Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.mdx
new file mode 100644
index 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.json
new file mode 100644
index 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.json
index 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.mdx
new file mode 100644
index 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 &lt;name&gt;
+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 &lt;name&gt;
+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 &lt;name&gt;
+Stop a running virtual machine.
+
+**Options:**
+
+- `--storage <name>` - VM storage location to use
+
+### lume delete &lt;name&gt;
+
+Delete a virtual machine and its associated files.
+
+**Options:**
+
+- `--force` - Force deletion without confirmation
+- `--storage <name>` - VM storage location to use
+
+### lume clone &lt;name&gt; &lt;new-name&gt;
+
+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 &lt;name&gt;
+
+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 &lt;name&gt;
+
+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 &lt;image&gt;
+
+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 &lt;name&gt; &lt;image:tag&gt;
+
+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 number
diff --git a/docs/content/docs/reference/lume/http-api.mdx b/docs/content/docs/reference/lume/http-api.mdx
new file mode 100644
index 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.json
new file mode 100644
index 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.json
index 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"
+ ]
+}