HTTP Server API

Default URL

http://localhost:7777

The HTTP API service runs on port 7777 by default. If you'd like to use a different port, pass the --port option during installation or when running lume serve.

Endpoints

Create VM

Create a new virtual machine.

POST: /lume/vms

Parameters

Name	Type	Required	Description
name	string	Yes	Name of the VM
os	string	Yes	Guest OS (`macOS`, `linux`, etc.)
cpu	integer	Yes	Number of CPU cores
memory	string	Yes	Memory size (e.g. `4GB`)
diskSize	string	Yes	Disk size (e.g. `64GB`)
display	string	No	Display resolution (e.g. `1024x768`)
ipsw	string	No	IPSW version (e.g. `latest`)
storage	string	No	Storage type (`ssd`, etc.)

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lume_vm",
    "os": "macOS",
    "cpu": 2,
    "memory": "4GB",
    "diskSize": "64GB",
    "display": "1024x768",
    "ipsw": "latest",
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/vms

import requests

payload = {
    "name": "lume_vm",
    "os": "macOS",
    "cpu": 2,
    "memory": "4GB",
    "diskSize": "64GB",
    "display": "1024x768",
    "ipsw": "latest",
    "storage": "ssd"
}
r = requests.post("http://localhost:7777/lume/vms", json=payload, timeout=50)
print(r.json())

const payload = {
  name: 'lume_vm',
  os: 'macOS',
  cpu: 2,
  memory: '4GB',
  diskSize: '64GB',
  display: '1024x768',
  ipsw: 'latest',
  storage: 'ssd',
};

