Docs · v1.0.0
Desk docs: MCP & JSON API
With Desk, AI agents and people alike get cloud computers: Vercel Sandbox Linux microVMs that ship with Node 24, Python 3.14, git, gh, Claude Code, Codex and OpenCode. Each MCP tool doubles as a JSON route under https://deskdigest.site/api/ (CORS *). Send query parameters to GET routes and a JSON body to POST routes. Agents can read this guide as plain text at /llms.txt.
Quickstart
Skip the wallet: each IP gets two free small-computer sessions a day, 10 minutes apiece.
curl -s -X POST https://deskdigest.site/api/computers/create \
-H 'content-type: application/json' \
-d '{"repo":"https://github.com/octocat/Hello-World","minutes":10}'curl -s -X POST https://deskdigest.site/api/computers/run \
-H 'content-type: application/json' -H 'x-computer-token: ct_...' \
-d '{"computer":"c_...","command":"ls -la && node -v"}'curl -s "https://deskdigest.site/api/computers/logs?computer=c_...&run=r...&offset=0" \
-H 'x-computer-token: ct_...'curl -s -X POST https://deskdigest.site/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://deskdigest.site/api/computers/stop \
-H 'content-type: application/json' -H 'x-computer-token: ct_...' \
-d '{"computer":"c_..."}'Auth & tokens
- Computer token. You see it once, in the
create_computerreply:ct_followed by 43 characters, and whoever holds it controls the computer. Pass it in thex-computer-tokenheader, or as"token"inside the JSON body or the MCP arguments. Desk reads it only from a header or body, so keep it out of URLs. - API key. Not required. To get one (
ck_…), use your wallet to sign a message on the home page, or callPOST /api/credits/key. Send it asAuthorization: Bearer ck_…or inx-api-key. Any computer created with a key is owned by your wallet, so the key by itself controls it and lists it from any device; the key also opens up credits and the wallet trial. - Only a SHA-256 hash of each computer token is stored, not the token. A lost token is gone for good, though computers created with a key stay reachable through that key.
Client setup
Claude Code
claude mcp add --transport http desk https://deskdigest.site/api/mcpUsing an API key, for credits and the wallet trial:
claude mcp add --transport http desk https://deskdigest.site/api/mcp --header "Authorization: Bearer ck_..."Cursor
{"mcpServers":{"desk":{"url":"https://deskdigest.site/api/mcp"}}}VS Code
{"servers":{"desk":{"type":"http","url":"https://deskdigest.site/api/mcp"}}}Clients limited to local servers
npx -y mcp-remote https://deskdigest.site/api/mcpMCP endpoint
POST https://deskdigest.site/api/mcp implements the plain flavour of MCP Streamable HTTP: you send JSON-RPC 2.0 and get application/json back, with neither sessions nor server-sent events. It runs protocol 2025-06-18 and still accepts 2025-03-26 and 2024-11-05. Supported methods are initialize, notifications/initialized (HTTP 202), tools/list, tools/call and ping, and a batch may hold up to 10 messages. When a tool fails, the result carries isError: true, and structuredContent holds the same { error, message } the HTTP route would return.
curl -s -X POST https://deskdigest.site/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":"desk","title":"Desk","version":"1.0.0","websiteUrl":"https://deskdigest.site"},
"instructions":"Desk gives you cloud computers: …"}}curl -s -X POST https://deskdigest.site/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_..."}}}'For every tool's input schema and its HTTP route as JSON, see /api/tools.
Tools & routes
Apart from pricing, each call needs either the owner's API key or the computer token. During a paid session, light calls (status, logs, commands, agent runs, files) cost nothing. Per computer, the rate limit is 300 reads and 60 new runs a minute.
create_computer · POST /api/computers/create
Makes a new computer and opens its first session. Give it a public Git repo and it clones into ~/<repo>, which counts as the first run. Arguments: repo (a public https Git URL without credentials), branch, size (small, medium or large; small by default), minutes (5 to 120; defaults to 30 with a key and 10 without), ports (as many as 4, each between 1024 and 65535; defaults 3000, 5173, 8080), name, billing (auto, trial, credits, free). Replies 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
Opens a fresh session on a stopped computer and brings its files back. Arguments: computer, token, minutes, size (you can switch sizes between sessions), billing, fresh (set true to boot a clean computer when the old files have expired). Replies with the computer, shaped like status. A computer that is already up gives 409 already_running; expired files without fresh give 410 files_expired, refunded.
extend_computer · POST /api/computers/extend
Puts more minutes (15 by default) on a running session, charged to the wallet trial or credits. You cannot extend a free session. Counting from its start, a session never runs past 2 hours, and extra minutes also have to fit the daily budget described below.
stop_computer · POST /api/computers/stop
Ends the session and saves the disk automatically, ready for the next start. Each whole minute you didn't use is returned, starting with the most recent payment.
{ "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. You get the same shape as create, minus the token: state, seconds remaining, preview URLs during a session, the latest 30 runs with exit codes, snapshots, and the expiry date of a stopped computer's files. Because it asks the provider, a session that ended by itself shows up as stopped.
curl -s "https://deskdigest.site/api/computers/status?computer=c_..." -H 'x-computer-token: ct_...'list_computers · GET or POST /api/computers/list
Using an API key, it returns your wallet's computers plus the wallet trial ({ minutes, used, left }). With no key, POST {"computers":[{"computer":"c_…","token":"ct_…"}]} for up to 20 computers; any pair whose token is wrong gets skipped.
run_command · POST /api/computers/run
Starts command (bash, at most 8000 characters) in the background inside cwd (the repo by default, otherwise ~), replying 202 with a run id right away. Use env for up to 20 variables scoped to this run; their values are never stored. A dev server stays up until you stop its 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://deskdigest.site/api/computers/logs?computer=c_0iy4ab7rey81&run=rc551298d61&offset=0" }run_agent · POST /api/computers/agent
Launches a coding agent CLI in non-interactive mode. Arguments: agent (claude, codex, opencode or gemini; claude by default), prompt (at most 20000 characters), apiKey (your own model key), model, provider (only for opencode: anthropic, openai, openrouter, google), cwd. Like run_command, it replies 202 with a run id. Details under Coding agents.
read_logs · GET /api/computers/logs
Query: computer, run, offset (in bytes, 0 by default), max (1024 to 65536). Output combines stdout and stderr. Keep polling with offset=next until done; chunks never cut a UTF-8 character in half. Once the computer stops, only the last 4 KB comes back (live: false), while the complete log remains on its disk at ~/.desk/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
Signals SIGTERM to every process in a run's group. Arguments: computer, run. The run then exits with code 143.
read_file · GET /api/computers/file
Query: computer, path (~ works). Returns at most 256 KB as { path, size, truncated, text }; binary files come as base64 in place of text. A missing file gives 404.
snapshot_computer · POST /api/computers/snapshot
Stores the disk as a named snapshot (label). The computer stops when the snapshot is taken, and unused minutes are returned. With a wallet a computer holds its 3 most recent snapshots; without one, 1.
{ "id": "snap_16bc2b22b14f", "label": "tests passing", "t": "…", "sizeBytes": 412000000, "expiresAt": "…" }restore_snapshot · POST /api/computers/restore
Resets a stopped computer to one of its snapshots (snapshot), which the next start then boots from.
delete_computer · POST /api/computers/delete
Permanently stops and removes the computer, its files and its snapshots at the provider. Requires "confirm": "delete".
pricing · GET /api/pricing
Open, no auth needed. Reports current availability (available, plus code/reason when it is false), each size with its credits per minute, the free tier and trial, the caps, file retention, the supported agents and the number of computers running now.
curl -s https://deskdigest.site/api/pricingMore routes
| Route | Use |
|---|---|
GET /api/stats | Public counts of computers, sessions, minutes started, commands, agent runs and those running now. |
GET /api/trial | Needs a key; returns your wallet's trial minutes. |
GET /api/tools | All 15 tools, each with its input schema and HTTP route. |
GET / POST /api/waitlist | Read the counts, or send {"feature":"always-on" | "ssh" | "private-repos" | "bigger-machines"} to vote (one per IP). |
/api/credits/info, /key, /balance, /refunds | Shared Credits routes: price and totals, issuing a key, your balance and the public refund log. |
Coding agents
| agent | Command | Key to pass |
|---|---|---|
claude | claude -p … --dangerously-skip-permissions | Anthropic API key, or a Claude subscription token made with claude setup-token (sk-ant-oat…). |
codex | codex exec --dangerously-bypass-approvals-and-sandbox | OpenAI API key. |
opencode | opencode run | A key for whichever provider you choose (anthropic, openai, openrouter, google). |
gemini | gemini --yolo -p … (installed the first time it runs) | Google AI Studio key. |
Inside the microVM, which acts as its sandbox, the agent has full permissions. Both prompt and key reach the process through environment variables, so none of your input is pasted into a shell. Model usage goes on your provider's bill. To list the run, Desk saves the prompt's first 200 characters; the key is never saved.
Limits & free tier
| Size | vCPU | Memory | Credits per minute |
|---|---|---|---|
| small | 2 | 4 GB | 1 |
| medium | 4 | 8 GB | 2 |
| large | 8 | 16 GB | 4 |
- Free: each IP gets 2 small sessions a day of up to 10 minutes, with a global ceiling of 40 free sessions per day. The count resets at 00:00 UTC.
- Wallet trial: a single 30-minute block of small computer time per wallet, with at most 20 new trials a day. Requires a free API key.
- Credits: all sizes, sessions of 5 minutes to 2 hours, charged up front; whole minutes left when you stop early are returned.
- Session length: 2 hours maximum, enforced as a hard cap (
DESK_MAX_SESSION_MINUTES). Processes stop when the session does; computers are not always on. - Daily compute budget: each running minute is billed to the operator in dollars by Vercel, while credits sell at a fixed $DESK price whose value can fall below that. That is why every session combined, free and trial ones too, is capped at $10 of Vercel time per UTC day, and any single wallet (or IP, without a wallet) at $3. Starting or extending a session sets aside the worst-case cost, and stopping early frees the minutes it did not use. Hitting the overall budget returns 503
daily_capacityand hitting yours returns 429wallet_daily_cap, both before any charge. Today's remaining budget sits underbudgetinGET /api/pricing. - Cost model: priced at Vercel Sandbox list rates, $0.128 per vCPU-hour of active CPU plus $0.0212 per GB-hour of memory, assuming every vCPU is busy. That works out to small $0.34, medium $0.68 and large $1.36 an hour, so $3 covers roughly 8.8 hours of small, 4.4 of medium or 2.2 of large per day. Actual bills tend to be lower because idle CPU time isn't billed.
- Files: retained 14 days from last use with a wallet and 1 day without, after which they expire. Disk size is 64 GB.
- Caps: 3 computers running at once across all users (
DESK_MAX_RUNNING), 2 per wallet (or per IP if there's no wallet), 10 stored computers per wallet and 4 preview ports at most. Once the shared running cap is full, starts get 503busy. - Network: outbound internet access is open. Preview URLs stay public for as long as the computer runs. Region is US East (iad1).
- Not yet: always-on computers, SSH, an interactive terminal and a GitHub app for private repos are on the waitlist. Private repos work now if you set
GH_TOKENin a command'senvand rungh repo clone owner/name.
Errors
| Status | error | What it means |
|---|---|---|
| 400 | bad_input, needs_credits, confirm | Some field is invalid (the message names it), or the session requires a trial or credits. |
| 401 | bad_key | Invalid or revoked API key. |
| 402 | credits, free_limit, needs_credits, trial_used | Standard HTTP 402 carrying buy instructions (need, buy). |
| 403 | not_yours | The computer token is absent or incorrect. |
| 404 / 410 | not_found, files_expired | The computer, run or file doesn't exist, or its files have expired. |
| 409 | not_running, already_running, running | That call doesn't fit the computer's current state. |
| 429 | free_limit, too_many_running, slow_down | Out of free sessions (pre-launch), too many computers running, or calls coming too fast. |
| 429 | wallet_daily_cap | The wallet (or IP) has spent its daily compute budget; the message tells you what still fits. No charge. |
| 503 | compute_off, paused, busy, daily_capacity | Computers are offline, all 3 slots are in use, or the day's compute budget is spent (it reopens at 00:00 UTC). No charge. |
Errors are never charged, and a session that fails to start gets a full refund.
Data we keep
Per computer we keep its id, name, size, repo, ports, owner wallet if there is one, a hash of its token, session times and billing, each command's first 300 characters, each agent prompt's first 200, and each run's last 4 KB of output, so a stopped computer can still show how its runs finished. Model keys and env values are never kept. Free sessions and waitlist votes are counted by a salted hash of your IP. Deleting a computer wipes its files and snapshots at the provider. Avoid printing secrets in command output.
Credits & $DESK
Trying Desk is free. Longer or larger sessions run on credits, where 1 credit equals 1 minute of a small computer. To get credits you burn $DESK through the shared Credits contract on Robinhood Chain (approve, then buyFor(account, credits, maxBurn)), either on the home page or straight from your wallet. Burned tokens are destroyed, and credits cannot be sold back. The owner's only powers are pausing purchases and moving the price per credit within caps fixed in the contract. Holders are promised nothing else.
Desk's agent has a published ERC-8004 registration file.
Changelog
v1.0.0 · 2026-11-16
- Three sizes of cloud computer on Vercel Sandbox, billed per minute, with sessions of up to 2 hours and files that persist between them.
- Hard limits on the operator's Vercel spend: 3 computers running at once and a daily compute budget ($10 overall, $3 per wallet). A refused start costs nothing.
- Clone a public repo on boot; run shell commands and coding agents (Claude Code, Codex, OpenCode, Gemini CLI) on your own key.
- Byte-offset logs, preview URLs on up to 4 ports, file reads, named snapshots you can restore, and delete.
- A remote MCP server (15 tools), a CORS-enabled JSON API, /llms.txt and this documentation.
- A free tier and a one-time wallet trial; credits paid for by burning $DESK; refunds of unused minutes, plus a public refund log.