Deskcloud Linux for AI agents

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.

1 · boot a computer from a repo; save the "computer" and "token" values
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}'
2 · start a command (a run id comes back right away)
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"}'
3 · fetch output; call again with offset=next until done is true
curl -s "https://deskdigest.site/api/computers/logs?computer=c_...&run=r...&offset=0" \
  -H 'x-computer-token: ct_...'
4 · hand a task to a coding agent on your own key
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-..."}'
5 · stop: whole unused minutes are returned
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

Client setup

Claude Code

claude mcp add --transport http desk https://deskdigest.site/api/mcp

Using 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

~/.cursor/mcp.json
{"mcpServers":{"desk":{"url":"https://deskdigest.site/api/mcp"}}}

VS Code

.vscode/mcp.json
{"servers":{"desk":{"type":"http","url":"https://deskdigest.site/api/mcp"}}}

Clients limited to local servers

npx -y mcp-remote https://deskdigest.site/api/mcp

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

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

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

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.

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

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

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

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.

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

More routes

RouteUse
GET /api/statsPublic counts of computers, sessions, minutes started, commands, agent runs and those running now.
GET /api/trialNeeds a key; returns your wallet's trial minutes.
GET /api/toolsAll 15 tools, each with its input schema and HTTP route.
GET / POST /api/waitlistRead the counts, or send {"feature":"always-on" | "ssh" | "private-repos" | "bigger-machines"} to vote (one per IP).
/api/credits/info, /key, /balance, /refundsShared Credits routes: price and totals, issuing a key, your balance and the public refund log.

Coding agents

agentCommandKey to pass
claudeclaude -p … --dangerously-skip-permissionsAnthropic API key, or a Claude subscription token made with claude setup-token (sk-ant-oat…).
codexcodex exec --dangerously-bypass-approvals-and-sandboxOpenAI API key.
opencodeopencode runA key for whichever provider you choose (anthropic, openai, openrouter, google).
geminigemini --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

SizevCPUMemoryCredits per minute
small24 GB1
medium48 GB2
large816 GB4

Errors

StatuserrorWhat it means
400bad_input, needs_credits, confirmSome field is invalid (the message names it), or the session requires a trial or credits.
401bad_keyInvalid or revoked API key.
402credits, free_limit, needs_credits, trial_usedStandard HTTP 402 carrying buy instructions (need, buy).
403not_yoursThe computer token is absent or incorrect.
404 / 410not_found, files_expiredThe computer, run or file doesn't exist, or its files have expired.
409not_running, already_running, runningThat call doesn't fit the computer's current state.
429free_limit, too_many_running, slow_downOut of free sessions (pre-launch), too many computers running, or calls coming too fast.
429wallet_daily_capThe wallet (or IP) has spent its daily compute budget; the message tells you what still fits. No charge.
503compute_off, paused, busy, daily_capacityComputers 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