Computers API

Persistent Linux machines: the root disk and network address survive stop/start, and only DELETE reclaims the disk.

REST API endpoints for Computers. 11 operations.

List your Computers

plaintext

GET /v1/computers

Auth: Bearer API key

Responses

Status	Description
`200`	Your Computers, newest first
`401`	Missing or invalid API key

operationId: computerList

Create a Computer

plaintext

POST /v1/computers

Boots a persistent Linux machine and returns once it is provisioning. The root disk survives stop/start and is only reclaimed by DELETE. Billed per start, per vCPU-hour and GB-hour while running, and per GB-month of disk for as long as the Computer exists.

Auth: Bearer API key

Request body

application/json (required) — schema ComputerCreateRequest.

Request body for creating a Computer.

Field	Type	Required	Description
`name`	`string`	Yes	Lowercase DNS label, max 63 characters. Unique per account.
`image`	`string \| null`	No	Guest image. `ubuntu24` is the only image available today.
`resources`	`object`	No
`ssh_keys`	`array<string>`	No	OpenSSH public keys authorised for `root`, one per array entry, max 32. Optional — `exec` and the browser terminal work without one. Send the public half only (the `.pub` file); a private key is rejected.

Responses

Status	Description
`201`	Computer created (initially CREATING)
`400`	Invalid name or resource shape
`401`	Missing or invalid API key
`402`	Credit exhausted or plan limit reached
`409`	A Computer with that name already exists
`503`	No host has capacity for the requested resources

operationId: computerCreate

Delete a Computer

plaintext

DELETE /v1/computers/{id}

The only operation that reclaims the root disk. Irreversible — stop the Computer instead if you want the files back later.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`204`	Computer and its disk deleted
`404`	Not found

operationId: computerDelete

Get one Computer

plaintext

GET /v1/computers/{id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`200`	The Computer
`404`	Not found

operationId: computerGet

Run a command inside a Computer

plaintext

POST /v1/computers/{id}/exec

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Request body

application/json (required) — schema ComputerExecRequest.

Request body for running a command inside a Computer.

Field	Type	Required	Description
`command`	`string`	Yes
`args`	`array<string>`	No
`cwd`	`string \| null`	No	Working directory inside the guest.
`env`	`object`	No
`timeout_ms`	`integer \| null (int64)`	No	1000..600000, default 60000.

Responses

Status	Description
`200`	Command finished
`404`	Not found
`409`	The Computer is not RUNNING

operationId: computerExec

Read one file out of a Computer

plaintext

GET /v1/computers/{id}/files

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id
`path`	query	`string`	Yes	Absolute path inside the guest

Responses

Status	Description
`200`	File contents, base64-encoded
`400`	Missing `path` query parameter
`404`	Not found
`409`	The Computer is not RUNNING

operationId: computerReadFile

Write files into a Computer

plaintext

PUT /v1/computers/{id}/files

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Request body

application/json (required) — schema ComputerWriteFilesRequest.

Request body for writing files into a Computer. Max 64 files per call.

Field	Type	Required	Description
`files`	`array<ComputerFileWrite>`	Yes

Nested schema — ComputerFileWrite:

Field	Type	Required	Description
`path`	`string`	Yes	ABSOLUTE path inside the guest — relative paths are rejected with 400 (an older guest build silently wrote them against the VM's CWD and reported success; audit 2026-10-21).
`content_b64`	`string`	Yes	Base64-encoded contents.
`mode`	`integer \| null (int32)`	No	Unix mode, default 0644.

Responses

Status	Description
`204`	Files written
`400`	No files, or more than 64
`404`	Not found
`409`	The Computer is not RUNNING

operationId: computerWriteFiles

Replace a Computer's authorised ssh keys

plaintext

PUT /v1/computers/{id}/ssh-keys

Sends the whole list every time, so removing a key is the same operation as adding one. On a RUNNING machine the change applies immediately — a revoked key stops working now, not at the next restart. On a stopped machine it is stored and delivered when it next boots.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Request body

application/json (required) — schema ComputerSshKeysRequest.

Request body for replacing a Computer's authorised ssh keys.

Field	Type	Required	Description
`ssh_keys`	`array<string>`	Yes	The complete list, max 32. Not a patch: whatever you send becomes the whole of `authorized_keys`, and an empty array removes every key.

Responses

Status	Description
`200`	The Computer, with the new key list
`400`	Not an OpenSSH public key, or more than 32
`404`	Not found
`502`	The keys could not be delivered to the running machine

operationId: computerSetSshKeys

Start a stopped Computer

plaintext

POST /v1/computers/{id}/start

Boots the same disk on the same host and reclaims the same address.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`200`	The Computer, now RUNNING
`404`	Not found
`503`	The Computer's host is unavailable

operationId: computerStart

Stop a Computer

plaintext

POST /v1/computers/{id}/stop

Halts the machine. The root disk and the network address are kept, so a later start comes back to the same files at the same address. Runtime billing stops; disk billing continues at the parked rate.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`200`	The Computer, now STOPPED
`404`	Not found

operationId: computerStop

Get or create a Computer by name

plaintext

PUT /v1/computers/by-name/{name}

Idempotent: the first call creates the machine (201), every identical repeat returns the existing one (200). Resource changes on a repeat are ignored — the existing machine wins. Use this instead of create when an agent may retry.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	Lowercase DNS label, max 63 characters

Request body

application/json (required) — schema ComputerCreateRequest.

Request body for creating a Computer.

Field	Type	Required	Description
`name`	`string`	Yes	Lowercase DNS label, max 63 characters. Unique per account.
`image`	`string \| null`	No	Guest image. `ubuntu24` is the only image available today.
`resources`	`object`	No
`ssh_keys`	`array<string>`	No	OpenSSH public keys authorised for `root`, one per array entry, max 32. Optional — `exec` and the browser terminal work without one. Send the public half only (the `.pub` file); a private key is rejected.

Responses

Status	Description
`200`	The existing Computer
`201`	Computer created
`400`	Invalid name or resource shape
`503`	No host has capacity for the requested resources

operationId: computerGetOrCreateByName