ParallelSandbox
打開 app

工具參考

agent 對 ParallelSandbox 能做的每件事都經過這些 MCP 工具，全部帶租戶的 API key。名稱、輸入、輸出是凍結的契約；streamable HTTP 端點 https://mcp.parallelsandbox.com/mcp 與 npm 上的 stdio 轉接器 parallelsandbox-mcp 給的是同一組工具。

箱子

工具 輸入 輸出
sandbox_start services[{name, port}]、externalBaseUrl、secrets（名稱清單）、idleTimeoutMin（選填） id、sceneUrl、takeoverUrl、status、startedFrom（spare 或 cold）
sandbox_exec id、cmd、cwd、timeoutSec、background stdout、stderr、exitCode、bgId
sandbox_sync id、localPath、dest ok
sandbox_get id、path 預簽下載網址，1 小時有效
sandbox_wire id、service、mode（box 或 external） 當前接線表
sandbox_shot id、target（screen 或 url）、record（start 或 stop） 預簽網址
sandbox_status id 狀態、boxd 健康、接線表、takeoverUrl、interrupted 原因
sandbox_stop id ok
sandbox_publish_version service、label、image、gitSha、note versionId
sandbox_versions 無 清單
sandbox_takeover id、note 人交還時留的話；最長等 30 分鐘
sandbox_secrets 無 名稱清單，不含值

sandbox_start

  • services：你的 repo 在箱子上會開出來的服務名稱與埠。名稱可以被接線：sandbox_wire 之後，這個名字在箱子裡會指到那個埠（box）或指到 externalBaseUrl（external）。埠要真的發布在箱子上，docker compose 的 ports: 就是做這件事。
  • externalBaseUrl：沒改的服務住在哪裡，例如你的 staging 環境。選填。
  • secrets：從 sandbox_secrets 的名稱裡挑要注入的，認領箱子時變成環境變數。沒列的不注入。
  • idleTimeoutMin：多少分鐘沒有工具呼叫就自動停。平台不設預設值，也沒有最長存活時間；箱子跑到你停它或點數歸零為止。
  • startedFrom：spare 是認領了待命箱（15 秒內可用）；cold 是為你新開了一台機器（90 秒內）。

同時箱數：Free 3、Pro 5、Max 20。

sandbox_exec

  • cwd 相對於箱子的工作目錄 /work，預設就是它。
  • timeoutSec 限制前景命令。伺服器與長時間 build 用 background: true，會拿到 bgId，輸出在 /work/.sbx/ 下的 log 檔，用另一個 sandbox_exec 讀。
  • 有人透過 takeoverUrl 連著時，sandbox_exec 不執行，回鎖定錯誤。等一下再試。
  • 箱子的虛擬螢幕是 :99。要在 sandbox_shot 或 takeoverUrl 看得到的東西都要帶 DISPLAY=:99 跑。

sandbox_sync 與 sandbox_get

  • sandbox_sync 把本機目錄（localPath，相對於 agent 的工作目錄）打包送到箱子的 /work/<dest>。node_modules、.git、dist、build 等會排除。沒 commit 的東西用它；commit 過的用 sandbox_exec 裡的 git clone。
  • sandbox_get 回 /work 下某個檔案或目錄的預簽下載網址。目錄會打成 tar.gz。網址一小時後失效。

sandbox_wire

  • mode: "box"：這個服務名稱在箱子裡指到箱子自己、起箱時宣告的那個埠。
  • mode: "external"：指到 externalBaseUrl。
  • 回傳值是整張接線表，不只你改的那個服務。
  • 同一個 docker compose 專案裡的服務本來就透過 compose 網路互相找得到；接線是給箱子上其他東西用的（測試程式、Chromium、其他容器、場景網址）。

sandbox_shot

  • 不帶 record：截圖。target: "screen"（預設）截虛擬螢幕；target: "url" 在螢幕上開一個新的 Chromium 打開該網址再截。
  • record: "start" 開始把螢幕錄成 mp4；record: "stop" 結束並回預簽網址。

sandbox_takeover

阻塞到人把箱子交還，或滿 30 分鐘。人在 app 看到你的 note，在即時畫面上操作，按「交還」，可以留一句話；那句話就是工具的回傳值。登入、驗證碼、付款確認、任何你不該自己做的事，都用它。

版本

sandbox_publish_version 把你 push 到租戶 registry 的一顆 image 登記成某服務的具名版本，別的箱子（或你團隊的其他 agent）可以直接拉來跑，不用重 build。sandbox_versions 列出清單。image 位址必須在你租戶的 registry 命名空間裡；sandbox_status 會附 registry 登入資訊。

Log

工具 輸入 輸出
logs_search project、since、query、boxId 列
logs_errors project、since、boxId 列，stack 已用上傳的 source map 還原
logs_tail project、boxId 串流

project 是在 app 建的 log project；網頁用瀏覽器 SDK 把 log 送進去。since 接受時間長度（10m、2h、7d）或 ISO 時間戳。boxId 只看某個箱子裡的網頁送出的 log。log 不設保留期限。

箱子狀態

spare → claimed → ready → takeover（可選）→ stopping → terminated
                     ↕
                   frozen

閒置的 microVM 箱子會變成 frozen：記憶體存成快照、不再計箱子時間。對它的任何工具呼叫都會先恢復（幾秒），sandbox_stop 對凍結的箱子也有效，什麼都不會丟。

任何狀態都可能變成 interrupted：底下的 spot 機器被雲端收回。sandbox_status 會給原因；對那個箱子的下一個工具呼叫也會回同樣的內容。起一個新箱子重跑；被中斷的箱子上什麼都不會留下。

REST

給 web 與桌面 app，以及任何不是 agent 的東西。同一把 API key，Authorization: Bearer。

端點 用途
/v1/auth/github GitHub 登入
/v1/keys 建立與撤銷 API key
/v1/boxes 列出與查看箱子
/v1/boxes/{id}/screencast 即時畫面，WebSocket
/v1/boxes/{id}/input 滑鼠鍵盤輸入
/v1/takeovers 待接手的請求
/v1/takeovers/{id}/return 交還箱子並留話
GET /v1/secrets, PUT /v1/secrets/{name}, DELETE /v1/secrets/{name} 管理 secrets
/v1/versions 已發布的版本
/v1/usage 用量事件
/v1/credits 點數餘額與分桶
/v1/billing/checkout Stripe Checkout
/v1/billing/portal Stripe 客戶入口
/v1/billing/webhook Stripe webhook
/v1/projects (log.parallelsandbox.com) log project
/v1/projects/{id}/sourcemaps (log.parallelsandbox.com) 上傳 source map

其他事實

  • 場景網址：https://<id>.box.parallelsandbox.com，經 edge 到箱子。
  • 接手 token：含箱子 id 與到期時間的 HMAC。箱子只認控制面發的一次性 token。
  • 用量事件：每個運行中的箱子每分鐘一筆，每個計量動作一筆；欄位 tenant、box、kind、quantity、unit、cost_usd、credits、at。
  • 箱子之間互不可見，箱子上沒有任何雲端憑證。