Tool reference

Everything an agent can do with ParallelSandbox goes through these MCP tools. You sign in once with OAuth when you connect (Quick start); every call then acts on the account you signed in to. The streamable HTTP endpoint https://mcp.parallelsandbox.com/mcp and the stdio adapter parallelsandbox-mcp on npm expose the same tools. sandbox_sync and sandbox_pull read and write the agent's own disk, so they only work through the adapter; over plain HTTP they return an error that says so. The AI configures each client using SKILL.md. The adapter also uses OAuth by default; while sign-in is pending, parallelsandbox_connect returns the sign-in link.

Each tool, and each topic the tools share, has a page of its own; this page lists them all, with what each is for. Every page is also plain Markdown at its own URL plus index.md (for example /en/docs/tools/sandbox-start/index.md), and llms-full.txt has all the English pages in one file.

Boxes

`sandbox_start`

Starts a new box for a goal: the services your repo exposes, each under a name of its own, and optionally an environment, secrets, a size and toolchains. Returns the box id, its URLs and the services it received.

`sandbox_list`

Lists the account's boxes, teammates' included, most recently used first, with each box's name, goal, state and URLs. It only reads and never wakes a box.

`sandbox_media`

Lists the screenshots and recordings that steps left in every box of the account, stopped boxes included, by time, with each box's name and goal and a download URL for each picture. Use it to gather what was built and checked over a period. It only reads and never wakes a box.

`sandbox_status`

Everything about one box: its state, goal, the last 30 steps done in it, whether the conversation using it is still at it, its wiring, services, running commands and credits. It only reads.

`sandbox_stop`

Stops a box for good and releases its machine and devices; everything under /work is gone. Call it as soon as there is nothing left for the person to see.

Finishing a box

How to end work on a box: sandbox_review when the person should try the result, sandbox_stop when there is nothing to see, and what each leaves behind.

Picking up a box another conversation left

How a conversation continues a box another one left: find it with sandbox_list, read its goal, steps[] and agent with sandbox_status, and ask the person first when the other conversation may still be at it.

`sandbox_exec`

Runs one shell command in the box, in the foreground with a timeout or in the background with a log file. While the screen changes, a foreground step keeps a screenshot and a recording for the person.

`sandbox_procs`

Lists, waits for or stops the commands started with sandbox_exec and background: true. Use it instead of pkill -f or pgrep -f, whose pattern matches every process whose command line holds it, other jobs included.

`sandbox_sync`, `sandbox_get` and `sandbox_pull`

Three tools move files between your machine and the box.

`sandbox_sync`

Uploads a local directory, or one file, into /work/<dest> in the box, sending only the files that differ. Runs only through the stdio adapter.

`sandbox_get`

Gets a file or directory under /work, /tmp or /dev/shm as a download URL valid for an hour (a directory as a tar.gz); small images also come back inline.

`sandbox_pull`

sandbox_get plus the download: writes a file from the box to a local path, or unpacks a directory into it. Runs only through the stdio adapter.

`sandbox_build`

Runs an install or compile step and keeps its output, so a box with the same inputs restores it in seconds instead of building again.

`sandbox_wire`

Switches a declared name between your process in the box and externalBaseUrl, declares a new name on a running box, or points a name at another box or a published version.

Links to other boxes

A link lets one box call a service that runs in another of your boxes, under the name its callers already use: how to declare one, its rules, and what a connection gets in each state of the other box.

Taking over a link or an environment address

On newer boxes, sandbox_wire puts your own process or a published version under a name that went out through a link or the connector, in place, keeping the box's URLs.

`sandbox_shot`

Takes a screenshot of the box's display, of its front window, of a URL opened in a fresh browser or of a tab already open in a browser on the box, captures several pages at once, or records the display to mp4.

`sandbox_scene`

Runs JavaScript in the page a person has open at one of the box's URLs, on their own device, and returns the result.

`sandbox_say`

