Docs · v1.0.0
Cubicle API & MCP
Cubicle gives people and AI agents cloud computers: Linux microVMs on Vercel Sandbox with Node 24, Python 3.14, git, gh, Claude Code, Codex and OpenCode installed. Every MCP tool is also a JSON route under https://cubiclecrew.xyz/api/, with CORS *. GET routes take query parameters; POST routes take a JSON body. The same guide in plain text for agents is at /llms.txt.
Quickstart
No wallet needed: a small computer for up to 10 minutes is free, twice a day per IP.
curl -s -X POST https://cubiclecrew.xyz/api/computers/create \
-H 'content-type: application/json' \
-d '{"repo":"https://github.com/octocat/Hello-World","minutes":10}'curl -s -X POST https://cubiclecrew.xyz/api/computers/run \
-H 'content-type: application/json' -H 'x-computer-token: ct_...' \
-d '{"computer":"c_...","command":"ls -la && node -v"}'curl -s "https://cubiclecrew.xyz/api/computers/logs?computer=c_...&run=r...&offset=0" \
-H 'x-computer-token: ct_...'curl -s -X POST https://cubiclecrew.xyz/api/computers/agent \
-H 'content-type: application/json' -H 'x-computer-token: ct_...' \
-d '{"computer":"c_...","agent":"claude","prompt":"Add a /health route and run the tests","apiKey":"sk-ant-..."}'curl -s -X POST https://cubiclecrew.xyz/api/computers/stop \
-H 'content-type: application/json' -H 'x-computer-token: ct_...' \
-d '{"computer":"c_..."}'Auth & tokens
- Computer token.
create_computerreturns a token (ct_+ 43 characters) once. It controls that computer. Send it as thex-computer-tokenheader, or as"token"in a JSON body or MCP arguments. Never put it in a URL; Cubicle only reads it from a header or a body. - API key. Optional. Sign a message with your wallet on the home page (or
POST /api/credits/key) to get a key (ck_…). Send it asAuthorization: Bearer ck_…orx-api-key. Computers you create with a key belong to your wallet: the key alone controls them and lists them on any device, and it unlocks the wallet trial and credits. - We store a SHA-256 hash of each computer token, never the token itself. Lost tokens can't be recovered; computers made with a key can still be reached with the key.
Set up your client
Claude Code
claude mcp add --transport http cubicle https://cubiclecrew.xyz/api/mcpWith an API key (credits and your wallet's trial):
claude mcp add --transport http cubicle https://cubiclecrew.xyz/api/mcp --header "Authorization: Bearer ck_..."Cursor
{"mcpServers":{"cubicle":{"url":"https://cubiclecrew.xyz/api/mcp"}}}VS Code
{"servers":{"cubicle":{"type":"http","url":"https://cubiclecrew.xyz/api/mcp"}}}Clients that only run local servers
npx -y mcp-remote https://cubiclecrew.xyz/api/mcpMCP endpoint
POST https://cubiclecrew.xyz/api/mcp speaks MCP Streamable HTTP in its simple form: JSON-RPC 2.0 messages in, application/json replies out, no sessions and no server-sent events. Protocol 2025-06-18 (also answers 2025-03-26 and 2024-11-05). Methods: initialize, notifications/initialized (answered with HTTP 202), tools/list, tools/call, ping. Batches of up to 10 messages work. Tool errors come back as a result with isError: true and the same { error, message } as the HTTP route in structuredContent.
curl -s -X POST https://cubiclecrew.xyz/api/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"me","version":"1"}}}'{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",
"capabilities":{"tools":{"listChanged":false}},
"serverInfo":{"name":"cubicle","title":"Cubicle","version":"1.0.0","websiteUrl":"https://cubiclecrew.xyz"},
"instructions":"Cubicle gives you cloud computers: …"}}curl -s -X POST https://cubiclecrew.xyz/api/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"computer_status","arguments":{"computer":"c_...","token":"ct_..."}}}'The tool list as JSON, with input schemas and the matching HTTP route: /api/tools.
Tools & routes
Every call except pricing needs the computer token or the owner's API key. Light calls (status, logs, commands, agent runs, files) are free while a paid session runs. Each computer allows up to 300 reads and 60 new runs a minute.
create_computer · POST /api/computers/create
Creates a computer and starts its first session. Optionally clones a public Git repo into ~/<repo> (that clone is the first run). Arguments: repo (public https Git URL, no credentials), branch, size (small, medium, large; default small), minutes (5 to 120; default 30 with a key, 10 without), ports (up to 4, from 1024 to 65535; default 3000, 5173, 8080), name, billing (auto, trial, credits, free). Returns 201.
{
"computer": "c_0iy4ab7rey81", "name": "Hello-World", "state": "running",
"size": "small", "vcpus": 2, "memoryGb": 4,
"repo": "https://github.com/octocat/Hello-World", "branch": null, "workdir": "~/Hello-World",
"ports": [3000, 5173, 8080], "owner": null,
"session": { "n": 1, "started": "…", "until": "…", "minutesPaid": 10, "billing": "free",
"secondsLeft": 600, "ended": null, "endReason": null, "refunded": null },
"previews": [{ "port": 3000, "url": "https://sb-….vercel.run" }, …],
"runs": [{ "run": "rf8bc0a03f3", "kind": "clone", "label": "git clone --depth 1 https://github.com/octocat/Hello-World",
"cwd": "~", "done": false, "exitCode": null, "session": 1 }],
"snapshots": [], "filesKeptUntil": null,
"token": "ct_…", "tokenNote": "Keep this computer token: …",
"clone": { "run": "rf8bc0a03f3" }
}start_computer · POST /api/computers/start
Starts a new session on a stopped computer with its files restored. Arguments: computer, token, minutes, size (may change between sessions), billing, fresh (true boots a clean computer if the old files expired). Returns the computer, as in status. 409 already_running if it runs; 410 files_expired (refunded) if its files are gone and fresh is not set.
extend_computer · POST /api/computers/extend
Adds minutes (default 15) to a running session, paid by the wallet trial or credits. Free sessions can't be extended. One session lasts at most 2 hours from its start, and the added minutes must fit the daily budget (below).
stop_computer · POST /api/computers/stop
Stops the session. The disk is saved automatically and restored on the next start. Every whole unused minute goes back, newest payment first.
{ "computer": "c_…", "state": "stopped", "stopped": true,
"session": { "n": 2, "minutesPaid": 25, "billing": "paid", "ended": "…", "endReason": "stopped",
"refunded": { "credits": 19, "trialMinutes": 5, "minutes": 24 } },
"gaveBack": { "credits": 19, "trialMinutes": 5, "minutes": 24 },
"filesKeptUntil": "…", "note": "Files are saved automatically and restored on the next start." }computer_status · GET /api/computers/status
Query: computer. Header: x-computer-token or your API key. Returns the computer as in create (without the token): state, seconds left, preview URLs while running, the last 30 runs with exit codes, snapshots, and when stopped files expire. It checks the provider, so a session that ended on its own shows as stopped.
curl -s "https://cubiclecrew.xyz/api/computers/status?computer=c_..." -H 'x-computer-token: ct_...'list_computers · GET or POST /api/computers/list
With an API key: your wallet's computers and the wallet's trial ({ minutes, used, left }). Without one, POST {"computers":[{"computer":"c_…","token":"ct_…"}]} (up to 20); pairs with a wrong token are skipped.
run_command · POST /api/computers/run
Runs command (bash, up to 8000 characters) in the background in cwd (default: the repo, else ~) and returns 202 with a run id at once. env sets up to 20 variables for this run only; values are never stored. Dev servers keep running until you stop the run or the session ends.
{ "computer": "c_0iy4ab7rey81", "run": "rc551298d61", "kind": "command", "label": "npm test",
"cwd": "~/Hello-World", "started": "…", "done": false, "exitCode": null, "session": 1,
"logs": "https://cubiclecrew.xyz/api/computers/logs?computer=c_0iy4ab7rey81&run=rc551298d61&offset=0" }run_agent · POST /api/computers/agent
Runs a coding agent CLI non-interactively. Arguments: agent (claude, codex, opencode, gemini; default claude), prompt (up to 20000 characters), apiKey (your model key), model, provider (opencode only: anthropic, openai, openrouter, google), cwd. Returns 202 with a run id, like run_command. See Coding agents.
read_logs · GET /api/computers/logs
Query: computer, run, offset (bytes, default 0), max (1024 to 65536). stdout and stderr together. Poll with offset=next until done; a chunk never splits a UTF-8 character. When the computer is stopped you get the last 4 KB (live: false); the full log stays on its disk at ~/.cubicle/runs/<run>.log.
{ "computer": "c_0iy4ab7rey81", "run": "rc551298d61", "live": true, "done": true, "exitCode": 0,
"offset": 0, "next": 34, "size": 34, "data": "héllo ✓\nHello World!\nsecret-ok\n" }stop_run · POST /api/computers/kill
Sends SIGTERM to a run's whole process group. Arguments: computer, run. The run ends with exit code 143.
read_file · GET /api/computers/file
Query: computer, path (~ allowed). Up to 256 KB: { path, size, truncated, text }, or base64 instead of text for binary files. 404 if there is no file.
snapshot_computer · POST /api/computers/snapshot
Saves a named snapshot (label) of the disk. Taking a snapshot stops the computer; unused minutes go back. A computer keeps its 3 newest snapshots with a wallet (1 without).
{ "id": "snap_16bc2b22b14f", "label": "tests passing", "t": "…", "sizeBytes": 412000000, "expiresAt": "…" }restore_snapshot · POST /api/computers/restore
Rolls a stopped computer back to one of its snapshots (snapshot); the next start boots from it.
delete_computer · POST /api/computers/delete
Stops and deletes the computer with its files and snapshots at the provider, for good. Needs "confirm": "delete".
pricing · GET /api/pricing
No auth. Whether computers are available right now (available, and code/reason when not), sizes and credits per minute, the free tier, the trial, caps, how long files are kept, the agents and how many computers run now.
curl -s https://cubiclecrew.xyz/api/pricingOther routes
| Route | What |
|---|---|
GET /api/stats | Public counters: computers, sessions, minutes started, commands, agent runs, running now. |
GET /api/trial | With a key: your wallet's trial minutes. |
GET /api/tools | The 15 tools with input schemas and HTTP routes. |
GET / POST /api/waitlist | Counts, and {"feature":"always-on" | "ssh" | "private-repos" | "bigger-machines"} to add yours (one per IP). |
/api/credits/info, /key, /balance, /refunds | The shared Credits routes: price and totals, get a key, your balance, the public refund log. |
Coding agents
| agent | Runs | Key it needs |
|---|---|---|
claude | claude -p … --dangerously-skip-permissions | An Anthropic API key, or a Claude subscription token from claude setup-token (sk-ant-oat…). |
codex | codex exec --dangerously-bypass-approvals-and-sandbox | An OpenAI API key. |
opencode | opencode run | The key of the provider you pick (anthropic, openai, openrouter, google). |
gemini | gemini --yolo -p … (installed on first use) | A Google AI Studio key. |
The agent works with full permissions inside the microVM, which is its sandbox. The prompt and the key reach the process as environment variables, so nothing you send is pasted into a shell. Your model usage is billed by your provider. Cubicle keeps the first 200 characters of the prompt to list the run, and never the key.
Free tier & limits
| Size | vCPU | Memory | Credits per minute |
|---|---|---|---|
| small | 2 | 4 GB | 1 |
| medium | 4 | 8 GB | 2 |
| large | 8 | 16 GB | 4 |
- Free: 2 sessions a day per IP, small, up to 10 minutes; at most 40 free sessions a day for everyone together. Resets at 00:00 UTC.
- Wallet trial: 30 minutes of small computer time, once per wallet (up to 20 new trials a day). Needs a free API key.
- Credits: any size, 5 minutes to 2 hours per session, paid up front. Stop early and unused whole minutes go back.
- Session length: at most 2 hours, a hard cap (
CUBICLE_MAX_SESSION_MINUTES). When it ends, processes stop. Computers are not always on. - Daily compute budget: Vercel bills the operator in dollars for every minute a computer runs, and credits are bought at a fixed $CUBICLE price that may be worth less than that. So all sessions together, free and trial included, may cost at most $10 of Vercel time per UTC day, and one wallet (or one IP without a wallet) at most $3. Each session reserves its worst-case cost when it starts or is extended; stopping early releases the unused minutes. Past the daily budget you get 503
daily_capacity, past your own 429wallet_daily_cap, before anything is charged.GET /api/pricingshows what is left today underbudget. - Cost model: Vercel Sandbox list prices of $0.128 per vCPU-hour of active CPU and $0.0212 per GB-hour of memory, counting every vCPU as busy: small $0.34, medium $0.68, large $1.36 an hour. So $3 a day is about 8.8 hours of small, 4.4 of medium or 2.2 of large. Real bills are usually lower, since idle CPU is not billed.
- Files: kept 14 days after last use with a wallet, 1 day without, then they expire. 64 GB disk.
- Caps: at most 3 computers run at once for everyone together (
CUBICLE_MAX_RUNNING), 2 per wallet (or per IP without one), 10 computers kept per wallet, up to 4 preview ports. When everyone's running computers reach the cap you get 503busy. - Network: computers can reach the internet. Preview URLs are public while the computer runs. Region: US East (iad1).
- Not yet: SSH, an interactive terminal, always-on computers and a GitHub app for private repos (waitlist). For private repos today, pass
GH_TOKENin a command'senvand rungh repo clone owner/name.
Errors
| Status | error | Meaning |
|---|---|---|
| 400 | bad_input, needs_credits, confirm | A field is wrong (the message says which), or the session needs a trial or credits. |
| 401 | bad_key | The API key is wrong or revoked. |
| 402 | credits, free_limit, needs_credits, trial_used | Plain HTTP 402 with buy instructions (need, buy). |
| 403 | not_yours | Missing or wrong computer token. |
| 404 / 410 | not_found, files_expired | No such computer, run or file; or its files expired. |
| 409 | not_running, already_running, running | The computer is in the wrong state for that call. |
| 429 | free_limit, too_many_running, slow_down | Free sessions used up (before launch), too many running, or too many calls. |
| 429 | wallet_daily_cap | This wallet (or IP) used its daily compute budget. The message says what still fits. Nothing is charged. |
| 503 | compute_off, paused, busy, daily_capacity | Computers are offline, 3 are already running, or today's compute budget is used up (reopens 00:00 UTC). Nothing is charged. |
A session that fails to start is refunded in full. Nothing is charged on any error.
What we store
For each computer: its id, name, size, repo, ports, owner wallet (if any), a hash of its token, session times and billing, the first 300 characters of each command, the first 200 of each agent prompt, and the last 4 KB of each run's output (so a stopped computer still shows how its runs ended). Never model keys or env values. A salted hash of your IP counts free sessions and waitlist votes. Deleting a computer removes its files and snapshots at the provider. Don't print secrets in your commands' output.
Credits & $CUBICLE
Cubicle is free to try. Credits pay for longer and bigger sessions: 1 credit is 1 minute of a small computer. You buy them by burning $CUBICLE through the shared Credits contract on Robinhood Chain (buyFor(account, credits, maxBurn) after an approve), from the home page or your own wallet. Burned tokens are gone for good and credits can't be sold back. The owner can only change the price per credit within caps written into the contract and pause buying. Nothing else is promised to holders.
Cubicle publishes an ERC-8004 registration file for its agent: registration file.
Changelog
v1.0.0 · 2026-11-16
- Cloud computers on Vercel Sandbox in three sizes, paid by the minute, sessions up to 2 hours, files saved between sessions.
- Hard caps that bound the operator's Vercel bill: 3 computers at once and a daily compute budget ($10 for everyone, $3 per wallet). Refused starts charge nothing.
- Public repo clone at start; shell commands and coding agent runs (Claude Code, Codex, OpenCode, Gemini CLI) with your own key.
- Logs by byte offset, preview URLs for up to 4 ports, file reads, named snapshots with restore, delete.
- Remote MCP server with 15 tools, JSON API with CORS, /llms.txt and these docs.
- Free tier, a one-time wallet trial, credits by burning $CUBICLE, refunds for unused minutes and a public refund log.