Cubicles docs
Developer docs
Let your code and your AI agents drive Cubicles: start a computer, run commands on it, read and write its files, and see its screen. Everything goes through one API key, over the REST API or the MCP server.
MCP serverConnect Claude Code, Cursor, VS Code, Codex or Claude Desktop, and let your AI use your computers.REST APIEvery endpoint an API key can call, with requests, answers and errors.ErrorsEvery error code, and what to do about it.
Get started
- Create an account and get a computer (a desktop). The API can start the purchase, but a person pays for it.
- Make an API key on the Developers page. It's shown once, so copy it. A key acts as you: your computers, their commands and files, and your agents. It can't manage keys or open the billing portal.
- Add the MCP server to your AI app (how), or call the REST API at
https://api.cubicles.cloud/api/v1.
Quickstart
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.jpgOr with Claude Code: claude mcp add --transport http cubicles https://api.cubicles.cloud/api/v1/mcp --header "Authorization: Bearer $CUBICLES_API_KEY"
Conventions
| 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. |
For AI tools
These docs are also plain Markdown, for an AI to read: /llms.txt says what Cubicles is and where everything is, and /llms-full.txt holds all of it in one file. Paste either link into your AI's chat. Once connected, the MCP server gives the model its own instructions:
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.