HTTP API

Every endpoint of the Lume HTTP API server (lume serve).

HTTP API for managing macOS and Linux virtual machines

Documented against Lume 0.6.0. Run lume --version for your installed version.

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

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

Parameters

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

Request 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/:name

Parameters

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

Request 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.

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

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

Parameters

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.

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).
400: Invalid request or VM not found.

Stop a running virtual machine#

POST /lume/vms/:name/stop

Parameters

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.

Image Management#

List available images from local cache#

GET /lume/images

Parameters

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

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

Request 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/cancel

Request 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/push

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

Field	Type	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/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

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

Parameters

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

Parameters

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

Parameters

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.