const res = await fetch('http://localhost:7777/lume/vms', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Run VM

Run a virtual machine instance.

POST: /lume/vms/:name/run

Parameters

Name	Type	Required	Description
noDisplay	boolean	No	If true, do not start VNC client
sharedDirectories	array of object	No	List of shared directories (`hostPath`, `readOnly`)
recoveryMode	boolean	No	Start in recovery mode
storage	string	No	Storage type (`ssd`, etc.)

Example Request

# Basic run
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/vms/my-vm-name/run

# Run with VNC client started and shared directory
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "noDisplay": false,
    "sharedDirectories": [
      {
        "hostPath": "~/Projects",
        "readOnly": false
      }
    ],
    "recoveryMode": false,
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/vms/lume_vm/run

import requests

# Basic run
r = requests.post("http://localhost:7777/lume/vms/my-vm-name/run", timeout=50)
print(r.json())

# With VNC and shared directory
payload = {
    "noDisplay": False,
    "sharedDirectories": [
        {"hostPath": "~/Projects", "readOnly": False}
    ],
    "recoveryMode": False,
    "storage": "ssd"
}
r = requests.post("http://localhost:7777/lume/vms/lume_vm/run", json=payload, timeout=50)
print(r.json())

// Basic run
let res = await fetch('http://localhost:7777/lume/vms/my-vm-name/run', {
  method: 'POST',
});
console.log(await res.json());

// With VNC and shared directory
const payload = {
  noDisplay: false,
  sharedDirectories: [{ hostPath: '~/Projects', readOnly: false }],
  recoveryMode: false,
  storage: 'ssd',
};
res = await fetch('http://localhost:7777/lume/vms/lume_vm/run', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

List VMs

List all virtual machines.

GET: /lume/vms

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/vms

import requests

r = requests.get("http://localhost:7777/lume/vms", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/vms');
console.log(await res.json());

[
  {
    "name": "my-vm",
    "state": "stopped",
    "os": "macOS",
    "cpu": 2,
    "memory": "4GB",
    "diskSize": "64GB"
  },
  {
    "name": "my-vm-2",
    "state": "stopped",
    "os": "linux",
    "cpu": 2,
    "memory": "4GB",
    "diskSize": "64GB"
  }
]

Get VM Details

Get details for a specific virtual machine.

GET: /lume/vms/:name

Parameters

Name	Type	Required	Description
storage	string	No	Storage type (`ssd`, etc.)

Example Request

# Basic get
curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/vms/lume_vm

# Get with specific storage
curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/vms/lume_vm?storage=ssd

import requests

# Basic get
details = requests.get("http://localhost:7777/lume/vms/lume_vm", timeout=50)
print(details.json())

# Get with specific storage
details = requests.get("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50)
print(details.json())

// Basic get
let res = await fetch('http://localhost:7777/lume/vms/lume_vm');
console.log(await res.json());

// Get with specific storage
res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd');
console.log(await res.json());

{
  "name": "lume_vm",
  "state": "stopped",
  "os": "macOS",
  "cpu": 2,
  "memory": "4GB",
  "diskSize": "64GB",
  "display": "1024x768",
  "ipAddress": "192.168.65.2",
  "vncPort": 5900,
  "sharedDirectories": [
    {
      "hostPath": "~/Projects",
      "readOnly": false,
      "tag": "com.apple.virtio-fs.automount"
    }
  ]
}

Update VM Configuration

Update the configuration of a virtual machine.

PATCH: /lume/vms/:name

Parameters

Name	Type	Required	Description
cpu	integer	No	Number of CPU cores
memory	string	No	Memory size (e.g. `8GB`)
diskSize	string	No	Disk size (e.g. `100GB`)
display	string	No	Display resolution (e.g. `1920x1080`)
storage	string	No	Storage type (`ssd`, etc.)

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "100GB",
    "display": "1920x1080",
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/vms/lume_vm

import requests

payload = {
    "cpu": 4,
    "memory": "8GB",
    "diskSize": "100GB",
    "display": "1920x1080",
    "storage": "ssd"
}
r = requests.patch("http://localhost:7777/lume/vms/lume_vm", json=payload, timeout=50)
print(r.json())

const payload = {
  cpu: 4,
  memory: '8GB',
  diskSize: '100GB',
  display: '1920x1080',
  storage: 'ssd',
};
const res = await fetch('http://localhost:7777/lume/vms/lume_vm', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Stop VM

Stop a running virtual machine.

POST: /lume/vms/:name/stop

Parameters

Name	Type	Required	Description
storage	string	No	Storage type (`ssd`, etc.)

Example Request

# Basic stop
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/vms/lume_vm/stop

# Stop with storage location specified
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd

import requests

# Basic stop
r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", timeout=50)
print(r.json())

# Stop with storage location specified
r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", params={"storage": "ssd"}, timeout=50)
print(r.json())

// Basic stop
let res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop', {
  method: 'POST',
});
console.log(await res.json());

// Stop with storage location specified
res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd', {
  method: 'POST',
});
console.log(await res.json());

Delete VM

Delete a virtual machine instance.

DELETE: /lume/vms/:name

Parameters

Name	Type	Required	Description
storage	string	No	Storage type (`ssd`, etc.)

Example Request

# Basic delete
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X DELETE \
  http://localhost:7777/lume/vms/lume_vm

# Delete with specific storage
curl --connect-timeout 6000 \
  --max-time 5000 \
  -X DELETE \
  http://localhost:7777/lume/vms/lume_vm?storage=ssd

import requests

# Basic delete
r = requests.delete("http://localhost:7777/lume/vms/lume_vm", timeout=50)
print(r.status_code)

# Delete with specific storage
r = requests.delete("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50)
print(r.status_code)

// Basic delete
let res = await fetch('http://localhost:7777/lume/vms/lume_vm', {
  method: 'DELETE',
});
console.log(res.status);

// Delete with specific storage
res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd', {
  method: 'DELETE',
});
console.log(res.status);

Clone VM

Clone an existing virtual machine.

POST: /lume/vms/clone

Parameters

