# Cubicles > Cloud computers for AI agents. Each desktop is a full Ubuntu 24.04 computer with a GNOME desktop, on all the time, that an AI agent can drive: run commands, read and write files, and see its screen. Developers and their AIs use it through a REST API or an MCP server, with an API key. - API base URL: https://api.cubicles.cloud/api/v1 - MCP server: https://api.cubicles.cloud/api/v1/mcp (Streamable HTTP) - Auth: `Authorization: Bearer cub_…`, an API key made at https://cubicles.cloud/developers ## Quickstart ```bash export CUBICLES_API_KEY=cub_… # Your desktops curl https://api.cubicles.cloud/api/v1/desktops -H "Authorization: Bearer $CUBICLES_API_KEY" # Run a command on one curl https://api.cubicles.cloud/api/v1/desktops/$DESKTOP_ID/exec \ -H "Authorization: Bearer $CUBICLES_API_KEY" \ -H "Content-Type: application/json" -d '{"command": "uname -a"}' # See its screen curl https://api.cubicles.cloud/api/v1/desktops/$DESKTOP_ID/screenshot \ -H "Authorization: Bearer $CUBICLES_API_KEY" -o screen.jpg ``` ## MCP server URL: `https://api.cubicles.cloud/api/v1/mcp`, with `Authorization: Bearer cub_…` (an API key from https://cubicles.cloud/developers). - Streamable HTTP transport at `POST /mcp`: one JSON-RPC 2.0 message (or a batch) per request, answered as `application/json`. Notifications get `202` with no body. - Stateless: no `Mcp-Session-Id`; `GET` and `DELETE` answer `405`. - Protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`; a client asking for another gets the newest. - API key only (`Authorization: Bearer cub_…`); a browser session gets `403 api_key_required`. - A tool that fails because of what it was asked (a stopped desktop, an unknown id) answers `isError: true` with the reason as text, for the model to read and correct, and `structuredContent.error.code` with the REST API's code (`desktop_not_running`, `validation_failed`, `desktop_busy`, …). An unknown tool is a JSON-RPC error. - Results also carry the JSON as `structuredContent`. - `run_command`, `read_file`, `write_file` and `take_screenshot` count toward 120 a minute per account. ### How to use it Call list_desktops to find a desktop. If it's stopped, start_desktop, then poll get_desktop until its status is running. Then use run_command, read_file, write_file and take_screenshot on it. Commands run as the desktop's user, who has passwordless sudo; graphical apps open on its screen. New desktops are bought on cubicles.cloud. ### Tools | Tool | Arguments | What it does | |---|---|---| | `list_desktops` | – | Your desktops with their id, name, plan, status and the actions allowed now | | `get_desktop` | desktop_id | One desktop: status, plan, region, price, allowed actions | | `start_desktop` | desktop_id | Turns on a stopped desktop; poll get_desktop until it's running | | `stop_desktop` | desktop_id | Shuts a running desktop down; its disk is kept | | `restart_desktop` | desktop_id | Restarts a running desktop | | `run_command` | desktop_id, command, stdin?, timeout_seconds? | Runs a bash command as the desktop's user (passwordless sudo, DISPLAY=:1) and returns the exit code, stdout and stderr | | `read_file` | desktop_id, path | A text file's content, up to 100,000 characters (a cut file says so, with its size; a binary one is refused). Relative paths start at home | | `write_file` | desktop_id, path, content | Writes a text file (up to 512 KiB), making its folder and replacing a file already there | | `take_screenshot` | desktop_id | The screen, as an MCP image (JPEG, at most 1920 pixels wide) | | `list_agents` | – | Your agents and their status | | `get_agent` | agent_id | One agent: harness, model, desktop, chats, status | | `redeploy_agent` | agent_id | Sets an agent up again, e.g. after it stopped answering | ### Connect a client #### Claude Code Run in a terminal: ```bash claude mcp add --transport http cubicles https://api.cubicles.cloud/api/v1/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` #### Cursor Add to `~/.cursor/mcp.json`: ```json { "mcpServers": { "cubicles": { "url": "https://api.cubicles.cloud/api/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` #### VS Code Add to `.vscode/mcp.json`: ```json { "servers": { "cubicles": { "type": "http", "url": "https://api.cubicles.cloud/api/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` #### Codex CLI Add to `~/.codex/config.toml, with CUBICLES_API_KEY set in your shell`: ```toml [mcp_servers.cubicles] url = "https://api.cubicles.cloud/api/v1/mcp" bearer_token_env_var = "CUBICLES_API_KEY" ``` #### Claude Desktop Add to `claude_desktop_config.json (Settings → Developer → Edit Config)`: ```json { "mcpServers": { "cubicles": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.cubicles.cloud/api/v1/mcp", "--header", "Authorization:${CUBICLES_AUTH}" ], "env": { "CUBICLES_AUTH": "Bearer YOUR_API_KEY" } } } } ``` ## REST API | Topic | Rule | |---|---| | Base URL | `https://api.cubicles.cloud/api/v1` | | Auth | `Authorization: Bearer cub_…` on every request. A key acts as the user who made it; no CSRF header or cookies needed. | | Format | JSON in and out, `camelCase` fields, ISO-8601 UTC timestamps, prices in integer cents | | Errors | `application/problem+json` with a stable `code` to branch on (see Errors). Every response has an `X-Request-Id`: quote it when reporting a problem. | | Rate limits | Over a limit answers `429 too_many_attempts` with `Retry-After` in seconds. Commands and screenshots: 120 a minute per account. | | Keys | `cub_` and 43 characters, shown once when made. Up to 25 per account, optionally expiring. A wrong, expired or deleted key gets `401 invalid_api_key`. | ### Summary | Method | Path | Auth | What | |---|---|---|---| | GET | `/me` | API key | The user the key acts as | | GET | `/catalog` | Public | Plans, operating systems and regions on sale | | GET | `/desktops` | API key | Your desktops, newest first | | GET | `/desktops/{id}` | API key | One desktop | | POST | `/desktops/{id}/start` | API key | Start a stopped desktop | | POST | `/desktops/{id}/stop` | API key | Shut a running desktop down | | POST | `/desktops/{id}/restart` | API key | Restart a running desktop | | POST | `/desktops/{id}/exec` | API key | Run a shell command and wait for its output | | GET | `/desktops/{id}/screenshot` | API key | A JPEG of the screen | | POST | `/desktops/{id}/files` | API key | Upload a file to the Desktop folder | | GET | `/desktops/{id}/files` | API key | List the files and folders in a folder | | GET | `/desktops/{id}/files/download` | API key | Download a file from anywhere on the computer | | POST | `/desktops` | API key | Create a desktop | | GET | `/desktops/{id}/checkout` | API key | Whether a checkout has been paid | | DELETE | `/desktops/{id}` | API key | Delete a desktop whose subscription is canceled | | GET | `/desktops/{id}/shares` | API key | The desktop's shares that haven't ended | | POST | `/desktops/{id}/shares` | API key | Share the desktop | | DELETE | `/desktops/{id}/shares/{shareId}` | API key | End a share and disconnect its guests | | GET | `/agents/catalog` | API key | Harnesses, model providers and chat apps | | GET | `/agents` | API key | Your agents, newest first | | GET | `/agents/{id}` | API key | One agent | | POST | `/agents` | API key | Set an agent up on a desktop | | POST | `/agents/{id}/redeploy` | API key | Set a `ready` or `failed` agent up again | | POST | `/agents/{id}/link` | API key | Show the WhatsApp and Signal QR codes on the desktop again | | DELETE | `/agents/{id}` | API key | Remove an agent from its desktop | | GET | `/billing/upcoming` | API key | The next charge of every desktop, before tax | | GET | `/invoices` | API key | Past invoices, newest first | | GET | `/invoices/{id}/pdf` | API key | Redirect to the invoice PDF | | GET | `/payment-methods` | API key | The cards on file (display details only) | | GET | `/api-keys` | Browser session only | Your keys that haven't expired | | POST | `/api-keys` | Browser session only | Make a key (shown once) | | DELETE | `/api-keys/{id}` | Browser session only | Delete a key: requests with it fail from now on | ## Account and catalogue Who the key belongs to, and what can be bought. ### `GET /me` The user the key acts as. Auth: API key. Response: ```json { "id": "a0000000-0000-0000-0000-000000000001", "fullName": "Ada Lovelace", "email": "ada@example.com", "emailVerified": true, "createdAt": "2026-08-14T00:00:00Z", "termsAccepted": true, "role": "user" } ``` ### `GET /catalog` Plans, operating systems and regions on sale. Auth: Public. Prices are integer cents before tax. `available` is false while no server has room for a plan; `reason` is then `sold_out` or `no_server`. Cached for 30 seconds. Response: ```json { "plans": [ { "id": "standard", "name": "Standard", "vcpu": 4, "memoryGb": 8, "diskGb": 120, "monthlyPriceCents": 2400, "description": "Agents juggling browser, docs and sheets.", "popular": true, "available": true, "reason": null, "details": null } ], "operatingSystems": [ { "id": "ubuntu", "name": "Ubuntu Desktop", "versionLabel": "24.04 LTS · GNOME", "monthlySurchargeCents": 0 } ], "regions": [ { "id": "fra", "name": "Frankfurt", "code": "eu-c" } ], "currency": "usd" } ``` ## Desktops A desktop is a cloud computer: Ubuntu 24.04 with a GNOME desktop, on until it's stopped. Its user is named after the desktop and has passwordless sudo. Desktop object fields: | Field | Notes | |---|---| | `status` | `awaiting_payment`, `provisioning`, `starting`, `running`, `stopping`, `stopped`, `restarting`, `deleting` or `failed`. The in-between ones change by themselves within seconds to minutes, so poll. | | `statusProgress` | 0–100 while `provisioning` or `starting`, else null | | `statusMessage` | A sentence about the status ("Starting Ubuntu…", why it `failed`), or null | | `monthlyPriceCents` | What's billed each month, before tax | | `free` | The account's free desktop: nothing is billed, and it can be deleted any time | | `subscriptionStatus` | `active`, `past_due` or `canceled`; null until the payment is confirmed | | `nextChargeAt` | End of the current billing period; null when canceled | | `cancelAt` | When a scheduled cancellation deletes the desktop; null if none | | `allowedActions` | What can be done now: `stop` and `restart` while `running`, `start` while `stopped`, `delete` once the subscription is canceled | ### `GET /desktops` Your desktops, newest first. Auth: API key. Answers `{ "items": [Desktop, …] }`. A desktop is listed once its payment is confirmed. ### `GET /desktops/{id}` One desktop. Auth: API key. | Field | Rule | |---|---| | `status` | `awaiting_payment`, `provisioning`, `starting`, `running`, `stopping`, `stopped`, `restarting`, `deleting` or `failed`. The in-between ones change by themselves within seconds to minutes, so poll. | | `statusProgress` | 0–100 while `provisioning` or `starting`, else null | | `statusMessage` | A sentence about the status ("Starting Ubuntu…", why it `failed`), or null | | `monthlyPriceCents` | What's billed each month, before tax | | `free` | The account's free desktop: nothing is billed, and it can be deleted any time | | `subscriptionStatus` | `active`, `past_due` or `canceled`; null until the payment is confirmed | | `nextChargeAt` | End of the current billing period; null when canceled | | `cancelAt` | When a scheduled cancellation deletes the desktop; null if none | | `allowedActions` | What can be done now: `stop` and `restart` while `running`, `start` while `stopped`, `delete` once the subscription is canceled | Response: ```json { "id": "d0000000-0000-0000-0000-000000000003", "name": "atlas", "plan": { "id": "pro", "name": "Pro", "vcpu": 8, "memoryGb": 16, "diskGb": 240 }, "os": { "id": "ubuntu", "name": "Ubuntu Desktop" }, "region": { "id": "fra", "name": "Frankfurt", "code": "eu-c" }, "status": "running", "statusProgress": null, "statusMessage": null, "monthlyPriceCents": 4800, "currency": "usd", "subscriptionStatus": "active", "nextChargeAt": "2026-12-05T10:00:00Z", "cancelAt": null, "createdAt": "2026-11-05T10:00:00Z", "allowedActions": ["open_session", "stop", "restart"] } ``` | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | ### `POST /desktops/{id}/start` Start a stopped desktop. Auth: API key. No body. Answers `200` with the Desktop, now `starting`; it's `running` a minute or two later (a first start takes a few minutes), so poll `GET /desktops/{id}`. `/stop` and `/restart` work the same way: stop shuts Ubuntu down and forces it off after two minutes; the disk is kept. | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | | 409 | `action_not_allowed` | Not offered in the current status (see `allowedActions`) | ### `POST /desktops/{id}/stop` Shut a running desktop down. Auth: API key. As `/start`. Programs running on it stop; its disk is kept. | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | | 409 | `action_not_allowed` | Not offered in the current status | ### `POST /desktops/{id}/restart` Restart a running desktop. Auth: API key. As `/start`. Programs running on it stop. | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | | 409 | `action_not_allowed` | Not offered in the current status | ### `POST /desktops/{id}/exec` Run a shell command and wait for its output. Auth: API key. Runs as the desktop's user (passwordless sudo) with `bash -lc`, in their home folder, with `DISPLAY=:1` so graphical programs open on the screen. A command still running at `timeoutSeconds` is stopped. Background a program that should keep running with `nohup … &`. `exitCode` is `124` when it ran out of time. `stdout` and `stderr` keep their first 100,000 characters each; `truncated` says one was longer. Commands and screenshots together are limited to 120 a minute per account. Each command has about a second of fixed overhead, so `timeoutSeconds` bounds the command, not the request. At most 8 commands and screenshots run on one desktop at once; more wait in line for up to 30 seconds, so parallel calls queue rather than fail. Request: ```json { "command": "cat > notes.txt && wc -c notes.txt", "stdin": "hello\n", "timeoutSeconds": 60 } ``` | Field | Rule | |---|---| | `command` | Required, at most 16 KiB. Send a longer script as `stdin` to `bash -s`. | | `stdin` | Optional, at most 512 KiB of UTF-8 | | `timeoutSeconds` | 1 to 300, default 60 | Response: ```json { "exitCode": 0, "stdout": "6 notes.txt\n", "stderr": "", "timedOut": false, "truncated": false } ``` | Status | Code | When | |---|---|---| | 400 | `validation_failed` | No `command`, or a field over its limit | | 404 | `not_found` | Not your desktop, or no such id | | 409 | `desktop_not_running` | The desktop isn't `running` | | 429 | `too_many_attempts` | Over 120 commands and screenshots a minute | | 429 | `desktop_busy` | 8 commands were already running on it for the 30 seconds this one waited; see `Retry-After` | | 502 | `desktop_unreachable` | The desktop didn't answer: still starting, or its guest agent is down (restart it) | | 503 | `server_busy` | Its server had no room for another command in time; see `Retry-After` | ### `GET /desktops/{id}/screenshot` A JPEG of the screen. Auth: API key. `image/jpeg`, at most 1920 pixels wide. Counts toward the 120 a minute of `exec`. | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | | 409 | `desktop_not_running` | The desktop isn't `running` | | 429 | `too_many_attempts` | Over the rate limit | | 429 | `desktop_busy` | Too many commands at once on the desktop; see `Retry-After` | | 502 | `desktop_unreachable` | The desktop didn't answer | ### `POST /desktops/{id}/files` Upload a file to the Desktop folder. Auth: API key. `multipart/form-data` with one file in the `file` part, at most 100 MB. It lands in `~/Desktop` under its own name; if that's taken, the new one becomes `name (1).ext`. Upload files one at a time. To get a file back, use `GET /desktops/{id}/files/download`. Response: ```json { "name": "report (1).pdf", "size": 482113 } ``` | Status | Code | When | |---|---|---| | 400 | `validation_failed` | No `file` part, or an unusable name | | 404 | `not_found` | Not your desktop, or no such id | | 409 | `desktop_not_running` | The desktop isn't `running` | | 413 | `file_too_large` | Over 100 MB | | 502 | `upload_failed` | The desktop didn't take it (disk full, or not answering) | ### `GET /desktops/{id}/files` List the files and folders in a folder. Auth: API key. `?dir=` the folder's absolute path; without it, `~/Desktop`. Read as the desktop's user. Hidden ones are included; folders come first, then files, each newest first, at most 500 (`truncated` if there were more). `dir` is the folder's real path, `parent` the one it's in (null for `/`), `home` the user's home folder. Response: ```json { "dir": "/home/atlas/Desktop", "parent": "/home/atlas", "home": "/home/atlas", "truncated": false, "items": [ { "name": "report (1).pdf", "size": 482113, "modifiedAt": "2026-11-09T10:15:02.250Z", "folder": false } ] } ``` | Status | Code | When | |---|---|---| | 400 | `validation_failed` | `dir` isn't an absolute path | | 403 | `folder_not_readable` | The desktop's user can't read that folder | | 404 | `not_found` | Not your desktop, or no such id | | 404 | `folder_not_found` | No folder there | | 409 | `desktop_not_running` | The desktop isn't `running` | | 502 | `desktop_unreachable` | The desktop didn't answer | ### `GET /desktops/{id}/files/download` Download a file from anywhere on the computer. Auth: API key. `?path=` the file's absolute path (or `?name=` a file in `~/Desktop`); at most 100 MB, read as the desktop's user. Answers with the file as `application/octet-stream`, an attachment with its name, and `Content-Length`. It comes out of the desktop a few MB at a time; if the desktop stops answering on the way, the response is cut short of its `Content-Length`. | Status | Code | When | |---|---|---| | 400 | `validation_failed` | No `path`, or one that isn't absolute | | 403 | `file_not_readable` | The desktop's user can't read that file | | 404 | `not_found` | Not your desktop, or no such id | | 404 | `file_not_found` | No file there | | 409 | `desktop_not_running` | The desktop isn't `running` | | 413 | `file_too_large` | Over 100 MB | | 502 | `desktop_unreachable` | The desktop didn't answer | ### `POST /desktops` Create a desktop. Auth: API key. A paid desktop: holds the name and creates a payment. Answers `201` with a `checkoutUrl` for a person to pay at; the desktop appears in `GET /desktops` once paid. Unpaid checkouts are released after 15 minutes. Poll `GET /desktops/{id}/checkout`: any status other than `awaiting_payment` means it's paid. With `"free": true`, the account's free desktop (the plan in `GET /catalog`'s `freePlan`, one per account): created at once and starts provisioning, with `transactionId` and `checkoutUrl` null. Poll `GET /desktops/{id}` until it is `running`. Request: ```json { "name": "atlas", "planId": "standard", "osId": "ubuntu", "regionId": "fra", "free": true } ``` | Field | Rule | |---|---| | `name` | 3–32 characters of `a-z`, `0-9` and `-`, starting with a letter. It becomes the desktop's Ubuntu user. | | `free` | Optional. `true` for the account's free desktop; left out to pay. | Response: ```json { "desktopId": "…", "transactionId": "txn_01…", "checkoutUrl": "https://cubicles.cloud/pay?_ptxn=txn_01…" } ``` | Status | Code | When | |---|---|---| | 400 | `validation_failed` | A bad name, or a name Ubuntu already uses (`root`, `ubuntu`) | | 400 | `plan_unavailable` | Unknown plan (also `os_unavailable`, `region_unavailable`) | | 400 | `free_plan_unavailable` | `free` with a plan other than the free one | | 409 | `too_many_desktops` | `free`, but the account already has its free desktop | | 409 | `plan_sold_out` | No server has room for the plan right now | | 409 | `name_taken` | Another desktop in that region has the name | ### `GET /desktops/{id}/checkout` Whether a checkout has been paid. Auth: API key. Response: ```json { "desktopId": "…", "status": "awaiting_payment" } ``` | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | ### `DELETE /desktops/{id}` Delete a desktop whose subscription is canceled. Auth: API key. Only once the subscription was canceled (`delete` in `allowedActions`). Ends the subscription now and destroys the desktop and its disk. Nothing is refunded. Answers `202` with the Desktop, `deleting`. A free desktop can be deleted at any time. Answers `202` with the Desktop, `deleting`. A desktop whose checkout is still open (`awaiting_payment`) can be deleted too: its checkout is canceled and its name freed. Answers `202` with the Desktop, `deleted`. Request: ```json { "confirmName": "atlas" } ``` | Status | Code | When | |---|---|---| | 400 | `confirm_name_mismatch` | `confirmName` isn't the desktop's name | | 404 | `not_found` | Not your desktop, or no such id | | 409 | `subscription_active` | Cancel the subscription first (in the web app's billing) | | 409 | `action_not_allowed` | Already being deleted, or the open checkout was just paid | ## Sharing Share a desktop's screen: a view-only link, or an invitation for one email address to use it too. Guests open the link in a browser. ### `GET /desktops/{id}/shares` The desktop's shares that haven't ended. Auth: API key. `{ "items": [Share, …] }`, oldest first. | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or no such id | ### `POST /desktops/{id}/shares` Share the desktop. Auth: API key. `access` is `view` or `control`. `email` is required for `control`; leave it out of a `view` link anyone holding it can open. With an `email`, the invitation is emailed. `url` is only in this answer: keep it. Request: ```json { "access": "view", "expiresInMinutes": 60 } ``` | Field | Rule | |---|---| | `access` | `view` (watch only) or `control` (use it too) | | `email` | Who may open it; required for `control` | | `expiresInMinutes` | 1 to 43200, or null for never | Response: ```json { "id": "6f1c…", "access": "view", "email": null, "expiresAt": "2026-11-05T11:00:00Z", "createdAt": "2026-11-05T10:00:00Z", "guests": 0, "url": "https://cubicles.cloud/share/…" } ``` | Status | Code | When | |---|---|---| | 400 | `validation_failed` | No `email` for `control`, your own email, or `expiresInMinutes` out of range | | 404 | `not_found` | Not your desktop, or no such id | | 409 | `action_not_allowed` | The desktop's checkout is still open: there's nothing to share yet | | 409 | `too_many_shares` | The desktop has 20 shares that haven't ended | | 429 | `too_many_attempts` | More than 30 invitations in an hour | ### `DELETE /desktops/{id}/shares/{shareId}` End a share and disconnect its guests. Auth: API key. `204`. Ending one that already ended does nothing. | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your desktop, or not its share | ## Agents An agent is an AI agent harness (OpenClaw, Hermes Agent, Claude Code, Codex CLI or OpenCode) that Cubicles sets up on one of your desktops with your model and its API key, optionally answering you on Telegram, Discord, WhatsApp or Signal. ### `GET /agents/catalog` Harnesses, model providers and chat apps. Auth: API key. What each harness supports: its `providers` (default first) and `channels`. ### `GET /agents` Your agents, newest first. Auth: API key. `{ "items": [Agent, …] }`. ### `GET /agents/{id}` One agent. Auth: API key. `status` is `pending` (waiting for its desktop to run), `installing`, `ready`, `failed` (`statusMessage` says why) or `deleting`. A WhatsApp or Signal chat is `needs_link` until its QR code, shown on the desktop, is scanned. Response: ```json { "id": "5b1e0000-0000-0000-0000-000000000001", "name": "OpenClaw", "harness": { "id": "openclaw", "name": "OpenClaw" }, "provider": "anthropic", "model": "claude-sonnet-5-5", "baseUrl": null, "apiKeyHint": "9876", "desktop": { "id": "d0000000-…", "name": "atlas", "status": "running" }, "status": "ready", "statusMessage": null, "channels": [ { "kind": "telegram", "allowedSender": "412587349", "account": null, "status": "ready", "greeting": "sent", "chatUrl": "https://t.me/atlas_agent_bot" } ], "createdAt": "2026-11-05T09:24:37Z", "allowedActions": ["redeploy", "delete"] } ``` | Status | Code | When | |---|---|---| | 404 | `not_found` | Not your agent | ### `POST /agents` Set an agent up on a desktop. Auth: API key. Answers `201` with the Agent, `pending`; it's set up in a few minutes once the desktop runs. Keys and bot tokens are stored encrypted and never sent back. Each chat answers only `allowedSender`, since whoever can message the agent controls the desktop. A desktop has at most one agent of each harness. Request: ```json { "desktopId": "d0000000-…", "name": "OpenClaw", "harness": "openclaw", "provider": "anthropic", "model": "claude-sonnet-5-5", "apiKey": "sk-ant-…", "baseUrl": null, "channels": [ { "kind": "telegram", "botToken": "123456789:AAH…", "allowedSender": "412587349" } ] } ``` | Field | Rule | |---|---| | `harness` | `openclaw`, `hermes`, `claude_code`, `codex` or `opencode` | | `provider` | One the harness supports (see `/agents/catalog`); `custom` needs `baseUrl` | | `name` | 1 to 40 characters | | `channels` | Optional. `botToken` for `telegram` and `discord`, `account` (E.164) for `signal`, and `allowedSender` for each: a numeric Telegram or Discord user id, or an E.164 phone number | | Status | Code | When | |---|---|---| | 400 | `validation_failed` | A field is missing or malformed, or the harness doesn't support it (`fieldErrors` names it) | | 404 | `not_found` | Not your desktop | | 409 | `desktop_unavailable` | The desktop is awaiting payment or being deleted | | 409 | `agent_exists` | The desktop already has an agent of that harness | | 409 | `too_many_agents` | The account has 20 agents | ### `POST /agents/{id}/redeploy` Set a `ready` or `failed` agent up again. Auth: API key. | Status | Code | When | |---|---|---| | 409 | `action_not_allowed` | Not `ready` or `failed` | ### `POST /agents/{id}/link` Show the WhatsApp and Signal QR codes on the desktop again. Auth: API key. | Status | Code | When | |---|---|---| | 409 | `desktop_not_running` | The desktop isn't `running` | | 409 | `action_not_allowed` | No chat waits for its QR code | | 409 | `agent_unreachable` | The desktop didn't answer | ### `DELETE /agents/{id}` Remove an agent from its desktop. Auth: API key. `202` with the Agent, `deleting`. Its services, setup and secrets are removed; the harness and what the agent made stay. ## Billing What's due and what was paid. Cards and cancellations are managed in the web app's billing page. ### `GET /billing/upcoming` The next charge of every desktop, before tax. Auth: API key. Response: ```json { "nextChargeAt": "2026-12-05T10:00:00Z", "totalCents": 4800, "currency": "usd", "lines": [ { "desktopId": "…", "desktopName": "atlas", "description": "Pro · Ubuntu Desktop", "amountCents": 4800, "chargeAt": "2026-12-05T10:00:00Z" } ] } ``` ### `GET /invoices` Past invoices, newest first. Auth: API key. `status` is `open` (payment failed), `paid`, `void` or `uncollectible`. Totals include tax. Response: ```json { "items": [ { "id": "…", "number": "325-10566", "status": "paid", "totalCents": 4165, "currency": "usd", "issuedAt": "…", "paidAt": "…", "periodStart": "…", "periodEnd": "…", "hasPdf": true } ] } ``` ### `GET /invoices/{id}/pdf` Redirect to the invoice PDF. Auth: API key. `302` to a link that expires after an hour. ### `GET /payment-methods` The cards on file (display details only). Auth: API key. ## API keys Made and deleted in the web app (Developers), with the browser session. A key can't manage keys. ### `GET /api-keys` Your keys that haven't expired. Auth: Browser session only. ### `POST /api-keys` Make a key (shown once). Auth: Browser session only. Request: ```json { "name": "Claude Code on my laptop", "expiresInDays": 90 } ``` | Status | Code | When | |---|---|---| | 409 | `too_many_api_keys` | The account has 25 keys | ### `DELETE /api-keys/{id}` Delete a key: requests with it fail from now on. Auth: Browser session only. ## Errors Every error is `application/problem+json`. Branch on `code`, not `title`. `detail` is added when there's a hint, and `fieldErrors` (`[{ field, message }]`) for field problems. ```json { "type": "https://cubicles.cloud/docs/errors/desktop_not_running", "title": "The desktop isn't running.", "status": 409, "instance": "/api/v1/desktops/d0000000-…/exec", "code": "desktop_not_running" } ``` | Status | Code | Meaning | |---|---|---| | 400 | `validation_failed` | Invalid fields, or a body that isn't valid JSON (`fieldErrors` says which) | | 400 | `confirm_name_mismatch` | The typed name isn't the desktop's | | 400 | `plan_unavailable` | Unknown or retired plan (also `os_unavailable`, `region_unavailable`) | | 401 | `unauthenticated` | No API key or session, whatever the method | | 401 | `invalid_api_key` | Wrong, expired or deleted API key | | 403 | `forbidden` | A signed-in browser request (or any `/auth/…` call) without its CSRF header | | 403 | `session_required` | Managing API keys, the billing portal or the admin dashboard with an API key | | 403 | `api_key_required` | `/mcp` with a browser session instead of an API key | | 404 | `not_found` | No such route (checked before the key), or not yours | | 404 | `share_not_found` | Unknown or ended share link | | 405 | `method_not_allowed` | The endpoint doesn't take that method (see `Allow`) | | 409 | `name_taken` | Desktop name already in use in that region | | 409 | `plan_sold_out` | No server has room for that plan right now | | 400 | `free_plan_unavailable` | `free` with a plan other than the free one, or an OS with a fee | | 409 | `too_many_desktops` | The account already has its free desktop | | 409 | `action_not_allowed` | Not offered in the current status (see `allowedActions`) | | 409 | `desktop_not_running` | A command, file, screenshot or stream needs a running desktop | | 409 | `subscription_active` | Deleting a desktop needs its subscription canceled first | | 409 | `too_many_shares` | The desktop has 20 shares that haven't ended | | 409 | `desktop_unavailable` | An agent can't be set up on that desktop | | 409 | `agent_exists` | The desktop already has an agent of that harness | | 409 | `too_many_agents` | The account has 20 agents | | 409 | `too_many_api_keys` | The account has 25 API keys | | 409 | `agent_unreachable` | The desktop didn't answer | | 410 | `share_expired` | Share link past its time | | 403 | `folder_not_readable` | The desktop's user can't read the folder to list | | 403 | `file_not_readable` | The desktop's user can't read the file to download | | 404 | `folder_not_found` | No folder to list at that path | | 404 | `file_not_found` | No file to download at that path | | 413 | `file_too_large` | An upload or download over 100 MB | | 423 | `account_closed` | The account is closed | | 429 | `too_many_attempts` | Rate limit hit; wait the `Retry-After` header's seconds | | 429 | `desktop_busy` | Too many commands at once on one desktop; wait the `Retry-After` header's seconds | | 500 | `internal_error` | Unexpected server error | | 502 | `desktop_unreachable` | The desktop didn't answer a command or screenshot | | 502 | `upload_failed` | The desktop didn't take an uploaded file | | 502 | `payment_provider_error` | The payment provider refused or failed a request | | 503 | `server_busy` | A desktop's server had no room for another command in time; see `Retry-After` |