シークレット

ボックスは時々認証情報を必要とします。プライベートリポジトリを clone するトークン、ログ SDK の write key、テストが呼ぶサービスの API キー。シークレットは、それらをリポジトリにもプロンプトにもツール呼び出しにも書かずにボックスへ渡す仕組みです。

仕組み

シークレットはコントロールプレーンにテナントごとに保存される名前と値の組です。名前は環境変数名です：PSBX_LOG_WRITE_KEY、GITHUB_TOKEN、STRIPE_TEST_KEY。
既定では何もボックスに届きません。sandbox_start の secrets は名前の一覧で、列挙したものだけが、ボックスが割り当てられた瞬間に、すべての sandbox_exec コマンドの環境変数として注入されます。
プールで待機中のボックスはテナントのデータを一切持ちません。割り当てられたときに初めてテナントの設定とシークレットを受け取り、停止時にはボックス上のすべてが破棄されます。
値はツールの結果、sandbox_status、使用量イベント、プラットフォームのログのどこにも現れません。sandbox_secrets は名前だけを返します。
ボックス自身はクラウドの認証情報を持たず、他のボックスに到達できません。

作成と管理

REST API で、テナントの API キーを使います：

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 です。

エージェントは存在するものを一覧できます：

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 でシークレットをイメージに焼き込まないでください。イメージはバージョンとして公開され、他のボックスに pull されることがあります。

何を保存するか

提供元が用意しているなら短命トークンを：GitHub App のインストールトークン、STS セッション、スコープを絞ったデプロイキー。自動的に失効します。
ログ SDK の pw_... のような公開可能な write key はページに置いても構いませんが、シークレットにしておけばリポジトリにテナント固有のものが一切残りません。
ParallelSandbox の API キーをシークレットとして保存してはいけません。エージェントはすでに持っていますし、ボックスには不要です。