LumeReference

Lume HTTP API Reference

HTTP API reference for Lume server

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

All virtual machines

List all virtual machines

GET: /lume/vms

Parameters

NameTypeRequiredDescription
storagestringNoFilter by storage location name

Example Request

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

  • 200: Success
  • 400: Bad request

Detailed information about a specific virtual machine

Get detailed information about a specific virtual machine

GET: /lume/vms/:name

Parameters

NameTypeRequiredDescription
namestringYesName of the VM
storagestringNoVM storage location to use

Example Request

curl "http://localhost:7777/lume/vms/{name}"
import requests

response = requests.get("http://localhost:7777/lume/vms/{name}")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/vms/${name}`);
const data = await response.json();

Response

  • 200: Success
  • 400: VM not found or invalid request

A new virtual machine

Create a new virtual machine

POST: /lume/vms

Request Body

NameTypeRequiredDescription
namestringYesName for the virtual machine
osstringYesOperating system to install (macOS or linux)
cpuintegerYesNumber of CPU cores
memorystringYesMemory size (e.g., 8GB)
diskSizestringYesDisk size (e.g., 50GB)
displaystringYesDisplay resolution (e.g., 1024x768)
ipswstringNoPath to IPSW file or 'latest' for macOS VMs
storagestringNoVM 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"
}'
import requests

data = {
    "name": "my-vm",
    "os": "macOS",
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "50GB",
    "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: "50GB",
    display: "1024x768",
  }),
});
const data = await response.json();

Response

  • 200: VM created successfully
  • 400: Invalid request body or VM creation failed

A virtual machine and its associated files

Delete a virtual machine and its associated files

DELETE: /lume/vms/:name

Parameters

NameTypeRequiredDescription
namestringYesName of the VM to delete
storagestringNoVM storage location

Example Request

curl -X DELETE "http://localhost:7777/lume/vms/{name}"
import requests

response = requests.delete("http://localhost:7777/lume/vms/{name}")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/vms/${name}`, {
  method: "DELETE",
});
const data = await response.json();

Response

  • 200: VM deleted successfully
  • 400: VM not found or deletion failed

A copy of an existing virtual machine

Create a copy of an existing virtual machine

POST: /lume/vms/clone

Request Body

NameTypeRequiredDescription
namestringYesName of the source VM
newNamestringYesName for the cloned VM
sourceLocationstringNoSource VM storage location
destLocationstringNoDestination 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"
}'
import requests

data = {
    "name": "my-vm",
    "newName": "example",
}

response = requests.post("http://localhost:7777/lume/vms/clone", json=data)
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: "example",
  }),
});
const data = await response.json();

Response

  • 200: VM cloned successfully
  • 400: Clone operation failed

Virtual machine configuration settings

Update virtual machine configuration settings

PATCH: /lume/vms/:name

Parameters

NameTypeRequiredDescription
namestringYesName of the VM to update

Request Body

NameTypeRequiredDescription
cpuintegerNoNew number of CPU cores
memorystringNoNew memory size (e.g., 16GB)
diskSizestringNoNew disk size (e.g., 100GB)
displaystringNoNew display resolution
storagestringNoVM storage location

Example Request

curl -X PATCH "http://localhost:7777/lume/vms/{name}" \
  -H "Content-Type: application/json" \
  -d '{}'
import requests

data = {
}

response = requests.patch("http://localhost:7777/lume/vms/{name}", json=data)
print(response.json())
const response = await fetch(`http://localhost:7777/lume/vms/${name}`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
  }),
});
const data = await response.json();

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

NameTypeRequiredDescription
namestringYesName of the VM to start

Request Body

NameTypeRequiredDescription
noDisplaybooleanNoRun without VNC display (default: false)
sharedDirectoriesarrayNoDirectories to share with the VM
recoveryModebooleanNoBoot macOS VM in recovery mode (default: false)
storagestringNoVM storage location

Example Request

curl -X POST "http://localhost:7777/lume/vms/{name}/run" \
  -H "Content-Type: application/json" \
  -d '{}'
import requests

data = {
}

response = requests.post("http://localhost:7777/lume/vms/{name}/run", json=data)
print(response.json())
const response = await fetch(`http://localhost:7777/lume/vms/${name}/run`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
  }),
});
const data = await response.json();

Response

  • 202: VM start initiated (async operation)
  • 400: Invalid request or VM not found

A running virtual machine

Stop a running virtual machine

POST: /lume/vms/:name/stop

Parameters

NameTypeRequiredDescription
namestringYesName of the VM to stop

Request Body

NameTypeRequiredDescription
storagestringNoVM storage location

Example Request

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

data = {
}

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

Response

  • 200: VM stopped successfully
  • 400: Stop operation failed

Image Management

Available images from local cache

List available images from local cache

GET: /lume/images

Parameters

NameTypeRequiredDescription
organizationstringNoOrganization to list images for (default: trycua)

