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. Every field has a default, so {} alone is a complete option and the browser reaches the open web. Drive it through the Browser routes.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 —
{} enables one on the open web, { "allowed_domains": ["*.example.com"] } scopes it; the full option object is above. Defaults to null, which disables the browser.string
Snapshot (
snp_…) to restore this computer from.Retrieve & list
Rename
PATCH /v1/computers/{id} → 200 OK. The name is the one field a computer has that you can change after creation; the body is strict, so any other field is 400 validation_failed. Returns the computer, and is recorded in the audit log as computer.updated.
string
required
1–200 characters.
Inspect
GET /v1/computers/{id}/inspect → 200 OK. What the computer is doing right now, from two sources: the provider’s own record of it (status, last_active_at, and home — the directory the fs/* calls are rooted in, or null when the provider does not confine them), and — only when that record says running — a single probe command run inside the machine. Inspecting never wakes a paused computer, so a paused or stopped one always answers with probe: null. A probe that cannot run or cannot be parsed is also probe: null, never an error; the numbers are a sample taken at sampled_at, not a metrics feed.
This call requires the computers:write scope. Despite the verb, it is not a plain read: the probe runs a command inside your machine, on compute you are billed for. Use GET /v1/computers/{id} for a read that does not touch the machine.
The home in the example below is illustrative. Read it from this call rather than hardcoding a path — it is what the machine’s image reports, and it can differ between computers.
Response
Execute a command
POST /v1/computers/{id}/exec → 200 OK. Runs a shell command and returns its output once it has finished. A paused computer is resumed first; a creating, failed, or destroyed one returns 409 with code computer_unavailable. Every run — by this route or the streamed one below — is recorded in the computer’s command history.
string
required
The command to run.
integer
Max runtime before the command is killed. Defaults to
30000.Response
Stream a command
POST /v1/computers/{id}/exec/stream → 200 OK, text/event-stream. The same run as exec, delivered as it happens: the body is a stream of Server-Sent Events whose data: lines are JSON frames — zero or more {"stdout": "…"} / {"stderr": "…"} chunks in the order the process produced them, then exactly one exit frame and the stream closes. command_id names the row the run was recorded as. Same body as exec; the same 404/409/400 refusals are returned as ordinary JSON errors before the stream opens. The SDK reads this as computers.execStream(id, command, { timeoutMs }), an async iterable of frames.
Response
Command history
GET /v1/computers/{id}/commands → 200 OK. Every command run on the computer through exec or exec/stream, newest first, cursor-paginated (Pagination). Each row keeps the first 65 536 characters of stdout and of stderr; truncated is true when either was cut. actor is the principal that ran it — an API key, a user, or the platform acting for a session. Commands the agent runs inside a session through its own tools are not listed here; they are in the session’s event stream.
This read requires the computers:write scope — the same scope that runs a command. It hands back what those commands printed, so it is not readable by a credential that could not have produced it.
Retention. Command output is stored for 30 days and then deleted; the rest of a computer’s history is deleted with the computer. It is stored exactly as the command produced it — nothing scans or redacts it — so a command that prints a credential stores that credential for the window. Print secrets to a file, or read them from the vault, rather than to stdout.
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.
type is file, directory, symlink or other; mode is the POSIX mode bits as an integer; modified_at is null when the filesystem does not report a time. The SDK returns the typed list as computers.listDir(id, path).
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.