Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs(lume): restore CLI, HTTP API, and install docs (Diátaxis)
Francesco Bonacciad5c593c7fea
diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdxnew file mode 100644index 0000000000..fae163db00--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx@@ -0,0 +1,53 @@+---+title: Install Lume+description: Installation instructions for the current version of the Lume CLI.+---++## Quickstart++Install and run a prebuilt macOS sandbox in two commands:++```bash+# Install Lume+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"+# Pull & start a macOS image+lume run macos-sequoia-vanilla:latest+```++<Callout title="Security Note">+ All prebuilt images use the default password `lume`. Change this immediately after your first+ login using the `passwd` command.+</Callout>++**System Requirements**:++- Apple Silicon Mac (M1, M2, M3, etc.)+- macOS 13.0 or later+- At least 8GB of RAM (16GB recommended)+- At least 50GB of free disk space++## Install with Script++Install with a single command:++```bash+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"+```++### Manual Start (No Background Service)++By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:++```bash+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"+```++<Callout title="Note">+ With this option, you'll need to manually start the Lume API service by running `lume serve` in+ your terminal whenever you need to use tools or libraries that rely on the Lume API (such as the+ Computer-Use Agent).+</Callout>++## Manual Download and Installation++You can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/cua/releases?q=lume&expanded=true), extract it, and install the package manually.diff --git a/docs/content/docs/how-to-guides/lume/meta.json b/docs/content/docs/how-to-guides/lume/meta.jsonnew file mode 100644index 0000000000..b060387bc5--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/meta.json@@ -0,0 +1 @@+{ "title": "Lume", "pages": ["install-lume"] }diff --git a/docs/content/docs/how-to-guides/meta.json b/docs/content/docs/how-to-guides/meta.jsonindex ec338b048b..9f12de433e 100644--- a/docs/content/docs/how-to-guides/meta.json+++ b/docs/content/docs/how-to-guides/meta.json@@ -1 +1,13 @@-{ "title": "How-to guides", "icon": "Wrench", "pages": ["index", "driver", "recipes", "sandbox", "skills", "agent-context"] }+{+ "title": "How-to guides",+ "icon": "Wrench",+ "pages": [+ "index",+ "driver",+ "recipes",+ "sandbox",+ "lume",+ "skills",+ "agent-context"+ ]+}diff --git a/docs/content/docs/reference/lume/cli.mdx b/docs/content/docs/reference/lume/cli.mdxnew file mode 100644index 0000000000..a98b2ed82a--- /dev/null+++ b/docs/content/docs/reference/lume/cli.mdx@@ -0,0 +1,238 @@+---+title: Lume CLI Reference+description: Command Line Interface reference for Lume+---++import { Callout } from 'fumadocs-ui/components/callout';++Once installed, you can start using Lume with these common workflows:++### Run a Prebuilt VM++```bash+# Run a macOS Sequoia VM+lume run macos-sequoia-vanilla:latest++# Run an Ubuntu VM+lume run ubuntu-noble-vanilla:latest+```++<Callout>+ We provide [prebuilt VM images](https://github.com/trycua/cua/tree/main/libs/lume) in our [ghcr+ registry](https://github.com/orgs/trycua/packages).+</Callout>++### Create a Custom VM++```bash+# Create a new macOS VM+lume create my-macos-vm --cpu 4 --memory 8GB --disk-size 50GB++# Create a Linux VM+lume create my-linux-vm --os linux --cpu 2 --memory 4GB+```++<Callout title="Disk Space">+The actual disk space used by sparse images will be much lower than the logical size listed. You can resize VM disks after creation using `lume set <name> --disk-size <size>`.+</Callout>++## VM Management++lume create <name>+Create a new macOS or Linux virtual machine.++**Options:**++- `--os <os>` - Operating system to install (macOS or linux, default: macOS)+- `--cpu <cores>` - Number of CPU cores (default: 4)+- `--memory <size>` - Memory size, e.g., 8GB (default: 4GB)+- `--disk-size <size>` - Disk size, e.g., 50GB (default: 40GB)+- `--display <res>` - Display resolution (default: 1024x768)+- `--ipsw <path>` - Path to IPSW file or 'latest' for macOS VMs+- `--storage <name>` - VM storage location to use++**Examples:**++```bash+# Create macOS VM with custom specs+lume create my-mac --cpu 6 --memory 16GB --disk-size 100GB++# Create Linux VM+lume create my-ubuntu --os linux --cpu 2 --memory 8GB++# Create macOS VM with latest IPSW+lume create my-sequoia --ipsw latest+```++lume run <name>+Start and run a virtual machine.++**Options:**++- `--no-display` - Do not start the VNC client app+- `--shared-dir <dir>` - Share directory with VM (format: path[:ro|rw])+- `--mount <path>` - For Linux VMs only, attach a read-only disk image+- `--registry <url>` - Container registry URL (default: ghcr.io)+- `--organization <org>` - Organization to pull from (default: trycua)+- `--vnc-port <port>` - Port to use for the VNC server (default: 0 for auto-assign)+- `--recovery-mode <boolean>` - For macOS VMs only, start VM in recovery mode (default: false)+- `--storage <name>` - VM storage location to use++**Examples:**++```bash+# Run VM with shared directory+lume run my-vm --shared-dir /path/to/share:rw++# Run VM without display (headless)+lume run my-vm --no-display++# Run macOS VM in recovery mode+lume run my-mac --recovery-mode true+```++lume stop <name>+Stop a running virtual machine.++**Options:**++- `--storage <name>` - VM storage location to use++### lume delete <name>++Delete a virtual machine and its associated files.++**Options:**++- `--force` - Force deletion without confirmation+- `--storage <name>` - VM storage location to use++### lume clone <name> <new-name>++Create a copy of an existing virtual machine.++**Options:**++- `--source-storage <name>` - Source VM storage location+- `--dest-storage <name>` - Destination VM storage location++## VM Information and Configuration++### lume ls++List all virtual machines and their status.++### lume get <name>++Get detailed information about a specific virtual machine.++**Options:**++- `-f, --format <format>` - Output format (json|text)+- `--storage <name>` - VM storage location to use++### lume set <name>++Modify virtual machine configuration.++**Options:**++- `--cpu <cores>` - New number of CPU cores (e.g., 4)+- `--memory <size>` - New memory size (e.g., 8192MB or 8GB)+- `--disk-size <size>` - New disk size (e.g., 40960MB or 40GB)+- `--display <res>` - New display resolution in format WIDTHxHEIGHT (e.g., 1024x768)+- `--storage <name>` - VM storage location to use++**Examples:**++```bash+# Increase VM memory+lume set my-vm --memory 16GB++# Change display resolution+lume set my-vm --display 1920x1080++# Add more CPU cores+lume set my-vm --cpu 8+```++## Image Management++### lume images++List available macOS images in local cache.++### lume pull <image>++Download a VM image from a container registry.++**Options:**++- `--registry <url>` - Container registry URL (default: ghcr.io)+- `--organization <org>` - Organization to pull from (default: trycua)+- `--storage <name>` - VM storage location to use++### lume push <name> <image:tag>++Upload a VM image to a container registry.++**Options:**++- `--additional-tags <tags...>` - Additional tags to push the same image to+- `--registry <url>` - Container registry URL (default: ghcr.io)+- `--organization <org>` - Organization/user to push to (default: trycua)+- `--storage <name>` - VM storage location to use+- `--chunk-size-mb <size>` - Chunk size for disk image upload in MB (default: 512)+- `--verbose` - Enable verbose logging+- `--dry-run` - Prepare files and show plan without uploading+- `--reassemble` - Verify integrity by reassembling chunks (requires --dry-run)++### lume ipsw++Get the latest macOS restore image URL.++### lume prune++Remove cached images to free up disk space.++## Configuration++### lume config++Manage Lume configuration settings.++**Subcommands:**++##### Storage Management++- `lume config storage add <name> <path>` - Add a new VM storage location+- `lume config storage remove <name>` - Remove a VM storage location+- `lume config storage list` - List all VM storage locations+- `lume config storage default <name>` - Set the default VM storage location++##### Cache Management++- `lume config cache get` - Get current cache directory+- `lume config cache set <path>` - Set cache directory++##### Image Caching++- `lume config caching get` - Show current caching status+- `lume config caching set <boolean>` - Enable or disable image caching++## API Server++### lume serve++Start the Lume API server for programmatic access.++**Options:**++- `--port <port>` - Port to listen on (default: 7777)++## Global Options++These options are available for all commands:++- `--help` - Show help information+- `--version` - Show version numberdiff --git a/docs/content/docs/reference/lume/http-api.mdx b/docs/content/docs/reference/lume/http-api.mdxnew file mode 100644index 0000000000..f908f85e20--- /dev/null+++ b/docs/content/docs/reference/lume/http-api.mdx@@ -0,0 +1,1260 @@+---+title: HTTP Server API+description: Lume exposes a local HTTP API server that listens at localhost for programmatic management of VMs.+---++import { Tabs, Tab } from 'fumadocs-ui/components/tabs';+import { Callout } from 'fumadocs-ui/components/callout';++## Default URL++```+http://localhost:7777+```++<Callout type="info">+ The HTTP API service runs on port `7777` by default. If you'd like to use a different port, pass+ the `--port` option during installation or when running `lume serve`.+</Callout>++## Endpoints++---++### Create VM++Create a new virtual machine.++`POST: /lume/vms`++#### Parameters++| Name | Type | Required | Description |+| -------- | ------- | -------- | ------------------------------------ |+| name | string | Yes | Name of the VM |+| os | string | Yes | Guest OS (`macOS`, `linux`, etc.) |+| cpu | integer | Yes | Number of CPU cores |+| memory | string | Yes | Memory size (e.g. `4GB`) |+| diskSize | string | Yes | Disk size (e.g. `64GB`) |+| display | string | No | Display resolution (e.g. `1024x768`) |+| ipsw | string | No | IPSW version (e.g. `latest`) |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "name": "lume_vm",+ "os": "macOS",+ "cpu": 2,+ "memory": "4GB",+ "diskSize": "64GB",+ "display": "1024x768",+ "ipsw": "latest",+ "storage": "ssd"+ }' \+ http://localhost:7777/lume/vms+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "name": "lume_vm",+ "os": "macOS",+ "cpu": 2,+ "memory": "4GB",+ "diskSize": "64GB",+ "display": "1024x768",+ "ipsw": "latest",+ "storage": "ssd"+}+r = requests.post("http://localhost:7777/lume/vms", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ name: 'lume_vm',+ os: 'macOS',+ cpu: 2,+ memory: '4GB',+ diskSize: '64GB',+ display: '1024x768',+ ipsw: 'latest',+ storage: 'ssd',+};++const res = await fetch('http://localhost:7777/lume/vms', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### Run VM++Run a virtual machine instance.++`POST: /lume/vms/:name/run`++#### Parameters++| Name | Type | Required | Description |+| ----------------- | --------------- | -------- | --------------------------------------------------- |+| noDisplay | boolean | No | If true, do not start VNC client |+| sharedDirectories | array of object | No | List of shared directories (`hostPath`, `readOnly`) |+| recoveryMode | boolean | No | Start in recovery mode |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+# Basic run+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ http://localhost:7777/lume/vms/my-vm-name/run++# Run with VNC client started and shared directory+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "noDisplay": false,+ "sharedDirectories": [+ {+ "hostPath": "~/Projects",+ "readOnly": false+ }+ ],+ "recoveryMode": false,+ "storage": "ssd"+ }' \+ http://localhost:7777/lume/vms/lume_vm/run+```++ </Tab>+ <Tab value="Python">++```python+import requests++# Basic run+r = requests.post("http://localhost:7777/lume/vms/my-vm-name/run", timeout=50)+print(r.json())++# With VNC and shared directory+payload = {+ "noDisplay": False,+ "sharedDirectories": [+ {"hostPath": "~/Projects", "readOnly": False}+ ],+ "recoveryMode": False,+ "storage": "ssd"+}+r = requests.post("http://localhost:7777/lume/vms/lume_vm/run", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+// Basic run+let res = await fetch('http://localhost:7777/lume/vms/my-vm-name/run', {+ method: 'POST',+});+console.log(await res.json());++// With VNC and shared directory+const payload = {+ noDisplay: false,+ sharedDirectories: [{ hostPath: '~/Projects', readOnly: false }],+ recoveryMode: false,+ storage: 'ssd',+};+res = await fetch('http://localhost:7777/lume/vms/lume_vm/run', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### List VMs++List all virtual machines.++`GET: /lume/vms`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/vms+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.get("http://localhost:7777/lume/vms", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/vms');+console.log(await res.json());+```++ </Tab>+</Tabs>++```json+[+ {+ "name": "my-vm",+ "state": "stopped",+ "os": "macOS",+ "cpu": 2,+ "memory": "4GB",+ "diskSize": "64GB"+ },+ {+ "name": "my-vm-2",+ "state": "stopped",+ "os": "linux",+ "cpu": 2,+ "memory": "4GB",+ "diskSize": "64GB"+ }+]+```++---++### Get VM Details++Get details for a specific virtual machine.++`GET: /lume/vms/:name`++#### Parameters++| Name | Type | Required | Description |+| ------- | ------ | -------- | -------------------------- |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+# Basic get+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/vms/lume_vm++# Get with specific storage+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/vms/lume_vm?storage=ssd+```++ </Tab>+ <Tab value="Python">++```python+import requests++# Basic get+details = requests.get("http://localhost:7777/lume/vms/lume_vm", timeout=50)+print(details.json())++# Get with specific storage+details = requests.get("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50)+print(details.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+// Basic get+let res = await fetch('http://localhost:7777/lume/vms/lume_vm');+console.log(await res.json());++// Get with specific storage+res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd');+console.log(await res.json());+```++ </Tab>+</Tabs>++```json+{+ "name": "lume_vm",+ "state": "stopped",+ "os": "macOS",+ "cpu": 2,+ "memory": "4GB",+ "diskSize": "64GB",+ "display": "1024x768",+ "ipAddress": "192.168.65.2",+ "vncPort": 5900,+ "sharedDirectories": [+ {+ "hostPath": "~/Projects",+ "readOnly": false,+ "tag": "com.apple.virtio-fs.automount"+ }+ ]+}+```++---++### Update VM Configuration++Update the configuration of a virtual machine.++`PATCH: /lume/vms/:name`++#### Parameters++| Name | Type | Required | Description |+| -------- | ------- | -------- | ------------------------------------- |+| cpu | integer | No | Number of CPU cores |+| memory | string | No | Memory size (e.g. `8GB`) |+| diskSize | string | No | Disk size (e.g. `100GB`) |+| display | string | No | Display resolution (e.g. `1920x1080`) |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X PATCH \+ -H "Content-Type: application/json" \+ -d '{+ "cpu": 4,+ "memory": "8GB",+ "diskSize": "100GB",+ "display": "1920x1080",+ "storage": "ssd"+ }' \+ http://localhost:7777/lume/vms/lume_vm+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "cpu": 4,+ "memory": "8GB",+ "diskSize": "100GB",+ "display": "1920x1080",+ "storage": "ssd"+}+r = requests.patch("http://localhost:7777/lume/vms/lume_vm", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ cpu: 4,+ memory: '8GB',+ diskSize: '100GB',+ display: '1920x1080',+ storage: 'ssd',+};+const res = await fetch('http://localhost:7777/lume/vms/lume_vm', {+ method: 'PATCH',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### Stop VM++Stop a running virtual machine.++`POST: /lume/vms/:name/stop`++#### Parameters++| Name | Type | Required | Description |+| ------- | ------ | -------- | -------------------------- |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+# Basic stop+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ http://localhost:7777/lume/vms/lume_vm/stop++# Stop with storage location specified+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd+```++ </Tab>+ <Tab value="Python">++```python+import requests++# Basic stop+r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", timeout=50)+print(r.json())++# Stop with storage location specified+r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", params={"storage": "ssd"}, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+// Basic stop+let res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop', {+ method: 'POST',+});+console.log(await res.json());++// Stop with storage location specified+res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd', {+ method: 'POST',+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### Delete VM++Delete a virtual machine instance.++`DELETE: /lume/vms/:name`++#### Parameters++| Name | Type | Required | Description |+| ------- | ------ | -------- | -------------------------- |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+# Basic delete+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X DELETE \+ http://localhost:7777/lume/vms/lume_vm++# Delete with specific storage+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X DELETE \+ http://localhost:7777/lume/vms/lume_vm?storage=ssd+```++ </Tab>+ <Tab value="Python">++```python+import requests++# Basic delete+r = requests.delete("http://localhost:7777/lume/vms/lume_vm", timeout=50)+print(r.status_code)++# Delete with specific storage+r = requests.delete("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50)+print(r.status_code)+```++ </Tab>+ <Tab value="TypeScript">++```typescript+// Basic delete+let res = await fetch('http://localhost:7777/lume/vms/lume_vm', {+ method: 'DELETE',+});+console.log(res.status);++// Delete with specific storage+res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd', {+ method: 'DELETE',+});+console.log(res.status);+```++ </Tab>+</Tabs>++---++### Clone VM++Clone an existing virtual machine.++`POST: /lume/vms/clone`++#### Parameters++| Name | Type | Required | Description |+| -------------- | ------ | -------- | ----------------------------------- |+| name | string | Yes | Source VM name |+| newName | string | Yes | New VM name |+| sourceLocation | string | No | Source storage location (`default`) |+| destLocation | string | No | Destination storage location |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "name": "source-vm",+ "newName": "cloned-vm",+ "sourceLocation": "default",+ "destLocation": "ssd"+ }' \+ http://localhost:7777/lume/vms/clone+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "name": "source-vm",+ "newName": "cloned-vm",+ "sourceLocation": "default",+ "destLocation": "ssd"+}+r = requests.post("http://localhost:7777/lume/vms/clone", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ name: 'source-vm',+ newName: 'cloned-vm',+ sourceLocation: 'default',+ destLocation: 'ssd',+};+const res = await fetch('http://localhost:7777/lume/vms/clone', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### Pull VM Image++Pull a VM image from a registry.++`POST: /lume/pull`++#### Parameters++| Name | Type | Required | Description |+| ------------ | ------ | -------- | ------------------------------------- |+| image | string | Yes | Image name (e.g. `macos-sequoia-...`) |+| name | string | No | VM name for the pulled image |+| registry | string | No | Registry host (e.g. `ghcr.io`) |+| organization | string | No | Organization name |+| storage | string | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "image": "macos-sequoia-vanilla:latest",+ "name": "my-vm-name",+ "registry": "ghcr.io",+ "organization": "trycua",+ "storage": "ssd"+ }' \+ http://localhost:7777/lume/pull+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "image": "macos-sequoia-vanilla:latest",+ "name": "my-vm-name",+ "registry": "ghcr.io",+ "organization": "trycua",+ "storage": "ssd"+}+r = requests.post("http://localhost:7777/lume/pull", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ image: 'macos-sequoia-vanilla:latest',+ name: 'my-vm-name',+ registry: 'ghcr.io',+ organization: 'trycua',+ storage: 'ssd',+};+const res = await fetch('http://localhost:7777/lume/pull', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### Push VM Image++Push a VM to a registry as an image (asynchronous operation).++`POST: /lume/vms/push`++#### Parameters++| Name | Type | Required | Description |+| ------------ | ----------- | -------- | ------------------------------------ |+| name | string | Yes | Local VM name to push |+| imageName | string | Yes | Image name in registry |+| tags | array | Yes | Image tags (e.g. `["latest", "v1"]`) |+| organization | string | Yes | Organization name |+| registry | string | No | Registry host (e.g. `ghcr.io`) |+| chunkSizeMb | integer | No | Chunk size in MB for upload |+| storage | string/null | No | Storage type (`ssd`, etc.) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "name": "my-local-vm",+ "imageName": "my-image",+ "tags": ["latest", "v1"],+ "organization": "my-org",+ "registry": "ghcr.io",+ "chunkSizeMb": 512,+ "storage": null+ }' \+ http://localhost:7777/lume/vms/push+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "name": "my-local-vm",+ "imageName": "my-image",+ "tags": ["latest", "v1"],+ "organization": "my-org",+ "registry": "ghcr.io",+ "chunkSizeMb": 512,+ "storage": None+}+r = requests.post("http://localhost:7777/lume/vms/push", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ name: 'my-local-vm',+ imageName: 'my-image',+ tags: ['latest', 'v1'],+ organization: 'my-org',+ registry: 'ghcr.io',+ chunkSizeMb: 512,+ storage: null,+};+const res = await fetch('http://localhost:7777/lume/vms/push', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++**Response (202 Accepted):**++```json+{+ "message": "Push initiated in background",+ "name": "my-local-vm",+ "imageName": "my-image",+ "tags": ["latest", "v1"]+}+```++---++### List Images++List available VM images.++`GET: /lume/images`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/images+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.get("http://localhost:7777/lume/images", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/images');+console.log(await res.json());+```++ </Tab>+</Tabs>++```json+{+ "local": ["macos-sequoia-xcode:latest", "macos-sequoia-vanilla:latest"]+}+```++---++### Prune Images++Remove unused VM images to free up disk space.++`POST: /lume/prune`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ http://localhost:7777/lume/prune+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.post("http://localhost:7777/lume/prune", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/prune', {+ method: 'POST',+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++### Get Latest IPSW URL++Get the URL for the latest macOS IPSW file.++`GET: /lume/ipsw`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/ipsw+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.get("http://localhost:7777/lume/ipsw", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/ipsw');+console.log(await res.json());+```++ </Tab>+</Tabs>++---++## Configuration Management++### Get Configuration++Get current Lume configuration settings.++`GET: /lume/config`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/config+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.get("http://localhost:7777/lume/config", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/config');+console.log(await res.json());+```++ </Tab>+</Tabs>++```json+{+ "homeDirectory": "~/.lume",+ "cacheDirectory": "~/.lume/cache",+ "cachingEnabled": true+}+```++### Update Configuration++Update Lume configuration settings.++`POST: /lume/config`++#### Parameters++| Name | Type | Required | Description |+| -------------- | ------- | -------- | ------------------------- |+| homeDirectory | string | No | Lume home directory path |+| cacheDirectory | string | No | Cache directory path |+| cachingEnabled | boolean | No | Enable or disable caching |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "homeDirectory": "~/custom/lume",+ "cacheDirectory": "~/custom/lume/cache",+ "cachingEnabled": true+ }' \+ http://localhost:7777/lume/config+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "homeDirectory": "~/custom/lume",+ "cacheDirectory": "~/custom/lume/cache",+ "cachingEnabled": True+}+r = requests.post("http://localhost:7777/lume/config", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ homeDirectory: '~/custom/lume',+ cacheDirectory: '~/custom/lume/cache',+ cachingEnabled: true,+};+const res = await fetch('http://localhost:7777/lume/config', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++---++## Storage Location Management++### Get VM Storage Locations++List all configured VM storage locations.++`GET: /lume/config/locations`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ http://localhost:7777/lume/config/locations+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.get("http://localhost:7777/lume/config/locations", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/config/locations');+console.log(await res.json());+```++ </Tab>+</Tabs>++```json+[+ {+ "name": "default",+ "path": "~/.lume/vms",+ "isDefault": true+ },+ {+ "name": "ssd",+ "path": "/Volumes/SSD/lume/vms",+ "isDefault": false+ }+]+```++### Add VM Storage Location++Add a new VM storage location.++`POST: /lume/config/locations`++#### Parameters++| Name | Type | Required | Description |+| ---- | ------ | -------- | ---------------------------- |+| name | string | Yes | Storage location name |+| path | string | Yes | File system path for storage |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ -H "Content-Type: application/json" \+ -d '{+ "name": "ssd",+ "path": "/Volumes/SSD/lume/vms"+ }' \+ http://localhost:7777/lume/config/locations+```++ </Tab>+ <Tab value="Python">++```python+import requests++payload = {+ "name": "ssd",+ "path": "/Volumes/SSD/lume/vms"+}+r = requests.post("http://localhost:7777/lume/config/locations", json=payload, timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const payload = {+ name: 'ssd',+ path: '/Volumes/SSD/lume/vms',+};+const res = await fetch('http://localhost:7777/lume/config/locations', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify(payload),+});+console.log(await res.json());+```++ </Tab>+</Tabs>++### Remove VM Storage Location++Remove a VM storage location.++`DELETE: /lume/config/locations/:name`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X DELETE \+ http://localhost:7777/lume/config/locations/ssd+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.delete("http://localhost:7777/lume/config/locations/ssd", timeout=50)+print(r.status_code)+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/config/locations/ssd', {+ method: 'DELETE',+});+console.log(res.status);+```++ </Tab>+</Tabs>++### Set Default VM Storage Location++Set a storage location as the default.++`POST: /lume/config/locations/default/:name`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">++```bash+curl --connect-timeout 6000 \+ --max-time 5000 \+ -X POST \+ http://localhost:7777/lume/config/locations/default/ssd+```++ </Tab>+ <Tab value="Python">++```python+import requests++r = requests.post("http://localhost:7777/lume/config/locations/default/ssd", timeout=50)+print(r.json())+```++ </Tab>+ <Tab value="TypeScript">++```typescript+const res = await fetch('http://localhost:7777/lume/config/locations/default/ssd', {+ method: 'POST',+});+console.log(await res.json());+```++ </Tab>+</Tabs>diff --git a/docs/content/docs/reference/lume/meta.json b/docs/content/docs/reference/lume/meta.jsonnew file mode 100644index 0000000000..79d91d6002--- /dev/null+++ b/docs/content/docs/reference/lume/meta.json@@ -0,0 +1 @@+{ "title": "Lume", "pages": ["cli", "http-api"] }diff --git a/docs/content/docs/reference/meta.json b/docs/content/docs/reference/meta.jsonindex 0ccc7d0d66..7317a8232d 100644--- a/docs/content/docs/reference/meta.json+++ b/docs/content/docs/reference/meta.json@@ -1 +1,11 @@-{ "title": "Reference", "icon": "BookText", "pages": ["index", "cua-driver", "sandbox-sdk", "docs-code-mcp"] }+{+ "title": "Reference",+ "icon": "BookText",+ "pages": [+ "index",+ "cua-driver",+ "lume",+ "sandbox-sdk",+ "docs-code-mcp"+ ]+}