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 | null
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
An agent’s computer
computer, or null before any session has needed one. The machine under it can change: the files are kept, and after a change this route names the new cmp_ id. Another organization’s agent is 404 not_found. It takes the same scope as GET /v1/computers/{id}.
The agent looks after its computer: it starts it when a session needs it, pauses it after a few idle minutes, and removes it when the agent is deleted. Your files are kept across all of that. So some calls on an agent’s computer work differently:
A call that names an older machine of the agent is
409 computer_unavailable; read the agent’s computer for its current one. takeover on a computer you created is 409 too: nothing else uses it, so pause it instead.
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
Build a 3D model
POST /v1/computers/{id}/build-3d → 200 OK — scope computers:write. Runs a Python script that builds a model with build123d (cad, millimetres) or Blender (blender, metres) in this computer, checks it, renders previews and publishes the exports as files. The same program an agent’s build_3d tool runs (3D assets). The toolchain (about 1.9 GB) installs into the computer on first use, so the first call needs 3 GB free disk: create the computer with disk_gb of 10 or more. A 5 GB computer has about 2.1 GB free and is refused with 409 computer_unavailable. A paused computer is resumed first, as for exec.
string
required
cad: the script assigns result, a build123d shape. blender: the script builds the scene with bpy.string
required
The Python source, up to 200 KB.
string
required
Base name of the outputs,
[a-z0-9_-]{1,64}.string[]
Any of
step, stl, 3mf, glb, obj, blend. Default ["step", "stl"] for cad, ["glb"] for blender.object | false
{ views?: ("iso"|"front"|"top"|"side")[], size?: number } — up to 4 views (default ["iso"]), 256–1024 px (default 768). false renders nothing.boolean
Default
true. false runs the checks without publishing anything; the outputs are deleted from the computer when the call ends either way.integer
Seconds the script and its exports may run, 10–300. Default 120. Rendering the previews has its own allowance on top (about 40–60 s per view, more for larger sizes), so previews never eat into the script’s time.
Response
boolean
false when the script raised, a cad solid failed its checks, an STL or 3MF was withheld because the mesh is not watertight, or an output was over the file size limit (then nothing is published).object[]
The published exports. For
cad, STEP, STL and 3MF are published only when valid_solid and watertight are both true. For either engine, STL and 3MF are never published from a mesh that is not watertight.string[]
The rendered PNGs, as
fil_ ids.object | null
valid_solid (null for blender), watertight, bbox_mm [x, y, z], volume_cm3 (null when not closed), triangles. null when the script failed before producing a shape.object | null
{ message, line } — the script’s own failure, with its line number when known. A failing script is a 200 with ok: false, not an error response.string
The last 4 KB of the build’s log: everything the script and the toolchain printed.
number
The computer time the build used.
creating, failed, or destroyed computer is 409 computer_unavailable; a body outside the limits above is validation_failed.
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. On an agent’s computer both go through the agent; see An agent’s computer.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 (Naive Managed Agents 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
computer_unavailable (409). It is removed when the agent is deleted.
A computer a session provisioned for itself — listed as 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.