シークレット

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

仕組み

シークレットはコントロールプレーンにアカウントごとに保存される名前と値の組です。名前は環境変数名で、英大文字・数字・_ を使い、英字で始めます：PSBX_LOG_WRITE_KEY、GITHUB_TOKEN、STRIPE_TEST_KEY。値は最大 64 KB です。
既定では何もボックスに届きません。sandbox_start の secrets は名前の一覧で、列挙したものだけが、ボックスが割り当てられた瞬間に、すべての sandbox_exec コマンドの環境変数として注入されます。id と names を付けた sandbox_secrets で、起動中のボックスにあとから注入することもできます。
新しいボックスは、テナントのデータを一切持たないスナップショットから起動します。割り当てられたときに初めてテナントの設定とシークレットを受け取り、停止時にはボックス上のすべてが破棄されます。
値はツールの結果、sandbox_status、使用量イベント、プラットフォームのログのどこにも現れません。値を出力するコマンドを実行しても、返るのは隠したものです。sandbox_exec の出力と sandbox_procs のログ末尾では、8 文字以上のシークレットの値が **** に置き換わります（規則は sandbox_exec）。ボックス内のファイルは変わらないので、バックグラウンドコマンドのログファイルや sandbox_get で取り出したファイルには本当の値があります。sandbox_secrets は名前だけを返します。
ボックス自身はクラウドの認証情報を持たず、自分の他のボックスにはあなたが宣言したリンクを通してだけ届きます。クラウドの権限を得る唯一の方法は、ボックスの環境に指定した AWS ロールで、一時的な認証情報が渡されます。

作成と管理

REST API で、トークンを使います。API キー、または OAuth アクセストークンです（キーの入手方法）：

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

既存の名前で作成すると値が置き換わり、その後に割り当てられたボックスは新しい値を受け取ります。削除は DELETE /v1/secrets/{name}、名前の一覧は GET /v1/secrets です。

人は app.parallelsandbox.com の設定 → Secrets でも追加、値の置き換え、削除ができます。そこには名前と更新日時だけが表示され、値は決して表示されません。トークンを人が持っているときはそちらを案内してください。アプリで入力した値はあなたとの会話を通らないので、AI プロバイダーにも届きません。値を会話に貼り付けるよう頼まないでください。

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

sandbox_secrets {}

ボックスで使う

sandbox_start { "name": "プライベートリポジトリのテスト", "goal": "プライベートリポジトリのテストを実行する。ボックスの中ですべて通れば完了", "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", "note": "プライベートリポジトリを clone する" }

作業の途中で必要になったシークレットは、起動中のボックスに再起動なしで注入できます。以降のコマンドには見え、すでに動いているプロセスとコンテナは起動時の環境のままです：

sandbox_secrets { "id": "<id>", "names": ["STRIPE_TEST_KEY"] }

docker compose は compose ファイル内の ${GITHUB_TOKEN} や値のない environment: エントリで、docker run は -e GITHUB_TOKEN で環境変数をコンテナに渡します。ARG でシークレットをイメージに焼き込まないでください。イメージはバージョンとして公開され、他のボックスに pull されることがあります。

ビルドに必要なキー（フロントエンドの VITE_GOOGLE_MAPS_API_KEY、NEXT_PUBLIC_*）も同じです。ビルドが読む名前でシークレットとして保存し、secrets に入れて（または sandbox_secrets で注入して）、同じ sandbox_exec でビルドします。ビルドはほかの変数と同じように環境から $VITE_GOOGLE_MAPS_API_KEY を読みます。キー入りの .env を /work に同期して置きっぱなしにする必要はありません。できあがったバンドルにはフロントエンドのキーの常として値が入るので、必要なものだけ取り出してください。キーが人の手元にあるなら、Settings → Secrets に入れてもらいます。

存在しない名前を渡すと、sandbox_start（と names 付きの sandbox_secrets）は secrets not found: 名前 (this account has: …) で失敗します。エラーにはアカウントにある名前が並ぶので、つづりや大文字小文字の違いがすぐわかります。値が出ることはありません。

何を保存するか

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