API Reference

HTTP API reference for Lume server

HTTP API for managing macOS and Linux virtual machines

Documented against Lume 0.3.10. 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#

List all virtual machines

GET: /lume/vms

Parameters#

Name	Type	Required	Description
storage	string	No	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 detailed information about a specific virtual machine

GET: /lume/vms/:name

Parameters#

Name	Type	Required	Description
name	string	Yes	Name of the VM
storage	string	No	VM storage location to use

Example Request#

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

Response#

200: Success
400: VM not found or invalid request

Create a new virtual machine#

Create a new virtual machine

POST: /lume/vms

Request Body#

Name	Type	Required	Description
name	string	Yes	Name for the virtual machine
os	string	Yes	Operating system to install (macOS or linux)
cpu	integer	Yes	Number of CPU cores
memory	string	Yes	Memory size (e.g., 8GB)
diskSize	string	Yes	Disk size (e.g., 50GB)
display	string	Yes	Display resolution (e.g., 1024x768)
ipsw	string	No	Path to IPSW file or 'latest' for macOS VMs
storage	string	No	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 a virtual machine and its associated files

DELETE: /lume/vms/:name

Parameters#

Name	Type	Required	Description
name	string	Yes	Name of the VM to delete
storage	string	No	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#

Create a copy of an existing virtual machine

POST: /lume/vms/clone

Request Body#

Name	Type	Required	Description
name	string	Yes	Name of the source VM
newName	string	Yes	Name for the cloned VM
sourceLocation	string	No	Source VM storage location
destLocation	string	No	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#

Update virtual machine configuration settings

PATCH: /lume/vms/:name

Parameters#

Name	Type	Required	Description
name	string	Yes	Name of the VM to update

Request Body#

Name	Type	Required	Description
cpu	integer	No	New number of CPU cores
memory	string	No	New memory size (e.g., 16GB)
diskSize	string	No	New disk size (e.g., 100GB)
display	string	No	New display resolution
storage	string	No	VM storage location

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#

Start a virtual machine

POST: /lume/vms/:name/run

Parameters#

Name	Type	Required	Description
name	string	Yes	Name of the VM to start

Request Body#

Name	Type	Required	Description
noDisplay	boolean	No	Run without VNC display (default: false)
sharedDirectories	array	No	Directories to share with the VM
recoveryMode	boolean	No	Boot macOS VM in recovery mode (default: false)
storage	string	No	VM storage location
clipboard	boolean	No	Enable bidirectional clipboard sync via SSH (experimental) (default: false)

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#

Stop a running virtual machine

POST: /lume/vms/:name/stop

Parameters#

Name	Type	Required	Description
name	string	Yes	Name of the VM to stop

Request Body#

Name	Type	Required	Description
storage	string	No	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#

List available images from local cache

GET: /lume/images

Parameters#

Name	Type	Required	Description
organization	string	No	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 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#

Pull a VM image from a container registry

POST: /lume/pull

Request Body#

Name	Type	Required	Description
image	string	Yes	Image to pull (format: name:tag)
name	string	No	Name for the resulting VM
registry	string	No	Container registry URL (default: ghcr.io)
organization	string	No	Organization to pull from (default: trycua)
storage	string	No	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

Push a VM image to a container registry#

Push a VM image to a container registry

POST: /lume/vms/push

Request Body#

Name	Type	Required	Description
name	string	Yes	Name of the local VM to push
imageName	string	Yes	Base name for the image in the registry
tags	array	Yes	List of tags to push
registry	string	No	Container registry URL (default: ghcr.io)
organization	string	No	Organization to push to (default: trycua)
storage	string	No	VM storage location
chunkSizeMb	integer	No	Chunk size for upload in MB (default: 512)

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#

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

Update Lume configuration settings

POST: /lume/config

Request Body#

Name	Type	Required	Description
homeDirectory	string	No	VM home directory path
cacheDirectory	string	No	Cache directory path
cachingEnabled	boolean	No	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#

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#

Add a new VM storage location

POST: /lume/config/locations

Request Body#

Name	Type	Required	Description
name	string	Yes	Storage location name
path	string	Yes	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#

Remove a VM storage location

DELETE: /lume/config/locations/:name

Parameters#

Name	Type	Required	Description
name	string	Yes	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#

Set the default VM storage location

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

Parameters#

Name	Type	Required	Description
name	string	Yes	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#

Retrieve Lume server logs

GET: /lume/logs

Parameters#

Name	Type	Required	Description
type	string	No	Log type: 'info', 'error', or 'all' (default: all)
lines	integer	No	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