Skip to main content
Machines are Ubuntu VMs provisioned on demand for your agent. Machine usage is measured in seconds weighted by size. Creating or resuming a machine reserves its auto-stop window; usage is settled against the time actually charged, and unused reservations are released when it stops. Choose the smallest size and shortest TTL that fits the task.
Machines must be available in your workspace to use these endpoints and tools. Contact support if you do not see this option.

List machines

GET /api/v1/machines returns all machines belonging to the agent’s token. Requires compute:read. The response wraps machine objects in a machines array. Single-machine operations return a machine object.
List machines

Response fields

string
Unique machine identifier.
string
Human-readable label set at creation.
string
Current lifecycle state: provisioning, ready, archiving, archived, error, deleting, or deleted. Run commands when the state is ready.
string
Machine size class (e.g. small).
number
Accumulated machine seconds weighted by size.
number
Weighted machine seconds currently reserved for this run.
string
Auto-stop deadline as an ISO 8601 timestamp, or null when no deadline is active.

Get one machine

GET /api/v1/machines/:id returns the current state and auto-stop time for a single machine. Requires compute:read.

Create a machine

POST /api/v1/machines provisions a new Ubuntu VM. Requires compute:run. The response is HTTP 202 while provisioning. Poll GET /api/v1/machines/:id until machine.state is ready before using it.
Create a machine

Request body

string
One of small (2 vCPU, 4 GB), default (4 vCPU, 8 GB), or large (8 vCPU, 16 GB). Their usage multipliers are 0.5, 1, and 2 respectively. Plans determine which sizes are available.
number
Auto-stop window in wall-clock seconds, at least 60 and defaulting to 3600. Your plan caps the maximum window. Unused reserved time is released after stopping.
string
Human-readable label for the machine. Useful for identifying it in the dashboard.
array
Up to 10 vault credential IDs to inject into the machine’s environment. Requires vault:use and credentials accessible to this agent and marked agent-readable. Organization keys cannot inject credentials. Values are omitted from the machine response but accessible to code running on the machine.

Stop a machine

POST /api/v1/machines/:id/stop requests a disk snapshot and stop. The machine moves through archiving to archived; unused reservations are released when stopping finishes. It can be restarted later with resume. Requires compute:run.

Resume a machine

POST /api/v1/machines/:id/resume restarts an archived machine from its last snapshot. Optional JSON fields are ttl_seconds, size, and env. The machine retains its configured credential IDs; this endpoint does not accept inject_credential_ids. Requires compute:run and any permissions needed to access credentials or an agent token held by the machine.

Delete a machine

DELETE /api/v1/machines/:id permanently deletes the machine and all its snapshots. This action cannot be undone. Requires compute:admin and the query parameter confirm=true.

MCP tools for machines

Stop machines as soon as your task completes. Check the resulting state and usage instead of assuming the initial stop request has already finished.