Cubicle

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.

1 · create a computer with a repo; keep "computer" and "token"
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}'
2 · run a command (returns a run id at once)
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"}'
3 · read the output; repeat with offset=next until done is true
curl -s "https://cubiclecrew.xyz/api/computers/logs?computer=c_...&run=r...&offset=0" \
  -H 'x-computer-token: ct_...'
4 · run a coding agent with your own key
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-..."}'
5 · stop it: unused whole minutes go back
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

Set up your client

Claude Code

claude mcp add --transport http cubicle https://cubiclecrew.xyz/api/mcp

With 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

~/.cursor/mcp.json
{"mcpServers":{"cubicle":{"url":"https://cubiclecrew.xyz/api/mcp"}}}

VS Code

.vscode/mcp.json
{"servers":{"cubicle":{"type":"http","url":"https://cubiclecrew.xyz/api/mcp"}}}

Clients that only run local servers

npx -y mcp-remote https://cubiclecrew.xyz/api/mcp

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

initialize
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"}}}'
reply
{"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: …"}}
tools/call
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.

response (shortened)
{
 "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.

response (shortened)
{ "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.

response
{ "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.

response
{ "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).

snapshot in the response
{ "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/pricing

Other routes

RouteWhat
GET /api/statsPublic counters: computers, sessions, minutes started, commands, agent runs, running now.
GET /api/trialWith a key: your wallet's trial minutes.
GET /api/toolsThe 15 tools with input schemas and HTTP routes.
GET / POST /api/waitlistCounts, and {"feature":"always-on" | "ssh" | "private-repos" | "bigger-machines"} to add yours (one per IP).
/api/credits/info, /key, /balance, /refundsThe shared Credits routes: price and totals, get a key, your balance, the public refund log.

Coding agents

agentRunsKey it needs
claudeclaude -p … --dangerously-skip-permissionsAn Anthropic API key, or a Claude subscription token from claude setup-token (sk-ant-oat…).
codexcodex exec --dangerously-bypass-approvals-and-sandboxAn OpenAI API key.
opencodeopencode runThe key of the provider you pick (anthropic, openai, openrouter, google).
geminigemini --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

SizevCPUMemoryCredits per minute
small24 GB1
medium48 GB2
large816 GB4

Errors

StatuserrorMeaning
400bad_input, needs_credits, confirmA field is wrong (the message says which), or the session needs a trial or credits.
401bad_keyThe API key is wrong or revoked.
402credits, free_limit, needs_credits, trial_usedPlain HTTP 402 with buy instructions (need, buy).
403not_yoursMissing or wrong computer token.
404 / 410not_found, files_expiredNo such computer, run or file; or its files expired.
409not_running, already_running, runningThe computer is in the wrong state for that call.
429free_limit, too_many_running, slow_downFree sessions used up (before launch), too many running, or too many calls.
429wallet_daily_capThis wallet (or IP) used its daily compute budget. The message says what still fits. Nothing is charged.
503compute_off, paused, busy, daily_capacityComputers 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