Example Request

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

  • 200: Success
  • 400: Failed to list images

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

  • 200: Success
  • 400: Failed to get IPSW URL

A VM image from a container registry

Pull a VM image from a container registry

POST: /lume/pull

Request Body

NameTypeRequiredDescription
imagestringYesImage to pull (format: name:tag)
namestringNoName for the resulting VM
registrystringNoContainer registry URL (default: ghcr.io)
organizationstringNoOrganization to pull from (default: trycua)
storagestringNoVM storage location

Example Request

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

data = {
    "image": "macos-sequoia-vanilla:latest",
}

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

Response

  • 200: Image pulled successfully
  • 400: Pull operation failed

A VM image to a container registry

Push a VM image to a container registry

POST: /lume/vms/push

Request Body

NameTypeRequiredDescription
namestringYesName of the local VM to push
imageNamestringYesBase name for the image in the registry
tagsarrayYesList of tags to push
registrystringNoContainer registry URL (default: ghcr.io)
organizationstringNoOrganization to push to (default: trycua)
storagestringNoVM storage location
chunkSizeMbintegerNoChunk 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"
  ]
}'
import requests

data = {
    "name": "my-vm",
    "imageName": "example",
    "tags": ["latest"],
}

response = requests.post("http://localhost:7777/lume/vms/push", json=data)
print(response.json())
const response = await fetch(`http://localhost:7777/lume/vms/push`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "my-vm",
    imageName: "example",
    tags: ["latest"],
  }),
});
const data = await response.json();

Response

  • 202: Push initiated (async operation)
  • 400: Invalid request

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"
import requests

response = requests.post("http://localhost:7777/lume/prune")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/prune`);
const data = await response.json();

Response

  • 200: Images pruned successfully
  • 400: Prune operation failed

Configuration

Current Lume configuration settings

Get current Lume configuration settings

GET: /lume/config

Example Request

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

  • 200: Success
  • 400: Failed to get config

Lume configuration settings

Update Lume configuration settings

POST: /lume/config

Request Body

NameTypeRequiredDescription
homeDirectorystringNoVM home directory path
cacheDirectorystringNoCache directory path
cachingEnabledbooleanNoEnable or disable image caching

Example Request

curl -X POST "http://localhost:7777/lume/config" \
  -H "Content-Type: application/json" \
  -d '{}'
import requests

data = {
}

response = requests.post("http://localhost:7777/lume/config", json=data)
print(response.json())
const response = await fetch(`http://localhost:7777/lume/config`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
  }),
});
const data = await response.json();

Response

  • 200: Configuration updated successfully
  • 400: Invalid request

All VM storage locations

List all VM storage locations

GET: /lume/config/locations

Example Request

curl "http://localhost:7777/lume/config/locations"
import requests

response = requests.get("http://localhost:7777/lume/config/locations")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/config/locations`);
const data = await response.json();

Response

  • 200: Success
  • 400: Failed to get locations

A new VM storage location

Add a new VM storage location

POST: /lume/config/locations

Request Body

NameTypeRequiredDescription
namestringYesStorage location name
pathstringYesPath 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"
}'
import requests

data = {
    "name": "my-vm",
    "path": "/path/to/storage",
}

response = requests.post("http://localhost:7777/lume/config/locations", json=data)
print(response.json())
const response = await fetch(`http://localhost:7777/lume/config/locations`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "my-vm",
    path: "/path/to/storage",
  }),
});
const data = await response.json();

Response

  • 200: Location added successfully
  • 400: Invalid request or location already exists

A VM storage location

Remove a VM storage location

DELETE: /lume/config/locations/:name

Parameters

NameTypeRequiredDescription
namestringYesName of the location to remove

Example Request

curl -X DELETE "http://localhost:7777/lume/config/locations/{name}"
import requests

response = requests.delete("http://localhost:7777/lume/config/locations/{name}")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/config/locations/${name}`, {
  method: "DELETE",
});
const data = await response.json();

Response

  • 200: Location removed successfully
  • 400: Location not found or cannot be removed

The default VM storage location

Set the default VM storage location

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

Parameters

NameTypeRequiredDescription
namestringYesName of the location to set as default

Example Request

curl -X POST "http://localhost:7777/lume/config/locations/default/{name}"
import requests

response = requests.post("http://localhost:7777/lume/config/locations/default/{name}")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/config/locations/default/${name}`);
const data = await response.json();

Response

  • 200: Default location set successfully
  • 400: Location not found

Logs

Lume server logs

Retrieve Lume server logs

GET: /lume/logs

Parameters

NameTypeRequiredDescription
typestringNoLog type: 'info', 'error', or 'all' (default: all)
linesintegerNoNumber of lines to return from end of log

Example Request

curl "http://localhost:7777/lume/logs"
import requests

response = requests.get("http://localhost:7777/lume/logs")
print(response.json())
const response = await fetch(`http://localhost:7777/lume/logs`);
const data = await response.json();

Response

  • 200: Success
  • 400: Failed to read logs

Was this page helpful?