computer_id. Those appear in this list named session {id}, so you can tell them from the ones you created; their lifecycle is the session’s, not yours.
The computer object
string
Unique id (e.g.
cmp_01H...).string
Always
computer.string
Human-readable name.
integer
Provisioned vCPU for a micro-VM (1–16).
integer
Provisioned memory in MiB (128–65536).
integer
Root disk size in GiB.
object
Browser configuration, or
null if disabled.object | null
Attached persistent volume. Always
null — a volume separate from the boot disk is not provisioned today; size the root disk with disk_gb.string | null
Snapshot this computer was restored from, if any.
string
Creation timestamp.
Lifecycle
Create a computer
POST /v1/computers → 202 Accepted. Provisioning is asynchronous: the response returns immediately with status: "creating". Wait for readiness before using the computer: poll GET /v1/computers/{id} until status is running. There is no computer lifecycle event to subscribe to — the event stream is session-scoped. If provisioning fails the computer moves to failed, and calls that need a live machine return 409 with code computer_unavailable.
string
Human-readable name. Defaults to
computer.integer
Provisioned vCPU. Defaults to
2.integer
Provisioned memory in MiB. Defaults to
4096.integer
Root disk size in GiB. Defaults to
5.object | null
Browser config —
{ "allowed_domains": ["*.example.com"] }. Defaults to null, which disables the browser.string
Snapshot (
snp_…) to restore this computer from.Retrieve & list
Execute a command
POST /v1/computers/{id}/exec → 200 OK. Runs a shell command and returns its output. The computer must be running; a creating, paused, or failed computer returns 409 with code computer_unavailable.
string
required
The command to run.
integer
Max runtime before the command is killed. Defaults to
30000.Response
Pause & resume
Pausing stops compute charges while retaining state. Resuming makes it usable again.Response
Snapshot
POST /v1/computers/{id}/snapshot → 201 Created. Captures the current filesystem state for fast restore. Pass the returned snapshot_id when creating a new computer.
Response
Filesystem
The disk is reached through the governedfs/* operations — there is no separate upload/download channel. Each takes an absolute path. See Filesystem for limits and encoding details.
Read a file
POST /v1/computers/{id}/fs/read → 200
string
required
Absolute path of the file to read.
string
text (default) or base64. Ask for base64 when the file is not valid UTF-8 — decoding binary as text substitutes U+FFFD and loses bytes silently.Response
Write a file
POST /v1/computers/{id}/fs/write → 200
string
required
Absolute path to write or overwrite.
string
required
The file contents, in the named encoding.
string
text (default) or base64 for binary payloads.List a directory
POST /v1/computers/{id}/fs/list → 200
string
required
Absolute path of the directory; lists its immediate children.
Create a directory
POST /v1/computers/{id}/fs/mkdir → 200
string
required
Absolute path to create; parents are created too (
mkdir -p).Remove a path
POST /v1/computers/{id}/fs/remove → 200
string
required
Absolute path to remove; directories are removed recursively (
rm -rf).Response
To persist an artifact beyond the computer’s lifetime, publish it to Files (Vetta object storage) rather than leaving it on the computer’s disk.
Destroy
DELETE /v1/computers/{id} → 200 OK. Permanently destroys the computer and its non-snapshotted disk.
Response
session {id} — cannot be
destroyed while that session can still run a turn: the call is computer_unavailable (409) naming
the session. Cancel the session to release the box, or let it finish; a session’s computer is
destroyed with it, and one left resting at idle is reclaimed after an hour of silence.