工具參考

agent 對 ParallelSandbox 能做的每件事都經過這些 MCP 工具，接上時用 OAuth 登入一次（快速開始），之後每個呼叫都作用在你登入的那個帳號上。streamable HTTP 端點 https://mcp.parallelsandbox.com/mcp 與 npm 上的 stdio 轉接器 parallelsandbox-mcp 給的是同一組工具。sandbox_sync 與 sandbox_pull 要讀寫 agent 自己的磁碟，只能經轉接器用；走純 HTTP 會回錯誤並講明原因。各種 client 的設定由 AI 依 SKILL.md 完成。轉接器也預設走 OAuth；等待登入時，parallelsandbox_connect 會回傳登入連結。

每個工具，以及工具共用的主題，各有自己的一頁；這一頁列出全部，並說明各自做什麼。每一頁在自己的網址後面加 index.md 就是純 Markdown 版（例如 /docs/tools/sandbox-start/index.md），llms-full.txt 則把英文版的所有頁面放在一個檔案裡。

箱子

`sandbox_start`

為一個 goal 開新箱子：宣告 repo 對外的服務（各有自己的名字），也可以選環境、秘密、大小與工具鏈。回箱子 id、它的網址與收到的服務。

`sandbox_list`

列出帳號的箱子（隊友的也在內），最近用過的在前，附每個箱子的名字、goal、狀態與網址。只讀，不會喚醒箱子。

`sandbox_media`

依時間列出帳號所有箱子（停掉的也算）每一步留下的截圖與錄影，附箱子的名字、goal 與每張畫面的下載網址。用來整理一段期間做了什麼、驗了什麼。只讀，不會喚醒箱子。

`sandbox_status`

一個箱子的全部資訊：狀態、goal、最近做過的 30 個步驟、在用它的對話還在不在做、接線、服務、正在跑的命令與點數。只讀。

`sandbox_stop`

把箱子永久停掉，釋放它的機器與裝置，/work 裡的東西全部消失。沒有東西要給人看時，做完就呼叫。

收尾

箱子怎麼收尾：要人試結果就 sandbox_review，沒有東西可看就 sandbox_stop，以及各自會留下什麼。

接手別的對話留下的箱子

對話怎麼接手別的對話留下的箱子：用 sandbox_list 找到它，用 sandbox_status 讀 goal、steps[] 與 agent；原本的對話可能還在做時，先問人。

`sandbox_exec`

在箱子裡跑一個 shell 命令：前景跑（有逾時），或背景跑（輸出寫到 log 檔）。前景命令執行時畫面有變，這一步會留截圖與錄影給人看。

`sandbox_procs`

列出、等待或停止用 sandbox_exec 加 background: true 開的命令。用它，不要用 pkill -f 或 pgrep -f：命令列含有那個 pattern 的程序都會被比對到，別的工作也算。

`sandbox_sync`、`sandbox_get` 與 `sandbox_pull`

在你的電腦與箱子之間搬檔案的三個工具。

`sandbox_sync`

把本機資料夾或單一檔案上傳到箱子的 /work/<dest>，只傳不一樣的檔案。只能經 stdio 轉接器用。

`sandbox_get`

把 /work、/tmp 或 /dev/shm 底下的檔案或資料夾取出成下載網址，一小時有效（資料夾是 tar.gz）；小圖片也會直接附在結果裡。

`sandbox_pull`

sandbox_get 加上下載：把箱子裡的檔案寫到本機路徑，或把資料夾解開到那裡。只能經 stdio 轉接器用。

`sandbox_build`

跑安裝或編譯步驟並保存輸出；輸入相同的箱子幾秒就還原，不用重新 build。

`sandbox_wire`

把宣告過的名字在箱子裡你的程序與 externalBaseUrl 之間切換、在跑著的箱子上宣告新名字，或讓名字指向別的箱子或發布好的版本。

連到別的箱子

link 讓一個箱子用呼叫端原本用的名字，呼叫你另一個箱子裡跑的服務：怎麼宣告、有哪些規則，以及另一個箱子在各種狀態下連線會得到什麼。

接手 link 或環境位址

在較新的箱子上，sandbox_wire 可以把原本經 link 或連接器出去的名字，原地換成箱子裡你的程序或發布好的版本，箱子的網址不變。

`sandbox_shot`

