ParallelSandbox

parallelsandbox-mcp

stdio adapter for the ParallelSandbox MCP server. It exposes the same tools as https://mcp.parallelsandbox.com/mcp (sandbox_*, logs_*), signing in with OAuth, and implements sandbox_sync and sandbox_pull locally: an agent can upload its working directory into a box without committing, and write files from the box back to its machine. Version 0.4.0 and later opens the browser to sign in and allow the connection. No API key is needed.

Use

npx -y parallelsandbox-mcp

Claude Code:

claude mcp add parallelsandbox -- npx -y parallelsandbox-mcp

Any other MCP client: run the command above as a stdio server.

The first connection starts immediately, then opens the browser for OAuth. Until sign-in finishes, the parallelsandbox_connect tool returns the sign-in link. Afterwards the adapter announces its sandbox and log tools; clients that do not reload tool lists need to reconnect once. Call parallelsandbox_connect again to check status or retry a cancelled sign-in. Sign-in waits five minutes before a retry is needed.

The token file lives in ~/.parallelsandbox, separately for each MCP endpoint, with mode 0600. Multiple conversations share this sign-in and serialize refreshes with a file lock. A lost refresh response requires a new sign-in so a used refresh token is never replayed. Existing PARALLELSANDBOX_API_KEY configurations continue to work.

If you never need sandbox_sync or sandbox_pull, skip this package and connect directly over HTTP, signing in with OAuth (run /mcp in Claude Code afterwards; no key needed). Over plain HTTP those two tools return an error, because they read and write files on your machine:

claude mcp add --transport http parallelsandbox https://mcp.parallelsandbox.com/mcp

Environment

When using a dev endpoint, set both PARALLELSANDBOX_MCP_URL and PARALLELSANDBOX_API_URL to its dev addresses.

sandbox_sync

