ParallelSandbox
Open app

Quick start

From zero to a box that has built, run and tested a real repo, in about ten minutes. You need a GitHub account, Claude Code (or another MCP client), and nothing installed on your machine beyond that.

A box is a remote Linux machine for your agent: 2 vCPU, 16 GB of memory, its own Docker, git, Node, Go, Python, a virtual display with Chromium, and ffmpeg. There is no AI inside. Your agent drives it through MCP tools; you watch or take over from the browser or the desktop app when it asks.

1. Sign in and create an API key

  1. Open https://app.parallelsandbox.com/ and sign in with GitHub.
  2. Go to Account, press Create API key, give it a name.
  3. Copy the key. It is shown once. It looks like psbx_....

Every account starts with 500 credits that never expire; a box costs about 100 credits an hour, billed by the minute. See Pricing.

2. Connect your agent

Claude Code, streamable HTTP:

claude mcp add --transport http parallelsandbox https://mcp.parallelsandbox.com/mcp \
  --header "Authorization: Bearer psbx_YOUR_KEY"

Any client that only speaks stdio (Codex, Cursor, a custom agent) uses the adapter from npm:

claude mcp add parallelsandbox -e PARALLELSANDBOX_API_KEY=psbx_YOUR_KEY -- npx -y parallelsandbox-mcp

Codex, in ~/.codex/config.toml:

[mcp_servers.parallelsandbox]
command = "npx"
args = ["-y", "parallelsandbox-mcp"]
env = { PARALLELSANDBOX_API_KEY = "psbx_YOUR_KEY" }

Check: run claude mcp list; parallelsandbox must show as connected, and /mcp inside Claude Code lists the sandbox_* and logs_* tools.

3. Install the skill

The skill teaches the agent when to use a box and in what order to call the tools. One file:

mkdir -p ~/.claude/skills/parallelsandbox
curl -fsSL https://parallelsandbox.com/skill/SKILL.md -o ~/.claude/skills/parallelsandbox/SKILL.md

For other agents, paste the same file into the system prompt or the project instructions. Read it here.

4. Run the first box

Tell Claude Code:

Use ParallelSandbox to run https://github.com/parallel-sandbox/example-compose-app: start a box, clone the repo, build and run it with docker compose, wire the services, run the Playwright e2e headed on the virtual display while recording, give me the screenshot and the video, then stop the box.

What the agent does, tool by tool:

sandbox_start { "services": [{ "name": "api", "port": 3000 }, { "name": "worker", "port": 8080 }] }
sandbox_exec  { "id": "<id>", "cmd": "git clone https://github.com/parallel-sandbox/example-compose-app.git" }
sandbox_exec  { "id": "<id>", "cmd": "docker compose up -d --build --wait", "cwd": "example-compose-app", "timeoutSec": 600 }
sandbox_wire  { "id": "<id>", "service": "api", "mode": "box" }
sandbox_wire  { "id": "<id>", "service": "worker", "mode": "box" }
sandbox_exec  { "id": "<id>", "cmd": "npm ci && npx playwright install chromium", "cwd": "example-compose-app/e2e", "timeoutSec": 600 }
sandbox_shot  { "id": "<id>", "record": "start" }
sandbox_exec  { "id": "<id>", "cmd": "DISPLAY=:99 HEADED=1 BASE_URL=http://localhost:3000 npx playwright test", "cwd": "example-compose-app/e2e", "timeoutSec": 300 }
sandbox_shot  { "id": "<id>", "record": "stop" }
sandbox_get   { "id": "<id>", "path": "example-compose-app/e2e/screenshots/jobs.png" }
sandbox_stop  { "id": "<id>" }

sandbox_start returns in under 15 seconds when a spare box is waiting, under 90 seconds when one has to be started cold. sandbox_shot with record: "stop" and sandbox_get return download URLs valid for one hour.

5. Watch, or take over

sandbox_start and sandbox_status return takeoverUrl. Open it in a browser to see the box's screen live and use the mouse and keyboard. While a person is connected, sandbox_exec pauses and returns "taken over"; close the page and the agent continues.

When the agent needs a person, it calls sandbox_takeover with a note. The request appears on https://app.parallelsandbox.com/ (and as a desktop notification if the app is installed). Do what is needed, press Hand back, optionally with a message; the agent receives that message as the tool result.

  • Tool reference: every tool, its inputs and outputs, box states, REST endpoints.
  • Example repos: the two repos used above and how to run them in a box.
  • Log SDK: send browser errors from the pages you run in a box, query them with logs_errors.
  • Secrets: give boxes the credentials they need without putting them in a repo.