API overview

The production API is rooted at https://api.agentcomputer.ai/v1. The raw OpenAPI spec lives at /openapi.json, and it is the source of truth for request and response schemas.

Account and auth

Read the current account and manage the keys that power the transparent UI.

Method	Endpoint	Description
`GET`	`/v1/me`	Read the current account.
`GET`	`/v1/ssh-keys`	List SSH keys.
`POST`	`/v1/ssh-keys`	Create an SSH key.
`DELETE`	`/v1/ssh-keys/<id>`	Delete an SSH key.

Computer images

List and inspect available computer images.

Method	Endpoint	Description
`GET`	`/v1/computer-images`	List computer images.
`GET`	`/v1/computer-images/<imageId>`	Read one computer image.

Size presets

List the available computer size presets. Computers can also be created with explicit RAM and storage values.

Method	Endpoint	Description
`GET`	`/v1/computer-size-presets`	List all public size presets with their memory and storage allocations.
`POST`	`/v1/computer-capacity/check`	Validate requested RAM and storage against currently enabled host capacity.

Computers

Create, inspect, update, and delete computers.

Method	Endpoint	Description
`GET`	`/v1/computers`	List visible computers.
`POST`	`/v1/computers`	Create a computer. Pass platform, size_preset, or requested_memory_mib plus requested_storage_bytes. Default Linux size: ram-2g. Default macOS size: 4 GiB RAM with 64 GiB storage.
`GET`	`/v1/computers/<id>`	Read one computer.
`PATCH`	`/v1/computers/<id>`	Update computer settings.
`DELETE`	`/v1/computers/<id>`	Delete a computer.
`POST`	`/v1/computers/<id>/actions/start`	Start a stopped computer.
`POST`	`/v1/computers/<id>/actions/stop`	Stop a running computer.
`POST`	`/v1/computers/<id>/actions/ensure-ready`	Start the computer if it isn't already running or starting. Idempotent.
`POST`	`/v1/computers/<id>/actions/resize`	Queue a RAM or storage resize.
`POST`	`/v1/computers/<id>/actions/transfer`	Transfer ownership of a computer to another workspace.
`POST`	`/v1/computers/<id>/exec`	Run a command on a running computer and return stdout, stderr, and exit code.
`POST`	`/v1/computers/<id>/files/ops`	Read and write the workspace. Works on stopped computers too. See Files operations below.

Access and shares

Fetch connection metadata, mint access sessions, and manage direct share-entry primitives.

Method	Endpoint	Description
`GET`	`/v1/computers/<id>/connection`	Read connection metadata.
`POST`	`/v1/computers/<id>/access-sessions`	Create a browser or VNC access session.
`GET`	`/v1/computers/<id>/access-sessions/<sessionId>`	Read an access session.
`DELETE`	`/v1/computers/<id>/access-sessions/<sessionId>`	Delete an access session.
`POST`	`/v1/computers/<id>/ssh/certificates`	Mint an SSH certificate.
`POST`	`/v1/computers/<id>/ssh-credentials`	Issue a short-lived SSH credential bundle for direct-edge connections.
`GET`	`/v1/computers/<id>/shares`	List active shares for a computer.
`POST`	`/v1/computers/<id>/shares/links`	Create a share link.
`DELETE`	`/v1/computers/<id>/shares/links/<shareId>`	Delete a share link.
`GET`	`/v1/shares/<token>`	Resolve a public share token.
`POST`	`/v1/shares/<token>/access-sessions`	Redeem a share token directly into browser or VNC access.

Ports

Publish app ports with stable public hostnames.

Method	Endpoint	Description
`GET`	`/v1/computers/<id>/ports`	List published ports.
`POST`	`/v1/computers/<id>/ports`	Create or update a published port.
`DELETE`	`/v1/computers/<id>/ports/<port>`	Delete a published port.

Snapshots and usage

Save computer state and inspect account usage.

Method	Endpoint	Description
`GET`	`/v1/computers/<id>/snapshots`	List snapshots for a computer.
`POST`	`/v1/computers/<id>/snapshots`	Create a snapshot.
`GET`	`/v1/snapshots/<snapshotId>`	Read one snapshot.
`POST`	`/v1/snapshots/<snapshotId>/restore`	Restore a snapshot into a new computer.
`DELETE`	`/v1/snapshots/<snapshotId>`	Delete a snapshot.
`GET`	`/v1/usage`	Read account usage.
`GET`	`/v1/computers/<id>/usage`	Read per-computer usage (runtime, CPU-hours, RAM-GiB-hours, hot and cold storage).
`PATCH`	`/v1/billing/preferences`	Update billing preferences for the current account or org.
`GET`	`/v1/status/uptime`	Public uptime summary.

