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/vms

Parameters

ParameterInTypeDefaultDescription
storagequerystringFilter 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/:name

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName of the VM.
storagequerystringVM 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/vms

Request body

FieldTypeDefaultDescription
namestringrequiredName for the virtual machine.
osstringrequiredOperating system to install (macOS or linux).
cpuintegerrequiredNumber of CPU cores.
memorystringrequiredMemory size (e.g., 8GB).
diskSizestringrequiredDisk size (e.g., 50GB).
displaystringrequiredDisplay resolution (e.g., 1024x768).
ipswstringPath to IPSW file or 'latest' for macOS VMs.
storagestringVM 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/:name

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName of the VM to delete.
storagequerystringVM 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/clone

Request body

FieldTypeDefaultDescription
namestringrequiredName of the source VM.
newNamestringrequiredName for the cloned VM.
sourceLocationstringSource VM storage location.
destLocationstringDestination VM storage location.
withSavedStatebooleanfalseClone 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/:name

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName of the VM to update.

Request body

FieldTypeDefaultDescription
cpuintegerNew number of CPU cores.
memorystringNew memory size (e.g., 16GB).
diskSizestringNew total disk size (increase only).
displaystringNew display resolution.
storagestringVM storage location.
noBackupbooleanfalseSkip the macOS rollback backup.
keepBackupbooleanfalseKeep rollback files after success.
dryRunbooleanfalseValidate 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/run

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName of the VM to start.

Request body

FieldTypeDefaultDescription
noDisplaybooleanfalseRun without VNC display.
sharedDirectoriesarrayDirectories to share with the VM.
recoveryModebooleanfalseBoot macOS VM in recovery mode.
storagestringVM storage location.
clipboardbooleanfalseEnable bidirectional clipboard sync via SSH (experimental).
vncstringenabledVNC server policy: 'enabled' or 'disabled'. 'disabled' requires noDisplay=true, starts no VNC listener, and reports a null vncUrl.
forwardsarrayGuest 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/stop

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName of the VM to stop.

Request body

FieldTypeDefaultDescription
storagestringVM 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/suspend

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName 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/rename

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName of the VM to rename.

Request body

FieldTypeDefaultDescription
newNamestringrequiredThe VM's new name.
storagestringVM 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/images

Parameters

ParameterInTypeDefaultDescription
organizationquerystringOrganization 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/ipsw

Example 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/pull

Request body

FieldTypeDefaultDescription
imagestringrequiredImage to pull (format: name:tag).
namestringName for the resulting VM.
registrystringghcr.ioContainer registry URL.
organizationstringtrycuaOrganization to pull from.
storagestringVM 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/start

Request body

FieldTypeDefaultDescription
imagestringrequiredImage to pull (format: name:tag).
namestringName for the resulting VM.
registrystringghcr.ioContainer registry URL.
organizationstringtrycuaOrganization to pull from.
storagestringVM 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/cancel

Request body

FieldTypeDefaultDescription
namestringrequiredVM 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/push

Request body

FieldTypeDefaultDescription
namestringrequiredName of the local VM to push.
imageNamestringrequiredBase name for the image in the registry.
tagsarrayrequiredList of tags to push.
registrystringghcr.ioContainer registry URL.
organizationstringtrycuaOrganization to push to.
storagestringVM storage location.
chunkSizeMbinteger512Chunk 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/prune

Example 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/config

Example request

curl "http://localhost:7777/lume/config"

Response

  • 200: Success.
  • 400: Failed to get config.

Update Lume configuration settings#

POST /lume/config

Request body

FieldTypeDefaultDescription
homeDirectorystringVM home directory path.
cacheDirectorystringCache directory path.
cachingEnabledbooleanEnable 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/locations

Example 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/locations

Request body

FieldTypeDefaultDescription
namestringrequiredStorage location name.
pathstringrequiredPath 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/:name

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName 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/:name

Parameters

ParameterInTypeDefaultDescription
namepathstringrequiredName 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/logs

Parameters

ParameterInTypeDefaultDescription
typequerystringLog type: 'info', 'error', or 'all' (default: all).
linesqueryintegerNumber 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.

ParameterTypeDefaultDescription
storagestringOptional 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.

ParameterTypeDefaultDescription
namestringrequiredName of the VM.
storagestringOptional 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.

ParameterTypeDefaultDescription
namestringrequiredName of the VM to start.
no_displaybooleanRun headless without VNC window (default: true).
shared_dirstringHost directory path to share with the VM (appears at /Volumes/My Shared Files).
storagestringOptional 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.

ParameterTypeDefaultDescription
namestringrequiredName of the VM to stop.
storagestringOptional 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.

ParameterTypeDefaultDescription
namestringrequiredName of the source VM to clone.
new_namestringrequiredName 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.

ParameterTypeDefaultDescription
namestringrequiredName of the VM to delete.
storagestringOptional 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.

ParameterTypeDefaultDescription
cpuintegerNumber of CPU cores (default: 4).
disk_sizestringDisk size, e.g., '100GB' (default: 100GB).
ipswstringPath to IPSW file or 'latest' to download (default: latest).
memorystringMemory size, e.g., '8GB' (default: 8GB).
namestringrequiredName for the new VM.
storagestringOptional storage location name or path.
unattendedstringUnattended 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.

ParameterTypeDefaultDescription
disk_sizestringrequiredNew disk size, e.g., '100GB'. Must be larger than the current size.
dry_runbooleanValidate and print the resize plan without modifying the disk. Default false.
keep_backupbooleanKeep the rollback backup after a successful resize; cannot be combined with no_backup. Default false.
namestringrequiredName of the VM to resize.
no_backupbooleanSkip the pre-resize backup (faster, but no automatic rollback on failure). Default false.
storagestringOptional 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.

ParameterTypeDefaultDescription
commandstringrequiredShell command to execute inside the VM.
namestringrequiredName of the VM.
passwordstringSSH password (default: lume).
storagestringOptional storage location name or path.
userstringSSH 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.