HTTP API and MCP tools
Every endpoint of the Lume HTTP API server and every tool of its MCP server (lume serve).
HTTP API for managing macOS and Linux virtual machines
Default URL#
http://localhost:7777
Start the server with lume serve or specify a custom port with lume serve --port <port>.
VM Management#
List all virtual machines#
GET /lume/vmsParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
storage | query | string | Filter by storage location name. |
Example request
curl "http://localhost:7777/lume/vms"Response
200: Success.400: Bad request.
Get detailed information about a specific virtual machine#
GET /lume/vms/:nameParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM. |
storage | query | string | VM storage location to use. |
Example request
curl "http://localhost:7777/lume/vms/my-vm"Response
200: Success (while an async pull runs, only name, status "pulling", downloadProgress, downloadedBytes, totalBytes and bytesPerSecond).400: VM not found, invalid request, or the async pull failed.
Create a new virtual machine#
POST /lume/vmsRequest body
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | Name for the virtual machine. |
os | string | required | Operating system to install (macOS or linux). |
cpu | integer | required | Number of CPU cores. |
memory | string | required | Memory size (e.g., 8GB). |
diskSize | string | required | Disk size (e.g., 50GB). |
display | string | required | Display resolution (e.g., 1024x768). |
ipsw | string | Path to IPSW file or 'latest' for macOS VMs. | |
storage | string | VM storage location to use. |
Example request
curl -X POST "http://localhost:7777/lume/vms" \
-H "Content-Type: application/json" \
-d '{
"name": "my-vm",
"os": "macOS",
"cpu": 4,
"memory": "8GB",
"diskSize": "50GB",
"display": "1024x768"
}'Response
200: VM created successfully.400: Invalid request body or VM creation failed.
Delete a virtual machine and its associated files#
DELETE /lume/vms/:nameParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM to delete. |
storage | query | string | VM storage location. |
Example request
curl -X DELETE "http://localhost:7777/lume/vms/my-vm"Response
200: VM deleted successfully.400: VM not found or deletion failed.
Create a copy of an existing virtual machine#
POST /lume/vms/cloneRequest body
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the source VM. |
newName | string | required | Name for the cloned VM. |
sourceLocation | string | Source VM storage location. | |
destLocation | string | Destination VM storage location. | |
withSavedState | boolean | false | Clone the source's saved machine state too (see suspend): the clone keeps the source's MAC address and machine identifier, which the state is bound to, and its first run resumes the saved guest. |
Example request
curl -X POST "http://localhost:7777/lume/vms/clone" \
-H "Content-Type: application/json" \
-d '{
"name": "my-vm",
"newName": "example"
}'Response
200: VM cloned successfully.400: Clone operation failed.
Update virtual machine configuration settings#
PATCH /lume/vms/:nameParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM to update. |
Request body
| Field | Type | Default | Description |
|---|---|---|---|
cpu | integer | New number of CPU cores. | |
memory | string | New memory size (e.g., 16GB). | |
diskSize | string | New total disk size (increase only). | |
display | string | New display resolution. | |
storage | string | VM storage location. | |
noBackup | boolean | false | Skip the macOS rollback backup. |
keepBackup | boolean | false | Keep rollback files after success. |
dryRun | boolean | false | Validate the resize plan without modifying the disk. |
Example request
curl -X PATCH "http://localhost:7777/lume/vms/my-vm" \
-H "Content-Type: application/json" \
-d '{}'Response
200: Settings updated successfully.400: Invalid settings or update failed.
Start a virtual machine#
POST /lume/vms/:name/runParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM to start. |
Request body
| Field | Type | Default | Description |
|---|---|---|---|
noDisplay | boolean | false | Run without VNC display. |
sharedDirectories | array | Directories to share with the VM. | |
recoveryMode | boolean | false | Boot macOS VM in recovery mode. |
storage | string | VM storage location. | |
clipboard | boolean | false | Enable bidirectional clipboard sync via SSH (experimental). |
vnc | string | enabled | VNC server policy: 'enabled' or 'disabled'. 'disabled' requires noDisplay=true, starts no VNC listener, and reports a null vncUrl. |
forwards | array | Guest ports to publish on host loopback ports over a virtio socket device, through Cua's guest vsock agent. GET reports the host ports under 'forwards' once the agent answers; these connections are not subject to macOS Local Network privacy or VPN routes. |
Example request
curl -X POST "http://localhost:7777/lume/vms/my-vm/run" \
-H "Content-Type: application/json" \
-d '{}'Response
202: VM start initiated (async operation).409: Host limit of running macOS guests reached.400: Invalid request or VM not found.
Stop a running virtual machine#
POST /lume/vms/:name/stopParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM to stop. |
Request body
| Field | Type | Default | Description |
|---|---|---|---|
storage | string | VM storage location. |
Example request
curl -X POST "http://localhost:7777/lume/vms/my-vm/stop" \
-H "Content-Type: application/json" \
-d '{}'Response
200: VM stopped successfully.400: Stop operation failed.
Suspend a running virtual machine to disk (its next run resumes it)#
POST /lume/vms/:name/suspendParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM to suspend. |
Example request
curl -X POST "http://localhost:7777/lume/vms/my-vm/suspend"Response
200: The VM's memory and device state were saved next to its disk (macOS 14 or later) and the VM stopped; a run resumes it, a cold boot discards the state.400: The VM does not run in this lume serve, or the save failed (the VM keeps running).
Rename a virtual machine, running or stopped#
POST /lume/vms/:name/renameParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the VM to rename. |
Request body
| Field | Type | Default | Description |
|---|---|---|---|
newName | string | required | The VM's new name. |
storage | string | VM storage location. |
Example request
curl -X POST "http://localhost:7777/lume/vms/my-vm/rename" \
-H "Content-Type: application/json" \
-d '{
"newName": "example"
}'Response
200: VM renamed (a running VM keeps running).400: The name is taken or invalid, or the VM runs in another process than this lume serve.
Image Management#
List available images from local cache#
GET /lume/imagesParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
organization | query | string | Organization to list images for (default: trycua). |
Example request
curl "http://localhost:7777/lume/images"Response
200: Success.400: Failed to list images.
Get the latest macOS restore image (IPSW) URL#
GET /lume/ipswExample request
curl "http://localhost:7777/lume/ipsw"Response
200: Success.400: Failed to get IPSW URL.
Pull a VM image from a container registry#
POST /lume/pullRequest body
| Field | Type | Default | Description |
|---|---|---|---|
image | string | required | Image to pull (format: name:tag). |
name | string | Name for the resulting VM. | |
registry | string | ghcr.io | Container registry URL. |
organization | string | trycua | Organization to pull from. |
storage | string | VM storage location. |
Example request
curl -X POST "http://localhost:7777/lume/pull" \
-H "Content-Type: application/json" \
-d '{
"image": "macos-tahoe-vanilla:latest"
}'Response
200: Image pulled successfully.400: Pull operation failed.
Start a background pull#
POST /lume/pull/startRequest body
| Field | Type | Default | Description |
|---|---|---|---|
image | string | required | Image to pull (format: name:tag). |
name | string | Name for the resulting VM. | |
registry | string | ghcr.io | Container registry URL. |
organization | string | trycua | Organization to pull from. |
storage | string | VM storage location. |
Example request
curl -X POST "http://localhost:7777/lume/pull/start" \
-H "Content-Type: application/json" \
-d '{
"image": "macos-tahoe-vanilla:latest"
}'Response
202: Pull started or already in progress.400: Invalid request body.
Cancel a background pull#
POST /lume/pull/cancelRequest body
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | VM name of the pull to cancel. |
Example request
curl -X POST "http://localhost:7777/lume/pull/cancel" \
-H "Content-Type: application/json" \
-d '{
"name": "my-vm"
}'Response
200: The pull stopped and was cleaned up.400: Invalid request body.404: No background pull in progress for the name (for example it already finished or was cancelled).500: The pull did not stop within 30 seconds.
Push a VM image to a container registry#
POST /lume/vms/pushRequest body
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the local VM to push. |
imageName | string | required | Base name for the image in the registry. |
tags | array | required | List of tags to push. |
registry | string | ghcr.io | Container registry URL. |
organization | string | trycua | Organization to push to. |
storage | string | VM storage location. | |
chunkSizeMb | integer | 512 | Chunk size for upload in MB. |
Example request
curl -X POST "http://localhost:7777/lume/vms/push" \
-H "Content-Type: application/json" \
-d '{
"name": "my-vm",
"imageName": "example",
"tags": [
"latest"
]
}'Response
202: Push initiated (async operation).400: Invalid request.
Remove cached images to free up disk space#
POST /lume/pruneExample request
curl -X POST "http://localhost:7777/lume/prune"Response
200: Images pruned successfully.400: Prune operation failed.
Configuration#
Get current Lume configuration settings#
GET /lume/configExample request
curl "http://localhost:7777/lume/config"Response
200: Success.400: Failed to get config.
Update Lume configuration settings#
POST /lume/configRequest body
| Field | Type | Default | Description |
|---|---|---|---|
homeDirectory | string | VM home directory path. | |
cacheDirectory | string | Cache directory path. | |
cachingEnabled | boolean | Enable or disable image caching. |
Example request
curl -X POST "http://localhost:7777/lume/config" \
-H "Content-Type: application/json" \
-d '{}'Response
200: Configuration updated successfully.400: Invalid request.
List all VM storage locations#
GET /lume/config/locationsExample request
curl "http://localhost:7777/lume/config/locations"Response
200: Success.400: Failed to get locations.
Add a new VM storage location#
POST /lume/config/locationsRequest body
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | Storage location name. |
path | string | required | Path to storage directory. |
Example request
curl -X POST "http://localhost:7777/lume/config/locations" \
-H "Content-Type: application/json" \
-d '{
"name": "my-vm",
"path": "/path/to/storage"
}'Response
200: Location added successfully.400: Invalid request or location already exists.
Remove a VM storage location#
DELETE /lume/config/locations/:nameParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the location to remove. |
Example request
curl -X DELETE "http://localhost:7777/lume/config/locations/my-vm"Response
200: Location removed successfully.400: Location not found or cannot be removed.
Set the default VM storage location#
POST /lume/config/locations/default/:nameParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
name | path | string | required | Name of the location to set as default. |
Example request
curl -X POST "http://localhost:7777/lume/config/locations/default/my-vm"Response
200: Default location set successfully.400: Location not found.
Logs#
Retrieve Lume server logs#
GET /lume/logsParameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
type | query | string | Log type: 'info', 'error', or 'all' (default: all). | |
lines | query | integer | Number of lines to return from end of log. |
Example request
curl "http://localhost:7777/lume/logs"Response
200: Success.400: Failed to read logs.
MCP tools#
lume serve --mcp serves these tools over stdio. See Connect an MCP client for client setup.
VM tools#
lume_list_vms#
List all virtual machines with their status, IP addresses, and resource allocation.
Effect: read-only, idempotent.
| Parameter | Type | Default | Description |
|---|---|---|---|
storage | string | Optional storage location name or path to filter VMs. |
lume_get_vm#
Get detailed information about a specific VM including IP address, VNC URL, and SSH availability.
Effect: read-only, idempotent.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the VM. |
storage | string | Optional storage location name or path. |
Example arguments
{"name":"<name>"}lume_run_vm#
Start a VM with optional shared directory for file access. The shared directory will be available at /Volumes/My Shared Files inside the VM.
Effect: mutating.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the VM to start. |
no_display | boolean | Run headless without VNC window (default: true). | |
shared_dir | string | Host directory path to share with the VM (appears at /Volumes/My Shared Files). | |
storage | string | Optional storage location name or path. | |
vnc | "enabled" | "disabled" | VNC server policy. 'disabled' starts no VNC listener and reports a null vncUrl (default: enabled). |
Example arguments
{"name":"<name>"}lume_stop_vm#
Stop a running VM gracefully.
Effect: mutating.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the VM to stop. |
storage | string | Optional storage location name or path. |
Example arguments
{"name":"<name>"}lume_clone_vm#
Clone a VM to create a copy. Useful for creating golden images for instant reset.
Effect: mutating.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the source VM to clone. |
new_name | string | required | Name for the cloned VM. |
Example arguments
{"name":"<name>","new_name":"<new_name>"}lume_delete_vm#
Delete a VM and all its associated files.
Effect: destructive.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Name of the VM to delete. |
storage | string | Optional storage location name or path. |
Example arguments
{"name":"<name>"}lume_create_vm#
Create a new macOS VM asynchronously. Returns immediately while the VM is being provisioned. Poll lume_list_vms or lume_get_vm to check progress (status will be 'provisioning' until complete).
Effect: mutating.
| Parameter | Type | Default | Description |
|---|---|---|---|
cpu | integer | Number of CPU cores (default: 4). | |
disk_size | string | Disk size, e.g., '100GB' (default: 100GB). | |
ipsw | string | Path to IPSW file or 'latest' to download (default: latest). | |
memory | string | Memory size, e.g., '8GB' (default: 8GB). | |
name | string | required | Name for the new VM. |
storage | string | Optional storage location name or path. | |
unattended | string | Unattended setup preset (e.g., 'tahoe', 'sequoia') for automatic macOS configuration. |
Example arguments
{"name":"<name>"}lume_resize_disk#
Grow a stopped VM's disk. For macOS VMs this preserves the paired RecoveryOS partition (relocating it to the new end of disk) and expands the main APFS container so future macOS updates keep working. Grow-only; the VM must be stopped; may take several minutes.
Effect: destructive.
| Parameter | Type | Default | Description |
|---|---|---|---|
disk_size | string | required | New disk size, e.g., '100GB'. Must be larger than the current size. |
dry_run | boolean | Validate and print the resize plan without modifying the disk. Default false. | |
keep_backup | boolean | Keep the rollback backup after a successful resize; cannot be combined with no_backup. Default false. | |
name | string | required | Name of the VM to resize. |
no_backup | boolean | Skip the pre-resize backup (faster, but no automatic rollback on failure). Default false. | |
storage | string | Optional storage location name or path. |
Example arguments
{"name":"<name>","disk_size":"<disk_size>"}Guest tools#
lume_exec#
Execute a command inside a running VM via SSH. Requires SSH to be enabled in the VM (default for VMs created with --unattended tahoe).
Effect: destructive.
| Parameter | Type | Default | Description |
|---|---|---|---|
command | string | required | Shell command to execute inside the VM. |
name | string | required | Name of the VM. |
password | string | SSH password (default: lume). | |
storage | string | Optional storage location name or path. | |
user | string | SSH username (default: lume). |
Example arguments
{"name":"<name>","command":"<command>"}Maintenance tools#
check_for_update#
Check the saved stable/nightly Lume channel for a release on GitHub. Returns current and selected channels. Read-only; never installs. Mirrors lume check-update --json.
Effect: read-only, idempotent.
No parameters.