Operations

Poll the status of long-running async operations.

Method	Endpoint	Description
`GET`	`/v1/operations/<operationId>`	Read an operation.

Files operations

One POST, dispatched on the operation field. Works against running and stopped computers; stopped requests do not start the VM or accrue runtime. All paths must be absolute and live under /home/node/workspace; responses report paths relative to that root. Owner or workspace admin only.

Read a file

curl -X POST https://api.agentcomputer.ai/v1/computers/<id>/files/ops \
     -H 'Authorization: Bearer ak_...' \
     -H 'Content-Type: application/json' \
     -d '{"operation": "read_text", "path": "/home/node/workspace/README.md"}'

Write a file

curl -X POST https://api.agentcomputer.ai/v1/computers/<id>/files/ops \
     -H 'Authorization: Bearer ak_...' \
     -H 'Content-Type: application/json' \
     -d '{
       "operation": "write_text",
       "path": "/home/node/workspace/notes.txt",
       "content": "hello from the API\n",
       "mode": 420
     }'

mode is a decimal POSIX mode (420 = 0o644). Omit to inherit the default.

List a directory

curl -X POST https://api.agentcomputer.ai/v1/computers/<id>/files/ops \
     -H 'Authorization: Bearer ak_...' \
     -H 'Content-Type: application/json' \
     -d '{"operation": "list", "path": "/home/node/workspace", "recursive": false}'

{
  "entries": [
    { "path": "README.md", "name": "README.md", "type": "file",      "size_bytes": 128, "mode": 420 },
    { "path": "src",       "name": "src",       "type": "directory", "mode": 493 }
  ]
}

Operations

operation	Description
`read_text`	Read a UTF-8 file. Returns `content`.
`read_bytes`	Read a binary file. Returns base64 in `content_base64`.
`write_text`	Write UTF-8 content. Optional `mode`.
`write_bytes`	Write base64-encoded bytes.
`read_range`	Read a byte range (`offset`, `length`).
`write_range`	Write at `offset`.
`list`	List a directory. Optional `recursive`.
`stat`	Type, size, and mode for one path.
`exists`	Whether a path exists.
`mkdir`	Create a directory. Optional `recursive`.
`move`	Move or rename. Fields: `path`, `to`.
`remove`	Delete a path. Optional `recursive`.
`patch`	Apply `edits` ({find, replace}) or replace with `set_contents`.
`grep`	Search under `path` with `pattern`, `regex`, `case_insensitive`, `max_matches`.

Exec sessions

Exec sessions give the computer owner programmatic access to guest processes over ConnectRPC. Exec is not a separate resource: create an access session with kind: "exec" on a running computer, then call the returned gateway. Owner-only in v1.

Create a session

curl -X POST https://api.agentcomputer.ai/v1/computers/<id>/access-sessions \
     -H 'Authorization: Bearer ak_...' \
     -H 'Content-Type: application/json' \
     -d '{"kind": "exec"}'

Response

{
  "session": {
    "kind": "exec",
    "connect_url": "https://exec.computer.agentcomputer.ai",
    "connect_token": "eyJhbGciOi...",
    "transport": {
      "protocol": "connectrpc",
      "service": "process.Process",
      "base_path": "/process.Process/",
      "capabilities": ["process"]
    },
    "access_url": "https://exec.computer.agentcomputer.ai?access_token=eyJhbGciOi..."
  }
}

Field	Description
`connect_url`	Exec gateway base URL. Use this as the primary endpoint.
`connect_token`	Short-lived bearer token scoped to this computer and session.
`transport`	ConnectRPC metadata: service name, base path, and capabilities.
`access_url`	Convenience URL with the token embedded as a query parameter.

Call the gateway

Send ConnectRPC requests to connect_url with an Authorization: Bearer <connect_token> header. All methods are POST against the process.Process service.

curl -X POST {connect_url}/process.Process/Start \
     -H 'Authorization: Bearer {connect_token}' \
     -H 'Content-Type: application/json' \
     -d '{"command": ["ls", "-la"]}'

Methods

Start

Start a new process and optionally stream initial output.

Connect

Attach to an existing process by tag or PID and stream output.

List

List tracked processes for the computer.

Update

Update session state such as PTY size.

SendInput

Send a single input chunk to a running process.

StreamInput

Open a persistent input stream for continuous input.

SendSignal

Send a signal (SIGTERM, SIGKILL, etc.) to a process.

CloseStdin

Close stdin without tearing down the process stream.