running and stops the second you stop or delete it. Keep machines short-lived: choose the smallest size and shortest TTL that fits the task, and stop early to return unused time to your org’s allowance.
Machines must be enabled in your workspace before the compute endpoints and MCP tools are available. Contact support or check your plan’s feature flags 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.
List machines
Response fields
string
Unique machine identifier.
string
Human-readable label set at creation.
string
Current lifecycle state:
creating, ready, running, stopped, or deleted.string
Machine size class (e.g.
small).number
Total billable seconds accumulated so far.
string
ISO 8601 timestamp when the machine will be automatically stopped if still running.
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.
Create a machine
Request body
string
Machine size class. Start with
small for most tasks.number
Maximum lifetime in seconds before the machine is automatically stopped. The remaining window is returned to your org’s allowance when you stop early.
string
Human-readable label for the machine. Useful for identifying it in the dashboard.
array
IDs of vault credentials to inject into the machine’s environment. Values are placed directly on the machine — they are never returned to the caller or visible in the API response.
Stop a machine
POST /api/v1/machines/:id/stop snapshots the disk and stops the billing clock. The machine can be restarted later with resume. Requires compute:run.
Resume a machine
POST /api/v1/machines/:id/resume restarts a stopped machine from its last snapshot. Requires compute:run.
Delete a machine
DELETE /api/v1/machines/:id permanently deletes the machine and all its snapshots after confirmation. This action cannot be undone. Requires compute:admin.