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
| Path | Operation |
|---|---|
GET/POST .../snapshots | List or create a named snapshot. |
POST .../snapshots/{name}/restore | Restore it. |
DELETE .../snapshots/{name} | Delete it. |
GET/POST .../disks | List, create or attach disks. |
POST .../clone | Full or linked clone while off. |