快速開始
從零到一個已經 build、跑起來、測完一個真實 repo 的箱子，大約十分鐘。你需要一個 GitHub 帳號、Claude Code（或其他 MCP client），本機不用裝任何東西。
箱子是你自己 agent 的遠端 Linux 機器：2 vCPU、16 GB 記憶體、自己的 Docker、git、Node、Go、Python、一個帶 Chromium 的虛擬螢幕、ffmpeg。箱子裡沒有 AI。你的 agent 用 MCP 工具操作它；它需要人時，你從瀏覽器或桌面 app 看畫面或接手。
1. 登入、建 API key
- 打開 https://app.parallelsandbox.com/ ，用 GitHub 登入。
- 到「帳號」，按「建立 API key」，取個名字。
- 複製 key。只顯示這一次，長得像
psbx_...。
每個帳號一開始有 500 點，不過期；箱子每小時約 100 點，按分鐘扣。詳見定價。
2. 接上你的 agent
Claude Code，streamable HTTP：
claude mcp add --transport http parallelsandbox https://mcp.parallelsandbox.com/mcp \
--header "Authorization: Bearer psbx_YOUR_KEY"
只會 stdio 的 client（Codex、Cursor、自己寫的 agent）用 npm 上的轉接器：
claude mcp add parallelsandbox -e PARALLELSANDBOX_API_KEY=psbx_YOUR_KEY -- npx -y parallelsandbox-mcp
Codex 的 ~/.codex/config.toml：
[mcp_servers.parallelsandbox]
command = "npx"
args = ["-y", "parallelsandbox-mcp"]
env = { PARALLELSANDBOX_API_KEY = "psbx_YOUR_KEY" }
檢查：跑 claude mcp list，parallelsandbox 要顯示已連線；在 Claude Code 裡打 /mcp 會列出 sandbox_* 與 logs_* 工具。
3. 裝 skill
skill 教 agent 什麼時候用箱子、工具照什麼順序呼叫。只有一個檔案：
mkdir -p ~/.claude/skills/parallelsandbox
curl -fsSL https://parallelsandbox.com/skill/SKILL.md -o ~/.claude/skills/parallelsandbox/SKILL.md
其他 agent 把同一份檔案貼進 system prompt 或專案指示即可。內容在這裡。
4. 跑第一個箱子
對 Claude Code 說：
用 ParallelSandbox 跑 https://github.com/parallel-sandbox/example-compose-app：起一個箱子，clone 這個 repo，用 docker compose build 並跑起來，接線，在虛擬螢幕上有頭跑 Playwright e2e 並錄影，把截圖和影片給我，然後收掉箱子。
agent 會一個工具一個工具做：
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 15 秒內回來，要冷開機器時 90 秒內。sandbox_shot 的 record: "stop" 與 sandbox_get 回的是一小時有效的下載網址。
5. 看畫面，或接手
sandbox_start 與 sandbox_status 都會回 takeoverUrl。在瀏覽器打開就是箱子的即時畫面，滑鼠鍵盤直接用。有人連著時 sandbox_exec 會暫停並回「被接管」；關掉頁面，agent 就繼續。
agent 需要人的時候會呼叫 sandbox_takeover 並附一句話。請求會出現在 https://app.parallelsandbox.com/ （裝了桌面 app 的話也會跳通知）。做完該做的事，按「交還」，可以留一句話；agent 會把那句話當成工具的回傳值收到。