Computers

A computer is a Linux machine that belongs to you rather than to a single conversation. Shell abilities normally run in an ephemeral sandbox that is created for a conversation and thrown away when it goes idle. Link those abilities to a computer and they run on it instead, so the tools an agent installs and the files it writes are there the next time any conversation uses the same computer.

Kinds of computer

  • shell - a headless Linux environment for commands, scripts and files.
  • desktop - a Linux desktop with a graphical session. Besides running commands, you can mint a short-lived link and watch or take over the screen from a browser.

The kind is chosen when the computer is created.

Creating a Computer

POST /api/v1/computer/create
Content-Type: application/json

{
  "name": "Research desktop",
  "description": "Browser and tools for the research agent",
  "kind": "desktop"
}

http

The response contains the ID of the new computer. A computer starts in the stopped state and is provisioned the first time it is started or used.

Connecting Computers to Shell Abilities

Set linkedComputerId on a shell ability (for example shell/exec, shell/read or shell/write) to run it on the computer. Abilities without a computer keep the ephemeral sandbox behaviour.

POST /api/v1/skillset/{skillsetId}/ability/create
Content-Type: application/json

{
  "name": "Run command",
  "instruction": "template: shell/exec",
  "linkedComputerId": "computer_abc123"
}

http

Blueprints

Computers can belong to a blueprint like any other resource. Cloning a blueprint creates new, stopped computers of the same kind; the clone never shares the original's machine.

Listing Computers

GET /api/v1/computer/list

http

Each item includes the computer's kind and its last known status. The list supports the usual cursor, order, take, meta and blueprintId parameters, and kind to list only shell or only desktop computers.

Fetching a Computer

GET /api/v1/computer/{computerId}/fetch

http
{
  "id": "computer_abc123",
  "name": "Research desktop",
  "kind": "desktop",
  "status": "running",
  "lastActiveAt": "2026-10-17T14:00:00.000Z",
  "createdAt": "2026-10-17T13:00:00.000Z",
  "updatedAt": "2026-10-17T14:00:00.000Z"
}

json

status is the last state the platform recorded. It changes when the computer is started, stopped or provisioned on first use, and it can lag behind a machine the sandbox reclaimed for idleness - starting the computer refreshes it.

Updating a Computer

POST /api/v1/computer/{computerId}/update
Content-Type: application/json

{
  "name": "Research desktop (EU)",
  "meta": { "team": "research" }
}

http

The name, description, alias, blueprint and metadata can be changed. The kind cannot: it is accepted only when it matches the computer's current kind, and a different one fails with COMPUTER_KIND_IMMUTABLE. Create a new computer to switch between shell and desktop.

Deleting a Computer

POST /api/v1/computer/{computerId}/delete

http

Deleting a computer releases its machine and unlinks it from any shell abilities, which go back to running in an ephemeral sandbox.

If the machine cannot be released, the computer is kept and the call fails, so it can be retried without leaving a machine running.

Exporting Computers

GET /api/v1/computer/export

http

Exports the computers' definitions - name, description, kind, blueprint and metadata - for backup or migration. Runtime state is not exported.

Starting, Stopping and Restarting a Computer

POST /api/v1/computer/{computerId}/start
POST /api/v1/computer/{computerId}/stop
POST /api/v1/computer/{computerId}/restart

http

Each returns the computer's status. Starting provisions a machine when the computer has none and checks that a kept one is still alive. A computer is also started on demand by the first command or file operation that uses it, so calling start is optional.

Stopping releases the machine. Whether its files survive a stop depends on the sandbox the platform runs on, so keep anything important in a space or download it first.

Restarting stops the computer and starts it again. Use it when a computer stops responding: it succeeds even when the old machine is already gone.

Running Commands

POST /api/v1/computer/{computerId}/exec
Content-Type: application/json

{
  "command": "uname -a && df -h /",
  "timeout": 60000
}

http
{ "exitCode": 0, "stdout": "Linux ...", "stderr": "" }

json

A command that runs and fails is a normal result with a non-zero exitCode. A computer that is not running is started first.

Sharing Files

Read and write text files on a computer by absolute path:

POST /api/v1/computer/{computerId}/file/write
Content-Type: application/json

{ "path": "/home/user/notes.md", "contents": "# Notes" }

http
POST /api/v1/computer/{computerId}/file/read
Content-Type: application/json

{ "path": "/home/user/notes.md" }

http

Contents are text and limited to 3 MB per request. For binary files, encode them (for example with base64) through exec.

Remote Access to a Desktop

Mint a short-lived link that opens a desktop computer's screen in the browser over web VNC, so a person can watch the agent or take over - to sign in to a site, for example:

POST /api/v1/computer/{computerId}/session/create
Content-Type: application/json

{ "durationInSeconds": 900 }

http
{
  "url": "https://...",
  "expiresAt": "2026-10-17T15:15:00Z"
}

json

The link is signed, valid for 10 minutes by default and at most one hour, and anyone holding it can see and control the desktop. Mint a fresh link each time one is needed rather than storing it. Shell computers have no screen and return a COMPUTER_NOT_DESKTOP error.

Go to cbk.ai