ParallelSandbox
Open app

Tool reference

Everything an agent can do with ParallelSandbox goes through these MCP tools. All of them carry the tenant's API key. Names, inputs and outputs are the frozen contract; the same tools are exposed by the streamable HTTP endpoint https://mcp.parallelsandbox.com/mcp and by the stdio adapter parallelsandbox-mcp on npm.

Boxes

Tool Input Output
sandbox_start services[{name, port}], externalBaseUrl, secrets (list of names), idleTimeoutMin (optional) id, sceneUrl, takeoverUrl, status, startedFrom (spare, snapshot or cold)
sandbox_exec id, cmd, cwd, timeoutSec, background stdout, stderr, exitCode, bgId
sandbox_sync id, localPath, dest ok
sandbox_get id, path presigned download URL, valid 1 hour
sandbox_wire id, service, mode (box or external) current wiring table
sandbox_shot id, target (screen or url), record (start or stop) presigned URL
sandbox_status id status, boxd health, wiring table, takeoverUrl, interrupted reason
sandbox_stop id ok
sandbox_publish_version service, label, image, gitSha, note versionId
sandbox_versions none list
sandbox_takeover id, note the note the person leaves when handing back; waits up to 30 minutes
sandbox_secrets none list of names, never values

sandbox_start

  • services: the names and ports your repo exposes on the box. A name becomes wireable: after sandbox_wire it resolves inside the box to that port (box) or to externalBaseUrl (external). Ports must be published on the box, which docker compose does with ports:.
  • externalBaseUrl: where unchanged services live, for example your staging environment. Optional.
  • secrets: names from sandbox_secrets to inject as environment variables when the box is claimed. Nothing is injected unless listed.
  • idleTimeoutMin: stop the box after this many minutes without a tool call. There is no platform default and no maximum lifetime; a box runs until you stop it or your credits reach zero.
  • startedFrom: spare means a warm box was claimed (ready in under 15 seconds); snapshot means a microVM was restored from a snapshot (a few seconds); cold means a machine was started for you (under 90 seconds).

Free accounts can run 3 boxes at once, Pro 5, Max 20.

sandbox_exec

  • cwd is relative to /work, the box's working directory, and defaults to it.
  • timeoutSec bounds foreground commands. Use background: true for servers and long builds; you get a bgId, and the output is in a log file under /work/.sbx/ that you can read with another sandbox_exec.
  • While a person is connected through takeoverUrl, sandbox_exec returns a locked error instead of running. Wait and retry.
  • The box's virtual display is :99. Anything you want to see in sandbox_shot or through takeoverUrl must run with DISPLAY=:99.

sandbox_sync and sandbox_get

  • sandbox_sync tars a local directory (localPath, relative to the agent's working directory) and unpacks it at /work/<dest>. node_modules, .git, dist, build and similar are excluded. Use it for uncommitted work; use git clone in sandbox_exec for committed work.
  • sandbox_get returns a presigned download URL for a file or directory under /work. Directories come back as a tar.gz. The URL expires after one hour.

sandbox_wire

  • mode: "box": the service name resolves, inside the box, to the box itself on the port declared at start.
  • mode: "external": the service name resolves to externalBaseUrl.
  • The return value is the whole wiring table, not just the service you changed.
  • Services inside one docker compose project already reach each other through the compose network; wiring is for everything else on the box (test runners, Chromium, other containers, the scene URL).

sandbox_shot

  • No record: a screenshot. target: "screen" (default) captures the virtual display; target: "url" opens the URL in a fresh Chromium on the display and captures it.
  • record: "start" begins recording the display to mp4; record: "stop" ends it and returns the presigned URL.

sandbox_takeover

Blocks until a person hands the box back, or 30 minutes pass. The person sees your note in the app, works on the live screen, presses Hand back, and can leave a message; that message is the tool result. Use it for logins, CAPTCHAs, payment confirmations, anything you must not do alone.

Versions

sandbox_publish_version records an image you pushed to your tenant's registry as a named version of a service, so other boxes (or other agents on your team) can run it without rebuilding. sandbox_versions lists them. The image reference must be inside your tenant's registry namespace; sandbox_status includes the registry login you need.

Logs

Tool Input Output
logs_search project, since, query, boxId rows
logs_errors project, since, boxId rows, stacks resolved through uploaded source maps
logs_tail project, boxId stream

project is a log project created in the app; pages send logs to it with the browser SDK. since accepts a duration (10m, 2h, 7d) or an ISO timestamp. boxId narrows to logs emitted from pages running inside one box. Logs are kept without expiry.

Box states

spare → claimed → ready → takeover (optional) → stopping → terminated
                     ↕
                   frozen

A microVM box that sits idle is frozen: its memory is snapshotted and it stops billing box time. Any tool call on it thaws it first (a couple of seconds); sandbox_stop works on a frozen box too. Nothing is lost.

Any state can turn into interrupted: the underlying spot machine was reclaimed by the cloud. sandbox_status reports the reason; the next tool call on that box returns the same. Start a new box and rerun; nothing on an interrupted box survives.

REST

For the web and desktop apps, and for anything that is not an agent. Same API key, Authorization: Bearer.

Endpoint Purpose
/v1/auth/github GitHub login
/v1/keys create and revoke API keys
/v1/boxes list and inspect boxes
/v1/boxes/{id}/screencast live screen, WebSocket
/v1/boxes/{id}/input mouse and keyboard input
/v1/takeovers pending takeover requests
/v1/takeovers/{id}/return hand a box back with a note
GET /v1/secrets, PUT /v1/secrets/{name}, DELETE /v1/secrets/{name} manage secrets
/v1/versions published versions
/v1/usage usage events
/v1/credits credit balance and buckets
/v1/billing/checkout Stripe Checkout
/v1/billing/portal Stripe customer portal
/v1/billing/webhook Stripe webhook
/v1/projects (log.parallelsandbox.com) log projects
/v1/projects/{id}/sourcemaps (log.parallelsandbox.com) upload source maps

Other facts

  • Scene URL: https://<id>.box.parallelsandbox.com, reaching the box through the edge.
  • Takeover token: an HMAC containing the box id and an expiry. The box only accepts one-time tokens issued by the control plane.
  • Usage events, one per minute per running box and one per metered action: tenant, box, kind, quantity, unit, cost_usd, credits, at.
  • Boxes cannot see each other and hold no cloud credentials.