Name	Type	Required	Description
name	string	Yes	Source VM name
newName	string	Yes	New VM name
sourceLocation	string	No	Source storage location (`default`)
destLocation	string	No	Destination storage location

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "source-vm",
    "newName": "cloned-vm",
    "sourceLocation": "default",
    "destLocation": "ssd"
  }' \
  http://localhost:7777/lume/vms/clone

import requests

payload = {
    "name": "source-vm",
    "newName": "cloned-vm",
    "sourceLocation": "default",
    "destLocation": "ssd"
}
r = requests.post("http://localhost:7777/lume/vms/clone", json=payload, timeout=50)
print(r.json())

const payload = {
  name: 'source-vm',
  newName: 'cloned-vm',
  sourceLocation: 'default',
  destLocation: 'ssd',
};
const res = await fetch('http://localhost:7777/lume/vms/clone', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Pull VM Image

Pull a VM image from a registry.

POST: /lume/pull

Parameters

Name	Type	Required	Description
image	string	Yes	Image name (e.g. `macos-sequoia-...`)
name	string	No	VM name for the pulled image
registry	string	No	Registry host (e.g. `ghcr.io`)
organization	string	No	Organization name
storage	string	No	Storage type (`ssd`, etc.)

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "image": "macos-sequoia-vanilla:latest",
    "name": "my-vm-name",
    "registry": "ghcr.io",
    "organization": "trycua",
    "storage": "ssd"
  }' \
  http://localhost:7777/lume/pull

import requests

payload = {
    "image": "macos-sequoia-vanilla:latest",
    "name": "my-vm-name",
    "registry": "ghcr.io",
    "organization": "trycua",
    "storage": "ssd"
}
r = requests.post("http://localhost:7777/lume/pull", json=payload, timeout=50)
print(r.json())

const payload = {
  image: 'macos-sequoia-vanilla:latest',
  name: 'my-vm-name',
  registry: 'ghcr.io',
  organization: 'trycua',
  storage: 'ssd',
};
const res = await fetch('http://localhost:7777/lume/pull', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Push VM Image

Push a VM to a registry as an image (asynchronous operation).

POST: /lume/vms/push

Parameters

Name	Type	Required	Description
name	string	Yes	Local VM name to push
imageName	string	Yes	Image name in registry
tags	array	Yes	Image tags (e.g. `["latest", "v1"]`)
organization	string	Yes	Organization name
registry	string	No	Registry host (e.g. `ghcr.io`)
chunkSizeMb	integer	No	Chunk size in MB for upload
storage	string/null	No	Storage type (`ssd`, etc.)

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-local-vm", 
    "imageName": "my-image",
    "tags": ["latest", "v1"],
    "organization": "my-org", 
    "registry": "ghcr.io",
    "chunkSizeMb": 512,
    "storage": null 
  }' \
  http://localhost:7777/lume/vms/push

import requests

payload = {
    "name": "my-local-vm",
    "imageName": "my-image",
    "tags": ["latest", "v1"],
    "organization": "my-org",
    "registry": "ghcr.io",
    "chunkSizeMb": 512,
    "storage": None
}
r = requests.post("http://localhost:7777/lume/vms/push", json=payload, timeout=50)
print(r.json())

