Blog ·
A Cubicles computer is a full Ubuntu desktop in the cloud, made for AI agents. Most people use it through the web app. But the same computers can be driven from code, through a REST API and an MCP server, with an API key. That opens up a different set of uses: scripted fleets, CI jobs on a real desktop, and AI apps that reach out to a computer of their own.
What the API covers
| Area | What you can do |
|---|---|
| Desktops | List them, create the free one, start, stop and restart, and delete |
| Commands | Run a shell command as the desktop's user and get the exit code and output |
| Files | Upload to the Desktop folder, list any folder, download any file |
| Screen | Take a screenshot as a JPEG |
| Sharing | Create view-only links and invitations, list them and end them |
| Agents | Set up OpenClaw, Hermes, Claude Code, Codex or OpenCode on a desktop, check on them, redeploy and remove them |
| Billing | Read upcoming charges, invoices and cards on file |
The full reference, with every field and error, is in the API docs.
Quickstart
Make an API key on the Developers page in the app. It starts with cub_ and is shown once, so copy it somewhere safe. Then:
export CUBICLES_API_KEY=cub_…
API=https://api.cubicles.cloud/api/v1
curl $API/desktops -H "Authorization: Bearer $CUBICLES_API_KEY"
curl $API/desktops/$DESKTOP_ID/exec \
-H "Authorization: Bearer $CUBICLES_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command": "uname -a"}'
curl $API/desktops/$DESKTOP_ID/screenshot \
-H "Authorization: Bearer $CUBICLES_API_KEY" -o screen.jpgA key acts as the user who made it, with no cookies or CSRF headers to deal with. You can have up to 25 keys, each optionally expiring, and delete one to cut it off immediately. Making and deleting keys, and managing payment, stay in the app.
Running commands
POST /desktops/{id}/exec runs a command and waits for it to finish. It runs as the desktop's user, in their home folder, through a login shell, with passwordless sudo. DISPLAY is set, so a graphical app you launch opens on the desktop's screen, where an agent or a person can see it.
POST /desktops/{id}/exec
{ "command": "cat > notes.txt && wc -c notes.txt", "stdin": "hello\n", "timeoutSeconds": 60 }
200
{ "exitCode": 0, "stdout": "6 notes.txt\n", "stderr": "", "timedOut": false, "truncated": false }- Time limit: 1 to 300 seconds, 60 by default. A command still running then is stopped, with exit code 124.
- Long-running programs: start them in the background with
nohup … &and check on them with later commands. - Big scripts: send them as
stdintobash -srather than in the command itself. - Output: the first 100,000 characters of stdout and stderr each, with
truncatedset if there was more.
Moving files
- Upload with
POST /desktops/{id}/files: one file per request, up to 100 MB, into the Desktop folder. A clashing name gets a number added rather than overwriting. - List a folder with
GET /desktops/{id}/files?dir=…. - Download any file the desktop's user can read with
GET /desktops/{id}/files/download?path=…, up to 100 MB.
A common pattern: an agent works on the desktop and saves its report as a file, and your script downloads it on a schedule and drops it into your own storage or inbox.
Seeing the screen
GET /desktops/{id}/screenshot returns a JPEG up to 1920 pixels wide. Use it to check on an agent without opening the desktop, to keep a visual record of a long job, or to give a vision model a look at what's on screen. For a live view, share the screen instead: see how to share your AI agent's screen.
Creating desktops and agents
Your account's free desktop can be created straight from the API. A paid one returns a checkout link for a person to pay at, and appears once it's paid.
POST /desktops
{ "name": "atlas", "planId": "standard", "osId": "ubuntu", "regionId": "fra", "free": true }
# Poll GET /desktops/{id} until "status" is "running", then:
POST /agents
{
"desktopId": "…",
"name": "OpenClaw",
"harness": "openclaw",
"provider": "anthropic",
"model": "claude-sonnet-5-5",
"apiKey": "sk-ant-…",
"channels": [{ "kind": "telegram", "botToken": "123456789:AAH…", "allowedSender": "412587349" }]
}The agent starts as pending, moves to installing and becomes ready a few minutes later. Model keys and bot tokens are stored encrypted and never returned. GET /agents/catalog lists which providers and chat apps each harness supports.
Limits worth knowing
| Limit | Value |
|---|---|
| Commands and screenshots | 120 a minute per account |
| At once on one desktop | 8 commands and screenshots; more wait in line for up to 30 seconds |
| File uploads and downloads | 100 MB each |
| API keys | 25 per account |
| Agents | 20 per account, one of each harness per desktop |
| Shares | 20 active per desktop |
Errors come back as application/problem+json with a stable code to branch on, like desktop_not_running or desktop_busy, and rate limits include a Retry-After header. Every response carries an X-Request-Id to quote if you need help. The codes are listed in the errors reference.
The same tools for AI apps, over MCP
Everything an AI assistant needs from the API is also exposed as an MCP server at https://api.cubicles.cloud/api/v1/mcp: list and start desktops, run commands, read and write files, take screenshots, and check on agents. Add it to Claude Code, Cursor, VS Code, Codex or Claude Desktop with your API key, and your assistant gets a computer of its own. See give your AI a cloud computer with MCP, the MCP docs, or what is MCP? if it's new to you.
What people build with it
- Report collection. A nightly job downloads the files agents saved during the day and posts them to a team channel.
- Health checks. A script takes a screenshot of each agent's desktop every hour and flags one that looks stuck.
- End-to-end tests on a real desktop. CI runs browser tests in a real Chrome on a real screen, with screenshots of failures.
- Agent orchestration. A coordinating agent hands work to agents on other desktops and collects their results as files.
- Client onboarding. A script sets up a client's agent and emails them a view-only link to watch it.
How it compares with code sandboxes
Code sandbox APIs create a short-lived, usually headless environment for each task, and throw it away after. That's ideal for running untrusted code snippets at scale. Cubicles desktops are the opposite trade: long-lived, with a full desktop and a real browser, keeping their files and logins between tasks, and watchable by a person. If your agent needs to stay signed in and pick up where it left off, you want the second. There's more on this in where should your AI agent run?.
To try it, create a free account, make your free computer and an API key, and run the quickstart above.
Frequently asked questions
Does Cubicles have an API?
Yes. A REST API at https://api.cubicles.cloud/api/v1 covers desktops, commands, files, screenshots, sharing, agents and billing, and an MCP server exposes the main tools to AI apps.
How do I authenticate with the Cubicles API?
Make an API key on the Developers page in the app and send it as Authorization: Bearer cub_… on every request. A key acts as the user who made it.
Can I create computers with the API?
Yes. Your free computer is created at once. A paid one returns a checkout link for a person to pay at, and appears once the payment is confirmed.
Can I run graphical apps through the API?
Yes. Commands run with the desktop's display set, so a graphical app you launch opens on its screen, where you can see it in a screenshot or by opening the computer.
What are the API's rate limits?
Commands and screenshots are limited to 120 a minute per account, with up to 8 running at once on one desktop. Over a limit, the API answers 429 with a Retry-After header.