Lume HTTP API Reference
HTTP API reference for Lume server
HTTP API for managing macOS and Linux virtual machines
Default URL
http://localhost:7777Start 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
| Name | Type | Required | Description |
|---|---|---|---|
| storage | string | No | Filter 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
| 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/{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
| 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"
}'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
| 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/{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
| 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"
}'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
| 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/{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
| 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 |
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
| 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/{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
| Name | Type | Required | Description |
|---|---|---|---|
| organization | string | No | Organization 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
| 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-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
| 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"
]
}'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
| 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 '{}'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
| 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"
}'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
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Name 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
| 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/{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
| 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"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?