API reference

List, inspect and control machines

Use stable IDs, respect states and let the host compose commands from trusted settings.

List machines

GET /v1/machines
{
  "machines": [{
    "id": "m-1a2b3c4d",
    "name": "Debian 13",
    "state": "off",
    "arch": "x86_64",
    "mem_mb": 4096,
    "cpus": 4,
    "startable": true
  }]
}

Get one

GET /v1/machines/{machine}

Use an ID or URL-escaped name. Duplicate names return 409 ambiguous.

Change settings

PATCH /v1/machines/{machine}
{ "name": "Build runner", "mem": "4096", "cpus": "4" }

Memory accepts 64–1,048,576 MB; processors accept 1–256. Resource changes require an off native machine.

Lifecycle action

POST /v1/machines/{machine}/{action}

Actions: start, shutdown, poweroff, pause, resume, reset.

Snapshots, disks and clones

PathOperation
GET/POST .../snapshotsList or create a named snapshot.
POST .../snapshots/{name}/restoreRestore it.
DELETE .../snapshots/{name}Delete it.
GET/POST .../disksList, create or attach disks.
POST .../cloneFull or linked clone while off.