Cubicles
Cubicles

A cloud desktop API for AI agents: run commands, move files and see the screen

Most of what you do in the Cubicles app, you can also do with an API key: from a script, a CI job, your own product, or an AI assistant over MCP.

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

AreaWhat you can do
DesktopsList them, create the free one, start, stop and restart, and delete
CommandsRun a shell command as the desktop's user and get the exit code and output
FilesUpload to the Desktop folder, list any folder, download any file
ScreenTake a screenshot as a JPEG
SharingCreate view-only links and invitations, list them and end them
AgentsSet up OpenClaw, Hermes, Claude Code, Codex or OpenCode on a desktop, check on them, redeploy and remove them
BillingRead 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:

List your desktops, run a command on one and grab its screen
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.jpg

A 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.

Request and response
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 stdin to bash -s rather than in the command itself.
  • Output: the first 100,000 characters of stdout and stderr each, with truncated set 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.

The free desktop, then an agent on it
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

LimitValue
Commands and screenshots120 a minute per account
At once on one desktop8 commands and screenshots; more wait in line for up to 30 seconds
File uploads and downloads100 MB each
API keys25 per account
Agents20 per account, one of each harness per desktop
Shares20 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.

Give your agent a computer