截箱子的畫面、最前面的視窗、用新開的瀏覽器打開的網址，或箱子裡瀏覽器已經開著的分頁；也能一次截好幾頁，或把畫面錄成 mp4。

`sandbox_scene`

在人用自己的裝置從箱子網址打開的頁面裡跑 JavaScript，回傳結果。

`sandbox_say`

在 app 裡給看著箱子的人一行狀態；不是用來問人的。他們留的話會以 fromHuman 回來。

`sandbox_review`

把測過的版本交給人，立即顯示卡片，等待回饋或驗收完成。open 依人要試的東西選：網頁用 web 加它的 port，桌面 App 或手機 App 用 box 交箱子的畫面。未宣告的 client 最多等 25 秒；完成長等待設定的 client 最多等 30 分鐘。用 reviewId 接續同一輪。

`sandbox_report`

用固定的 reportId 重讀真人回饋，包含圈選圖、錄影、時間逐字稿與重新簽署的檔案網址。

`sandbox_takeover`

請人在箱子的即時畫面上做只有他們能做的事（登入、CAPTCHA、驗證碼），在網址有效期間等他們交還：30 分鐘，人第一次打開時延到打開後 30 分鐘。

`sandbox_feedback`

向 ParallelSandbox 團隊回報你跑了什麼、怎麼跑、卡在哪、該改什麼；一個 session 用過箱子後送一則。

`sandbox_secrets`

列出帳號秘密的名稱（絕不給值），或把指定的秘密注入跑著的箱子，成為環境變數。

`sandbox_environments`

列出人的環境（他們自己的 dev 或 staging）：箱子經連接器連得到的內網位址、每條連線在不在線上，以及箱子拿得到設定的服務。

`sandbox_device`

為箱子租一台 Android 模擬器或 iPhone 模擬器，顯示在箱子畫面上；也能列出箱子的裝置，或還掉一台。

版本

發布版本讓別的箱子不用重新 build，就能跑你 build 好的服務。

`sandbox_publish_version`

把你推到帳號 registry 的映像記成某個服務的具名版本，讓別的箱子不用重新 build 就能跑。

`sandbox_versions`

列出已發布的版本，新的在前，可以只看一個服務；別的箱子用 services[].version 跑其中一個。

跑發布好的版本

用 version 宣告的服務，會用它的名字跑發布好的映像，不用 build：箱子怎麼拉取與啟動、env 裡的額外變數，以及怎麼看進度與換版本。

動手做之前先設計

新做或要改的東西，動手做之前先跟人一起設計，順序是：畫面用 sandbox_draft、服務用 sandbox_architecture、存的資料用 sandbox_schema；然後在箱子裡做，用 sandbox_review 交給人驗收。只有這次工作碰不到的那一步才跳過。人要草稿、草圖、架構圖或 Schema 時就用它們，不要改寫 HTML 或圖片檔。三個工具都只收 JSON、不需要箱子，每一版都回到工具結果，也出現在人的 app 裡這份設計的頁面，人在上面圈線、講話、打字：sandbox_draft 是手繪風的手機草稿、sandbox_architecture 是乾淨的一般架構圖，這兩種是伺服器畫的圖；sandbox_schema 是文字、不是圖，每個欄位都要寫一句 note。new: true 標跟現在比起來新的或不一樣的東西（草稿是紅色、架構圖是藍色、Schema 標 [new]），跟上一版比改了什麼寫在 note；圖上的圖例這類固定字跟帳號的語言，你寫的字照原樣出現。人的回報照驗收回饋的方式回到畫那一版的對話（要自動回來，stdio 轉接器要 0.6.0 以上；用 sandbox_report 只帶 reportId 讀），用同一個 topic 再呼叫同一個工具就是下一版（v2、v3…）；沒有核准或定案的步驟。設計屬於帳號和畫它的那段對話，不屬於箱子：箱子停掉它還在。id 選填：傳這段工作的箱子，設計也會出現在那個箱子頁；這些呼叫不會叫醒它，但成功一次就算一次使用，呼叫的對話會拿到這個箱子。

Log

三個工具讀 ParallelSandbox 自己的 log 服務，由網頁用瀏覽器 SDK 送進來；它們不讀 Sentry 或任何其他錯誤追蹤服務。

工具參考

箱子

sandbox_sync、sandbox_get 與 sandbox_pull

版本

動手做之前先設計

Log

`sandbox_sync`、`sandbox_get` 與 `sandbox_pull`