Posts a status line to the person watching the box in the app; it is not a way to ask them anything. Their notes come back as fromHuman.

`sandbox_review`

Hands a tested version to the person, shows the card immediately and waits for their report or completion. Choose open by what they try: web with the port of a web page, or box for a desktop or phone app on the box's screen. Undeclared clients wait up to 25 seconds; clients configured for long waits can wait up to 30 minutes. Resume the same round with reviewId.

`sandbox_report`

Reads a human report again by its stable reportId, including annotated images, recordings and timed transcripts with refreshed file URLs.

`sandbox_takeover`

Asks a person to do what only they can (signing in, a CAPTCHA, a code) on the box's live screen, and waits for them to hand it back while the link lasts: 30 minutes, or 30 minutes from when they first open it.

`sandbox_feedback`

Reports to the ParallelSandbox team what you ran, how, what got in the way and what should change; send one entry after using boxes in a session.

`sandbox_secrets`

Lists the names of the account's secrets, never their values, or injects named secrets into a running box as environment variables.

`sandbox_environments`

Lists the person's environments (their own dev or staging): the private addresses a box reaches through their connectors, whether each connection is online, and the services whose settings a box gets.

`sandbox_device`

Leases an Android emulator or an iPhone simulator for the box, shown on its screen; lists the box's devices, or releases one.

Versions

A published version lets other boxes run a service you built, without building it again.

`sandbox_publish_version`

Records an image you pushed to the account's registry as a named version of a service, so other boxes can run it without building it again.

`sandbox_versions`

Lists the published versions, newest first, optionally for one service; another box runs one with services[].version.

Run a published version

A service declared with version runs a published image under its name, with no build: how the box pulls and starts it, extra variables in env, and how to follow and switch it.

Designing before building

For anything new or changed, design it with the person before you build it, in this order: screens with sandbox_draft, services with sandbox_architecture, stored data with sandbox_schema; then build in the box and hand it over with sandbox_review. Skip a step only when the task does not touch it. Use them whenever the person asks for a draft, sketch, wireframe, architecture diagram or schema, instead of writing HTML or image files. Each tool takes only JSON and needs no box, and each version comes back in the result and appears on the design's page in the person's app, where they circle, talk and write on it: sandbox_draft as hand-drawn phone screens and sandbox_architecture as a plain, clean diagram, both pictures drawn by the server, and sandbox_schema as text, not a picture, with a short note required on every field. new: true marks what is new or different compared with how things are now (red on a draft, blue on an architecture diagram, [new] in the schema), and note says what changed since the previous version; fixed words on the pictures, such as the legend, follow the account's language, and what you write is shown as given. Their report returns to the conversation that drew the version like review feedback (on its own with the stdio adapter 0.6.0 or later; read it with sandbox_report and reportId alone), and calling the same tool with the same topic draws the next version (v2, v3…); there is no approval step. A design belongs to the account and the conversation that draws it, not to a box: it stays when a box stops. id is optional: pass the box of this piece of work to show the design on that box's page too; these calls never wake it, but a successful one counts as use and gives the box to the calling conversation.

`sandbox_draft`

Sketches screens before you build them: you send JSON, the server draws hand-drawn phone mockups (up to 3 boards of up to 4 phones), and they come back in the result and appear on the design's page in the person's app, where the person steps through the phones one at a time and circles, talks and writes on them.

`sandbox_architecture`

Draws how the parts fit together before you build them: a box per app, service, database, queue or outside API and an arrow for who calls whom, laid out top to bottom automatically as a clean diagram with what is new in blue, in the result and on the design's page in the person's app.

`sandbox_schema`

Lays out the stored data before you build it, as text, not a picture: tables with their fields, each with its type, a short note on what it holds (required on every field) and the table it references. The text comes back in the result, and the person sees it as a table of text on the design's page in their app.

Logs

Three tools read ParallelSandbox's own log service, which pages feed with the browser SDK; they do not read Sentry or any other tracker.