Secrets

箱子偶爾需要憑證：clone 私有 repo 的 token、log SDK 的 write key、你的測試會打到的某個服務的 API key。Secrets 就是把這些交給箱子、又不放進 repo、prompt 或工具呼叫的方法。

怎麼運作

• 一個 secret 是一組名稱與值，存在控制面，每個租戶自己的。名稱就是環境變數名：PSBX_LOG_WRITE_KEY、GITHUB_TOKEN、STRIPE_TEST_KEY。
• 預設什麼都不會進箱子。sandbox_start 的 secrets 是名稱清單，只有列出的才注入，在箱子被認領的那一刻變成每個 sandbox_exec 命令的環境變數。
• 待命池裡的箱子不帶任何租戶資料。認領時才拿到租戶設定與 secrets；箱子停掉時上面的一切都會銷毀。
• 值不會出現在工具回傳、sandbox_status、用量事件或平台 log 裡。sandbox_secrets 只回名稱。
• 箱子自己沒有任何雲端憑證，也連不到其他箱子。

建立與管理

用 REST API，帶租戶 API key：

curl -fsS -X PUT https://api.parallelsandbox.com/v1/secrets/GITHUB_TOKEN \
  -H "Authorization: Bearer psbx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "ghp_..." }'

用既有名稱再建一次就是換值；之後認領的箱子拿到新值。刪除用 DELETE /v1/secrets/{name}；GET /v1/secrets 列出名稱。

agent 列出有哪些：

sandbox_secrets {}

在箱子裡用

sandbox_start { "services": [{ "name": "web", "port": 8080 }], "secrets": ["GITHUB_TOKEN", "PSBX_LOG_WRITE_KEY"] }
sandbox_exec  { "id": "<id>", "cmd": "git clone https://x-access-token:$GITHUB_TOKEN@github.com/your-org/private-repo.git && cd private-repo && git remote set-url origin https://github.com/your-org/private-repo.git" }

docker compose 用 compose 檔裡的 ${GITHUB_TOKEN} 或 environment: 裡不帶值的項目把環境變數帶進容器。不要用 ARG 把 secret 烤進 image；image 可能被發布成版本、被別的箱子拉走。

該存什麼

• 供應方有給就用短效 token：GitHub App 的 installation token、STS session、限定範圍的 deploy key。它們會自己過期。
• 像 log SDK 的 pw_... 這種可公開的 write key 放在網頁上也可以，但存成 secret 的話 repo 裡就完全沒有租戶專屬的東西。
• 絕對不要把 ParallelSandbox 的 API key 存成 secret。agent 已經有它；箱子不需要。