Lume HTTP API Reference — VM Management Server

The Lume HTTP API is a REST server for managing macOS and Linux virtual machines programmatically. Any HTTP client — curl, Python, TypeScript, or your CI system — can call these endpoints. Documented against Lume 0.5.3.

Starting the server

lume serve              # Default port 7777
lume serve --port 8080  # Custom port

Base URL

http://localhost:7777

The Lume HTTP API has no authentication by default. It listens on localhost only. Exposing it on a public interface is not recommended without additional network-level controls.

VM Management

List all VMs

List all virtual machines managed by the local Lume instance. GET /lume/vms Query parameters:

storage

string

Filter results by named storage location.

curl
Python
TypeScript

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

import requests
response = requests.get("http://localhost:7777/lume/vms")
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms");
const data = await response.json();

Response codes: 200 Success — 400 Bad request

Get a VM

Get detailed information about a specific virtual machine. GET /lume/vms/:name Path parameters:

name

string

required

Name of the virtual machine.

Query parameters:

storage

string

VM storage location to use.

curl
Python
TypeScript

curl "http://localhost:7777/lume/vms/my-vm"

import requests
response = requests.get("http://localhost:7777/lume/vms/my-vm")
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms/my-vm");
const data = await response.json();

Response codes: 200 Success — 400 VM not found or invalid request

Create a VM

Create a new virtual machine. POST /lume/vms Request body:

name

string

required

Name for the new virtual machine.

string

required

Operating system: 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' (macOS VMs only).

storage

string

VM storage location to use.

curl
Python
TypeScript

curl -X POST "http://localhost:7777/lume/vms" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-vm",
    "os": "macOS",
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "100GB",
    "display": "1024x768"
  }'

import requests
data = {
    "name": "my-vm",
    "os": "macOS",
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "100GB",
    "display": "1024x768",
}
response = requests.post("http://localhost:7777/lume/vms", json=data)
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "my-vm",
    os: "macOS",
    cpu: 4,
    memory: "8GB",
    diskSize: "100GB",
    display: "1024x768",
  }),
});
const data = await response.json();

Response codes: 200 Created — 400 Invalid request or creation failed

Update a VM

Update CPU, memory, disk size, or display resolution for a stopped VM. PATCH /lume/vms/:name Path parameters:

name

string

required

Name of the VM to update.

Request body (all optional):

cpu

integer

New CPU core count.

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

Skip the macOS rollback backup. Default: false.

keepBackup

boolean

Keep rollback files after success. Default: false.

dryRun

boolean

Validate resize plan without modifying the disk. Default: false.

curl
Python
TypeScript

curl -X PATCH "http://localhost:7777/lume/vms/my-vm" \
  -H "Content-Type: application/json" \
  -d '{"cpu": 8, "memory": "16GB"}'

import requests
response = requests.patch(
    "http://localhost:7777/lume/vms/my-vm",
    json={"cpu": 8, "memory": "16GB"}
)
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms/my-vm", {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ cpu: 8, memory: "16GB" }),
});
const data = await response.json();

Response codes: 200 Updated — 400 Invalid settings or update failed

Delete a VM

Delete a virtual machine and all associated files. DELETE /lume/vms/:name Path parameters:

name

string

required

Name of the VM to delete.

Query parameters:

storage

string

VM storage location.

curl
Python
TypeScript

curl -X DELETE "http://localhost:7777/lume/vms/my-vm"

import requests
response = requests.delete("http://localhost:7777/lume/vms/my-vm")
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms/my-vm", {
  method: "DELETE",
});
const data = await response.json();

Response codes: 200 Deleted — 400 Not found or deletion failed

Clone a VM

Create a copy of an existing virtual machine. POST /lume/vms/clone

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.

curl
Python
TypeScript

curl -X POST "http://localhost:7777/lume/vms/clone" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-vm", "newName": "my-vm-clone"}'

import requests
response = requests.post(
    "http://localhost:7777/lume/vms/clone",
    json={"name": "my-vm", "newName": "my-vm-clone"}
)
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms/clone", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "my-vm", newName: "my-vm-clone" }),
});
const data = await response.json();

Response codes: 200 Cloned — 400 Clone failed

Start a VM

Start (boot) a virtual machine. POST /lume/vms/:name/run

name

string

required

Name of the VM to start.

Request body (all optional):

noDisplay

boolean

Run without opening a display. Default: false.

sharedDirectories

array

Directories to share with the VM.

recoveryMode

boolean

Boot in macOS recovery mode. Default: false.

storage

string

VM storage location.

clipboard

boolean

Enable bidirectional clipboard sync via SSH. Default: false.

curl
Python
TypeScript

curl -X POST "http://localhost:7777/lume/vms/my-vm/run" \
  -H "Content-Type: application/json" \
  -d '{"noDisplay": true}'

import requests
response = requests.post(
    "http://localhost:7777/lume/vms/my-vm/run",
    json={"noDisplay": True}
)
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms/my-vm/run", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ noDisplay: true }),
});
const data = await response.json();

Response codes: 202 Start initiated (async) — 400 Invalid request or VM not found

Stop a VM

Stop a running virtual machine. POST /lume/vms/:name/stop

name

string

required

Name of the VM to stop.

Request body (all optional):

storage

string

VM storage location.

curl
Python
TypeScript

curl -X POST "http://localhost:7777/lume/vms/my-vm/stop" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests
response = requests.post("http://localhost:7777/lume/vms/my-vm/stop", json={})
print(response.json())

