sandbox_status

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

回一個箱子上面那張表列的所有東西。它只讀資料：不會喚醒凍結的箱子，也不會讓箱子變成你的（也不會把 stopsAt 往後推，見箱子狀態）。其中三個欄位是給接著做的人看的：

• goal：這個箱子要做什麼，就是給 sandbox_start 的那段；開箱時沒給的箱子（走 REST，或 goal 還不是必填時開的）沒有這個欄位。
• steps[]：箱子裡最近做過的 30 件事，舊的在前：命令、目錄與呼叫時附的說明，從不含輸出，也不含截圖與錄影。每一步的截圖與錄影在另一份清單：REST 的 GET /v1/boxes/{id}/media，只列有畫面的步驟，最近 7 天內、最多最新的 200 步（見 REST）。每一步有：
  • at：時間，RFC3339。
  • kind：exec、build、sync、wire、shot、device、start、stop、takeover、review、return 或 say。
  • summary：做了什麼（命令、服務名稱、訊息），最多 200 個字元；超過的會截掉並以 … 結尾。
  • target（可能沒有）：上傳（sync）或 build（build）的目錄。
  • note（可能沒有）：呼叫時給的 note。
  • actor（可能沒有）：人做的是 human；agent 與 ParallelSandbox 做的沒有這個欄位。
  • detail（可能沒有）：background: true 起的命令是 background，還原既有輸出的 build 是 reused，sandbox_shot 錄的一段是 record；wire 是模式（box 或 external）、link to <box> 或 version <label>。
  • ms（可能沒有）：花了多久。
  • ok：ParallelSandbox 有沒有執行它（箱子有回應）；命令跑了但失敗，仍然是 ok，附它的 exitCode。
  • exitCode、signal、timedOut（只有前景命令有）：命令怎麼結束的，跟它的 sandbox_exec 回的一樣。背景命令在這裡沒有（那時它才剛開始）；它怎麼結束看 sandbox_procs。
  • error（可能沒有）：一行說明 ParallelSandbox 這邊哪裡失敗，絕不是命令的輸出：箱子沒回應、有人接手了箱子，或命令跑完前呼叫就被關掉（附 execId，可用 sandbox_procs 拿它的結果）。
• 轉接器自己的雜事（sandbox_sync 用來比對檔案、在 /work/.psbx-sync/ 底下的命令與上傳）不列。步驟保留 7 天。
• agent（只有還活著的箱子有）：最後用這個箱子的對話還在不在做，{ "state": "left", "idleSec": 5400 }。state 是 working、away（對話還開著，但 10 分鐘沒用這個箱子）、left（對話關掉了）或 idle（箱子 1 小時沒用）；判斷規則見哪個對話在用箱子。那個對話就是發問的這個時，多一個 thisConversation: true。untracked: true 表示最後用它的呼叫沒帶對話 id（API key 腳本、直接打 REST、或沒經 stdio adapter 的遠端連線）：這時的 state 只是照閒置時間猜的，不代表有別的對話還在用。重新啟動你自己的 client（Claude Code、Codex…）會換成新的對話身分，所以重啟前用過的箱子，在你再用它之前會顯示 left、沒有 thisConversation；它還是你的，可以直接接著做。
• disk（只有在跑的箱子有）：箱子被什麼塞滿，好幾個 agent 共用一顆箱子、空間不夠時看這個。filesystems 是 /work、Docker 的儲存區、/、/tmp 與 /dev/shm 的 sizeGb、usedGb、freeGb（跟前面某個路徑在同一顆磁碟上的只標 sameAs，不要加總）；work 是 /work 底下每一項的大小（MB，大的在前，多半一項就是一個專案或一個 agent 的目錄）；caches 是套件快取與共用的瀏覽器（/root/.cache、/root/.npm、/root/go、Gradle、pnpm、Playwright 的瀏覽器等）；temp 是 /dev/shm 與 /tmp 底下超過 1 MB 的項目；docker 是 docker system df 的各列（映像、容器、volume、build cache，各自可回收多少）。sandbox_status 最多等它約 5 秒：還沒量完的路徑列在 notMeasured、標 measuring: true，會在背景繼續量，過幾秒再呼叫一次就有；結果留 30 秒（measuredAt）。不會幫你清任何東西：只刪自己的，共用箱子裡別人的目錄先問過再刪。這個欄位上線前開的箱子沒有 disk。
• fields：["goal", "agent", "steps"] 只回這幾個頂層欄位，加上 id 與 status；不認得的欄位名放在 unknownFields 回來。人留給你的話（fromHuman）照樣會帶。逐一查看別的對話留下的幾個箱子時用它。
• freeze（閒置會凍結的箱子，ready 或接手中時）：at 是照現在的情況閒置規則會凍結它的時間，blockedBy[] 是現在撐著它、讓它過了一般的 10 分鐘也不凍的東西。background（background: true 起的命令）、url（你最後一次呼叫之後經它的網址進來的請求）與 recording 只算到各自的 until；takeover、foreground（還在跑的 sandbox_exec）、link（別的箱子連著它）與 phone（接著的手機先凍、箱子再凍）要等它們結束，這時沒有 at。見箱子狀態。
• boxdVersion：箱子裡 boxd 的版本，當下問的（boxd 剛重啟也對）。imageId：箱子是從哪一個映像開出來的（microVM 箱子是映像 id，box-…）。開始記錄之前開的箱子沒有 imageId。
• services[].lastProxyError：最近 30 分鐘內，經這個服務的網址進來的請求轉不過去時，箱子最後一次的情況：at、status（它的 port 沒人回應是 503，箱子會先等 3 秒看它是不是在重啟；其他失敗是 502；或服務自己回的 5xx）、error（dial tcp 127.0.0.1:5173: connect: connection refused、逾時）與 count。503 box is frozen（或其他狀態）與 502 box unreachable 是箱子前面那一段回的，回應本身就寫了原因。同樣的紀錄、連同對不到任何服務的網址，也在 health.sceneErrors。
• running.containers[]：每個 Docker 容器的 name、image、status 與 ports；用 psbx-testdb 開的資料庫另有 envFile，是它的連線設定檔（. /work/.sbx/testdb/<名字>.env 會 export DATABASE_URL 等變數）。

所有工具與主題都列在工具參考。