{"id": " ", "localPath": "/abs/path/to/repo", "dest": "repo"} syncs localPath into /work/ on the box. dest is relative to /work (repo, not /work/repo; a leading /work/ is dropped and any other absolute path is refused before anything is uploaded). Pass an absolute path: a relative one resolves against this adapter's working directory (where your MCP client started it), which is not necessarily the agent's. In a git working tree it takes the tracked files plus the untracked files .gitignore does not exclude, asks the box which of them differ from what is already in dest, and uploads only those, so syncing after an edit sends just that edit. A file changed inside the box counts as different and gets the local version back, unless an "exclude" glob covers it (["capacitor.config.ts", "renderer/dist-win"]: such paths are neither sent nor compared, and the box's copy is never listed as stale or pruned). Outside git, and with commit, it compares and sends only the differences the same way; outside git it takes every file except node_modules, .git, dist, build, coverage, .venv and similar. No .git is sent.

A sync that would send more than 100 MB (size on disk) sends nothing and lists the largest folders; raise the limit with "maxMB" when that size is expected. "dryRun": true compares with the box and reports what would be sent without sending or deleting anything. While it runs, the adapter reports progress every 10 seconds (hashing, comparing, megabytes uploaded) to clients that ask for progress. An upload that fails with fetch failed, a reset connection or HTTP 502/504 is sent once more, and notes says so; one where nothing moves for two minutes, or the box does not answer within ten minutes of receiving everything, fails with a message naming that step.

The result says what happened: sentPaths (the first 50 files sent; sentFiles is the count), changedOnBox (files the box actually rewrote), remotePath, and in a working tree uncommitted, the paths that differ from HEAD. If other sessions share the checkout, those may be their unfinished work: pass "commit": "HEAD" with "alsoPaths" listing your own files instead. commit takes any revision and fails if it does not exist. Without commit, alsoPaths sends only those paths.

Files deleted or renamed locally stay in the box and are listed in staleInDest, leaving out paths your ignore rules skip (node_modules, build output, .env). "prune": true deletes them. A single file in localPath lands at dest itself ("dest": "renderer/.env" writes /work/renderer/.env), unless dest ends in / or is already a folder in the box.

node_modules is never sent, so notes (and deps) say when a folder with a package-lock.json, pnpm-lock.yaml or yarn.lock has no node_modules in the box, or, for npm, one whose installed packages differ from the lockfile, with the command to run there. On the first sync into a dest, notes also lists build settings the ignore rules kept out (tsconfig.json, .env.local) and says how to send them, and a gradlew, mvnw or *.sh script starting with #! that lacks the executable bit is pointed out whenever it is sent.

Submodules: without commit, an initialized submodule goes over as a plain directory, everything on disk in it. git archive leaves them out, so with commit pass "submodules": true to add each initialized submodule at the commit the tree records. "baseline": "origin/main" sends that commit to -baseline as well, so a failing test can be run on both sides to see whether it was already failing; each node_modules in dest is copied into the baseline as hard links where it has none ("baselineDeps": false skips that), leaving out Vite's cache so the two trees do not share one. When a sync fails, nothing new reached the box; the next sandbox_exec on that box carries a reminder.

sandbox_pull

{"id": " ", "path": " ", "localPath": "/abs/path/on/your/machine"} downloads a file or a directory from the box. A file is written to localPath. A directory's contents are extracted straight into localPath, the reverse of sandbox_sync: path app/dist with localPath /abs/dist gives /abs/dist/index.html, not /abs/dist/dist/index.html (versions before 0.3.3 added that extra level). The result gives files, the number of files written, and paths, the first 50 of them. Pass "extract": false to keep the tar.gz as one file instead; it holds the directory itself as its top entry. Relative paths resolve the same way as for sandbox_sync; dest is accepted as another name for localPath. Only the local copy stays: the hand-off copy on ParallelSandbox's side is deleted after about a day.

Extracting merges into what is already in localPath. "clean": true makes it exactly the box's directory instead: the archive is unpacked next to it first and swapped in only when that succeeds, and the result's removed counts the local files that went. clean is refused for a git checkout, your home directory, the adapter's working directory and their parents. Files the box was still writing while it packed the directory are listed in changedWhileReading. The download reports progress, gives up after two minutes without data, and fetches a fresh link once when the first is refused.

Which conversation is using a box

Ordinary MCP connections choose a random id when the adapter starts and send it as X-Psbx-Agent on every call. Registered native sessions keep one supervisor-owned id across all turns; the supervisor maintains its presence until it stops. After the first tool call it is reported once a minute, and when its conversation closes (stdin ends, or SIGTERM, SIGINT or SIGHUP) it reports /v1/agents/ /leave. With the feedback relay below, the relay sends one /v1/agents/heartbeat a minute for every live adapter of the account on that machine (each adapter keeps a small presence file with its id and process); otherwise each adapter reports /v1/agents/ /heartbeat itself. The app uses this to tell a box the AI is still working in from one whose conversation was closed without sandbox_review or sandbox_stop; a conversation killed outright (no leave) counts as gone three minutes after its last heartbeat. Nothing else is sent: no prompt, no transcript. Restarting the client starts a new adapter with a new id, so a box the conversation used before the restart shows agent.state left until it is used again; the restarted conversation can simply continue with it.

Timeouts

sandbox_takeover blocks until a person hands the box back, up to 30 minutes. sandbox_review immediately creates the person's review card, then waits for their report or completion within the caller’s declared budget. The default adapter and unknown HTTP clients wait up to 25 seconds; explicitly supported clients can wait up to 30 minutes. An explicit waitSec is capped by that budget and the time spent preparing the review. The result includes the effective waitSec and callerWaitMaxSec. Its progress includes the review ID and entry URL before the final result. Use waitSec: 0 for an explicit handoff without waiting, or resume a timed-out round with reviewId instead of creating another card with what. The adapter waits 31 minutes for takeover and review, and 65 minutes for other calls (a foreground sandbox_exec runs at most 60 minutes). Cancelling a client call also cancels its control connection; it does not delete the review or feedback. Each foreground sandbox_exec carries an execId the adapter picks. If its result is lost on the way back (no data for 75 seconds, or the stream ends without it), the command keeps running on the box, and the error names sandbox_procs {action: "wait", bgId: }, which returns its exit code and the end of its output once it ends. The adapter also checks the server's tool list every 10 minutes and sends notifications/tools/list_changed when it changed, so a long conversation does not keep using an old schema. The waiting-tool route lasts for that active call. Registered native sessions use the supervisor below to continue after a turn exits.

Continue after the AI finishes

parallelsandbox-agent runs a persistent supervisor for a registered native Claude Code, Codex or Gemini CLI session. The first prompt and