const response = await fetch("http://localhost:7777/lume/vms/my-vm/stop", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();

Response codes: 200 Stopped — 400 Stop failed

Image Management

List cached images

List available VM images from the local cache. GET /lume/images

organization

string

default:"trycua"

Organization to list images for.

curl
Python
TypeScript

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

import requests
response = requests.get("http://localhost:7777/lume/images")
print(response.json())

const response = await fetch("http://localhost:7777/lume/images");
const data = await response.json();

Response codes: 200 Success — 400 Failed to list images

Get IPSW URL

Get the latest macOS restore image (IPSW) URL for the current hardware. GET /lume/ipsw

curl
Python
TypeScript

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

import requests
response = requests.get("http://localhost:7777/lume/ipsw")
print(response.json())

const response = await fetch("http://localhost:7777/lume/ipsw");
const data = await response.json();

Response codes: 200 Success — 400 Failed to get IPSW URL

Pull an image

Pull a VM image from an OCI-compatible container registry. POST /lume/pull

image

string

required

Image reference in name:tag format.

name

string

Name for the resulting VM.

registry

string

default:"ghcr.io"

Container registry URL.

organization

string

default:"trycua"

Organization to pull from.

storage

string

VM storage location.

curl
Python
TypeScript

curl -X POST "http://localhost:7777/lume/pull" \
  -H "Content-Type: application/json" \
  -d '{"image": "macos-tahoe-vanilla:latest"}'

import requests
response = requests.post(
    "http://localhost:7777/lume/pull",
    json={"image": "macos-tahoe-vanilla:latest"}
)
print(response.json())

const response = await fetch("http://localhost:7777/lume/pull", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ image: "macos-tahoe-vanilla:latest" }),
});
const data = await response.json();

Response codes: 200 Pulled — 400 Pull failed

Push an image

Push a local VM image to a container registry. POST /lume/vms/push

name

string

required

Name of the local VM to push.

imageName

string

required

Base name for the image in the registry.

Prune cached images

Remove cached images to free up disk space. POST /lume/prune

curl
Python
TypeScript

curl -X POST "http://localhost:7777/lume/prune"

import requests
response = requests.post("http://localhost:7777/lume/prune")
print(response.json())

const response = await fetch("http://localhost:7777/lume/prune", {
  method: "POST",
});
const data = await response.json();

Response codes: 200 Pruned — 400 Prune failed

Configuration

Get configuration

Get current Lume configuration. GET /lume/config

curl
Python
TypeScript

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

import requests
response = requests.get("http://localhost:7777/lume/config")
print(response.json())

const response = await fetch("http://localhost:7777/lume/config");
const data = await response.json();

Response codes: 200 Success — 400 Failed to get config

Update configuration

Update Lume configuration settings. POST /lume/config

homeDirectory

string

VM home directory path.

cacheDirectory

string

Cache directory path.

cachingEnabled

boolean

Enable or disable image caching.

Response codes: 200 Updated — 400 Invalid request

Storage Locations

List storage locations

GET /lume/config/locations Response codes: 200 Success — 400 Failed

Add a storage location

POST /lume/config/locations

name

string

required

Storage location name.

path

string

required

Path to the storage directory.

Response codes: 200 Added — 400 Already exists or invalid

Remove a storage location

DELETE /lume/config/locations/:name

name

string

required

Name of the storage location to remove.

Response codes: 200 Removed — 400 Not found or cannot remove

Set default storage location

POST /lume/config/locations/default/:name

name

string

required

Name of the location to set as default.

Response codes: 200 Set — 400 Not found

Logs

Retrieve server logs

GET /lume/logs

type

string

default:"all"

Log type: info, error, or all.

lines

integer

Number of lines to return from the end of the log file.

curl
Python
TypeScript

curl "http://localhost:7777/lume/logs?type=error&lines=50"

import requests
response = requests.get(
    "http://localhost:7777/lume/logs",
    params={"type": "error", "lines": 50}
)
print(response.json())

const response = await fetch(
  "http://localhost:7777/lume/logs?type=error&lines=50"
);
const data = await response.json();

Response codes: 200 Success — 400 Failed to read logs

Cua Driver

Sandbox SDK

Lume

Cua Bench

Lume HTTP API Reference — VM Management Server

Starting the server

Base URL

VM Management

List all VMs

Get a VM

Create a VM

Update a VM

Delete a VM

Clone a VM

Start a VM

Stop a VM

Image Management

List cached images

Get IPSW URL

Pull an image

Push an image

Prune cached images

Configuration

Get configuration

Update configuration

Storage Locations

List storage locations

Add a storage location

Remove a storage location

Set default storage location

Logs

Retrieve server logs

Build docs developers (and LLMs) love

Cua Driver

Sandbox SDK

Lume

Cua Bench

Documentation Index

​Starting the server

​Base URL

​VM Management

​List all VMs

​Get a VM

​Create a VM

​Update a VM

​Delete a VM

​Clone a VM

​Start a VM

​Stop a VM

​Image Management

​List cached images

​Get IPSW URL

​Pull an image

​Push an image

​Prune cached images

​Configuration

​Get configuration

​Update configuration

​Storage Locations

​List storage locations

​Add a storage location

​Remove a storage location

​Set default storage location

​Logs

​Retrieve server logs

Build docs developers (and LLMs) love

Starting the server

Base URL

VM Management

List all VMs

Get a VM

Create a VM

Update a VM

Delete a VM

Clone a VM

Start a VM

Stop a VM

Image Management

List cached images

Get IPSW URL

Pull an image

Push an image

Prune cached images

Configuration

Get configuration

Update configuration

Storage Locations

List storage locations

Add a storage location

Remove a storage location

Set default storage location

Logs

Retrieve server logs