const payload = {
  name: 'my-local-vm',
  imageName: 'my-image',
  tags: ['latest', 'v1'],
  organization: 'my-org',
  registry: 'ghcr.io',
  chunkSizeMb: 512,
  storage: null,
};
const res = await fetch('http://localhost:7777/lume/vms/push', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Response (202 Accepted):

{
  "message": "Push initiated in background",
  "name": "my-local-vm",
  "imageName": "my-image",
  "tags": [
    "latest",
    "v1"
  ]
}

List Images

List available VM images.

GET: /lume/images

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/images

import requests

r = requests.get("http://localhost:7777/lume/images", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/images');
console.log(await res.json());

{
  "local": [
    "macos-sequoia-xcode:latest",
    "macos-sequoia-vanilla:latest"
  ]
}

Prune Images

Remove unused VM images to free up disk space.

POST: /lume/prune

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/prune

import requests

r = requests.post("http://localhost:7777/lume/prune", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/prune', {
  method: 'POST',
});
console.log(await res.json());

Get Latest IPSW URL

Get the URL for the latest macOS IPSW file.

GET: /lume/ipsw

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/ipsw

import requests

r = requests.get("http://localhost:7777/lume/ipsw", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/ipsw');
console.log(await res.json());

Configuration Management

Get Configuration

Get current Lume configuration settings.

GET: /lume/config

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/config

import requests

r = requests.get("http://localhost:7777/lume/config", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/config');
console.log(await res.json());

{
  "homeDirectory": "~/.lume",
  "cacheDirectory": "~/.lume/cache",
  "cachingEnabled": true
}

Update Configuration

Update Lume configuration settings.

POST: /lume/config

Parameters

Name	Type	Required	Description
homeDirectory	string	No	Lume home directory path
cacheDirectory	string	No	Cache directory path
cachingEnabled	boolean	No	Enable or disable caching

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "homeDirectory": "~/custom/lume",
    "cacheDirectory": "~/custom/lume/cache",
    "cachingEnabled": true
  }' \
  http://localhost:7777/lume/config

import requests

payload = {
    "homeDirectory": "~/custom/lume",
    "cacheDirectory": "~/custom/lume/cache",
    "cachingEnabled": True
}
r = requests.post("http://localhost:7777/lume/config", json=payload, timeout=50)
print(r.json())

const payload = {
  homeDirectory: '~/custom/lume',
  cacheDirectory: '~/custom/lume/cache',
  cachingEnabled: true,
};
const res = await fetch('http://localhost:7777/lume/config', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Storage Location Management

Get VM Storage Locations

List all configured VM storage locations.

GET: /lume/config/locations

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  http://localhost:7777/lume/config/locations

import requests

r = requests.get("http://localhost:7777/lume/config/locations", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/config/locations');
console.log(await res.json());

[
  {
    "name": "default",
    "path": "~/.lume/vms",
    "isDefault": true
  },
  {
    "name": "ssd",
    "path": "/Volumes/SSD/lume/vms",
    "isDefault": false
  }
]

Add VM Storage Location

Add a new VM storage location.

POST: /lume/config/locations

Parameters

Name	Type	Required	Description
name	string	Yes	Storage location name
path	string	Yes	File system path for storage

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ssd",
    "path": "/Volumes/SSD/lume/vms"
  }' \
  http://localhost:7777/lume/config/locations

import requests

payload = {
    "name": "ssd",
    "path": "/Volumes/SSD/lume/vms"
}
r = requests.post("http://localhost:7777/lume/config/locations", json=payload, timeout=50)
print(r.json())

const payload = {
  name: 'ssd',
  path: '/Volumes/SSD/lume/vms',
};
const res = await fetch('http://localhost:7777/lume/config/locations', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Remove VM Storage Location

Remove a VM storage location.

DELETE: /lume/config/locations/:name

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X DELETE \
  http://localhost:7777/lume/config/locations/ssd

import requests

r = requests.delete("http://localhost:7777/lume/config/locations/ssd", timeout=50)
print(r.status_code)

const res = await fetch('http://localhost:7777/lume/config/locations/ssd', {
  method: 'DELETE',
});
console.log(res.status);

Set Default VM Storage Location

Set a storage location as the default.

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

Example Request

curl --connect-timeout 6000 \
  --max-time 5000 \
  -X POST \
  http://localhost:7777/lume/config/locations/default/ssd

import requests

r = requests.post("http://localhost:7777/lume/config/locations/default/ssd", timeout=50)
print(r.json())

const res = await fetch('http://localhost:7777/lume/config/locations/default/ssd', {
  method: 'POST',
});
console.log(await res.json());

On this page