docker-sandboxes-env

Docker Sandboxes：宣言型 sbxenv.yaml 環境

概要

sbxenv.yaml（schemaVersion "1"、実験的）は、1 つのサンドボックス環境（エージェント、ミックスインキット、ワークスペースのマウント、環境変数、プロビジョニングするシークレット／レジストリ／バインディング、MCP サーバー、ポート、ホスト側のライフサイクルコマンド）を宣言的に記述します。これにより、長いフラグ指定を行わずに sbx env create|run|plan|exec|rm で環境を再現可能な形で構築・削除できます。このスキルでは、このファイル形式を最初から最後まで扱います。このファイルが利用するサンドボックスのライフサイクルの動作、プロビジョニング先となる認証情報／ネットワークモデル、kits: エントリーが参照するキットのスキーマについては、それぞれのスキルに委ねます。

このスキルを使う場面

次の場合に、このスキルを有効にしてください。

• 長い sbx create／sbx run のコマンドラインではなく、サンドボックス環境のチェックイン可能で再現性のある定義をユーザーが求めている場合。
• リポジトリのクローン作成、フィクスチャのシード、状態のアーカイブなどのホスト側セットアップ／ティアダウンコマンドを、サンドボックスの作成／アタッチ／削除のライフサイクルに関連付けたい場合。
• 名前付き引数（args: + --env-arg）を使って共有環境ファイルをパラメーター化したい場合。
• sbx env create／run で承認を求められる理由や、宣言したファイル、キット、シークレットがスキップされたり問題として指摘されたりする理由をデバッグしている場合。

このスキルを使わない場面

次の場合は、このスキルを使わないでください。

• sbxenv.yaml ファイルを使わず、基盤となる sbx create／run／rm のフラグベースのワークフローを扱う場合は、docker-sandboxes-lifecycle を使用してください。
• 環境ファイルとは独立してネットワークポリシーを選択したり、シークレット／レジストリの認証情報を保存したりする場合は、docker-sandboxes-network-credentials を使用してください。このスキルの secrets:／registries:／bindings: ブロックも同じストアにプロビジョニングしますが、ここではそのルールを再定義しません。
• kits: エントリーが参照するキットの spec.yaml を作成する場合は、docker-sandboxes-kits を使用してください。

基本ガイダンス

ファイルの解決と必須フィールド

• sbx env がディレクトリから読み込むファイル名は sbxenv.yaml のみです。ほかの名前は認識されず、プロジェクト階層にあるディレクトリ名付きの .sbxenv.yaml も、そのプロジェクト独自のファイルとしては読み込まれません（この隠しファイル名を使うのはホームディレクトリのベースレイヤーのみです。詳しくは後述します）。
• すべての環境ファイルには、schemaVersion: "1" と agent:（組み込みエージェント名、または kits: で指定したエージェントキットのマニフェスト名）が必要です。それ以外はすべて任意です。agent: shell には認証情報が不要で、ファイルの基本動作を検証する最も簡単な方法です。
• sbx env create|run|plan|exec|rm では、1 つ以上の PATH 引数を指定できます。各 PATH はディレクトリ（<PATH>/sbxenv.yaml に解決されます）またはファイルそのものです。複数指定すると、宣言順にディープマージされます。docker compose -f と同様の動作です。後のファイルが前のファイルを上書きし、マッピングはキーごとにマージされ、シーケンスは連結されます。

  sbx env create sbxenv.yaml override.yaml
  

名前、ワークスペース、.sbxenv.yaml のユーザーベースレイヤー

• ファイルで name: が設定されている場合、または --name で上書きされている場合を除き、サンドボックスの名前はマウントされたディレクトリ（何もマウントされていない場合はプロジェクトディレクトリ）に基づきます。そのため、何もマウントしない環境でも、適用するたびに同じサンドボックスになります。同じディレクトリにある別々の環境ファイルは、同じサンドボックス名になり、競合します。それぞれで独自の name: を設定するか（または呼び出しごとに異なる --name を指定しない限り）、同じディレクトリに複数の環境が存在する可能性がある場合は、各環境に必ず明示的な name: を指定してください。
• workspace: は、sbx create でパスを省略した場合と同様に、読み書き可能なマウントを指定します。workspace: を省略すると、何もマウントされません。 相対 workspace: パスは、それを宣言したファイルのディレクトリを基準に解決されます。workspace: . は、ファイルが置かれているディレクトリをマウントします。${{ env.projectDir }} はプロジェクトディレクトリ（最初の PATH が指定するディレクトリ、または指定がない場合は cwd）を指し、${{ env.fileDir }} は宣言元ファイルが置かれているディレクトリを指します。それ以外は展開されません。単独の $ はリテラルテキストなので、コンテナ用に記述した値（PATH: $PATH:/opt/bin）は変更されずに渡されます。

  workspace: .                       # mounts the directory this file sits in
  # workspace: ${{ env.projectDir }} # mounts the project directory explicitly
  

• 相対キットソースにも、workspace: と同じファイルディレクトリ基準のルールが適用されます（キット参照の構文については docker-sandboxes-kits を参照してください）。
• マウントされたワークスペース内のファイルには、デフォルトで読み取り専用のマスキングが適用されます。この保護が完全に機能するのは、ファイルがマウントのルート直下にある場合のみです。 マウントポイントでの読み取り専用バインドは、サンドボックスから名前を変更できません。マウント内で、その上位に名前を変更できるものがないためです。しかし、読み書き可能なマウントのサブディレクトリにある環境ファイルは、現在のパスでのみ保護されます。サンドボックスは、書き込み可能な親ディレクトリの名前を変更し、その後元のパスを自ら再作成して、読み取り専用バインドが適用されない状態でサンドボックスが制御するファイルを元の場所に置けます。sbx env plan は、マウントのルートにないファイルについて、この保護の隙間を明示的に警告します。親ディレクトリの名前を変更しても隙間は生じない、とは説明しないでください。マウントルート以外では、隙間が生じます。
• PATH が指定されていない場合、ホームディレクトリにある .sbxenv.yaml は、プロジェクト間で共有するデフォルト値のベースレイヤーとして下位にマージされます。PATH を指定すると、このレイヤーは完全にスキップされます。ベースレイヤーでは、name:（1つのプロジェクトを識別するもの）を設定できません。また、workspace: は ${{ env.projectDir }} をルートとする必要があります。ほかの値を指定すると、そのレイヤーをマージするすべてのプロジェクトに、同じ固定ディレクトリがマウントされてしまいます。

args: — 共有ファイルのパラメーター化

• 名前付き入力は args: の下に宣言します。それぞれに default（省略可能にします。default: "" も有効なデフォルト値です）または required: true（相互に排他的）を指定し、必要に応じて description、enum、または pattern も指定します。
• ファイル内で値が現れる場所ならどこでも、${{ env.args.NAME }} として参照できます。値は --env-arg NAME=VALUE（繰り返し指定可能）または --env-args-file PATH で渡します。

lifecycle: — ホストコマンドと承認プラン

• lifecycle: は、ホスト上で、サンドボックスの外部にある、ご自身の権限で実行されるシェルコマンドを宣言します。コンテナ内では実行されません。呼び出しごとに次の3つのフェーズがこの順序で実行されます。
  • initialize — 既存のサンドボックスに接続するだけの場合も含め、すべての create と run で実行されます。環境の作成に必要なもの（クローンしたワークスペースや生成ファイルなど）を用意できる唯一のフェーズなので、冪等でなければなりません。再接続のたびに再実行されます。
  • postCreate — サンドボックスの作成後、対話型の接続がターミナルを使用する前に一度実行されます。
  • preRemove — sbx env rm がサンドボックスを削除する前に実行されます。この時点では、まだ sbx env exec からサンドボックスにアクセスできます。preRemove の失敗は警告にとどまり、失敗しても削除はブロックされません。フックの実行後、削除時に承認済みの削除プランとサンドボックスの識別情報が再確認されます。承認に含まれていない新たな認証情報やバインディングの変更、または同じ名前のサンドボックスへの置き換えがある場合、削除前に処理が停止します。再試行する前に、新しい削除プランを確認してください。
  • sbx env exec はライフサイクルコマンドを一切実行せず、サンドボックスがすでに存在している必要があります。サンドボックスを作成することはありません。先に sbx env create または sbx env run を実行してください。

  lifecycle:
    initialize:
      - command: test -d app || git clone https://github.com/acme/app
    postCreate:
      - command: ./scripts/seed-fixtures.sh
    preRemove:
      - command: ./scripts/archive-state.sh
  

• すべてのコマンドは、デフォルトでプロジェクトディレクトリからシェル経由で実行されます（コマンドごとに workdir: で変更できます。実行時間は timeout: で制限できます）。
• ライフサイクルコマンドを宣言するファイルは、今回の呼び出しで何も変更されていなくても、そのファイルに到達するたびに確認を求められます。コマンドの承認は、そのコマンドから呼び出されるものもすべて信頼することを意味します。たとえば、回答後に内容が変更される可能性のあるスクリプトも含まれるため、デフォルトでは承認を記憶せず、確認を繰り返します。唯一の例外は sbx settings set env.rememberHostCommands true です。この設定を有効にすると、コマンドが実際に変更された場合にのみ再確認を求めます。信頼できないファイルや信頼できないキットのライフサイクルコマンドを、承認済みとして扱わないでください。また、コマンドを確認していないファイルに対して rememberHostCommands を有効にしないでください。ホストコマンドを一切宣言しておらず、設定も前回の承認時から変更されていない環境は、確認なしで適用されます。1回の呼び出しですべての宣言済みコマンドを実行しないようにするには、--skip-host-commands を使用してください。

環境プラン：その内容と対象外の内容

• sbx env plan [PATH...] は、ファイルを適用すると設定されるすべての内容（ホストコマンド、認証情報／バインディング、MCP 登録、ディレクトリ、公開ポート、サンドボックス自体、およびその変数）を、最後に適用／承認された状態と比較して表示します。何も変更しません。
• sbx env create／sbx env run は同じプランを表示し、処理を開始する前に承認を求めます（非対話型の使用では --auto-approve／-y で確認を省略できます。ただし、確認していないファイルやキットに対して デフォルトで -y を使用しないでください）。シークレットの value: の実値は、プランに表示される場合も状態に記録される場合も、平文ではなく sha256: ダイジェストとして扱われます。ref:／command: シークレットには、認証情報の取得元が表示され、解決後の値は表示されません。

環境にスコープを設定したシークレット、レジストリ、バインディング

• secrets: と registries: は、sbx secret set が使用するものと同じ認証情報ストアに、この環境のサンドボックススコープで登録されます。そのため、sbx env rm は作成したものだけを正確に削除できます。各エントリーの形式は sbx secret set と同じ value／ref／command（3つのうちちょうど1つ）です。実行時にこれらが何を意味するか、またチェックイン済みファイルにシークレットの値をリテラルで記述すべきでない理由については、docker-sandboxes-network-credentials を参照してください。
• bindings: はサービスごとの認証情報バインディングで、ユーザーのグローバルな credentials.yaml にマージされます。secrets:／registries: とは異なり、ユーザー全体に適用され、他のサンドボックスや環境と共有される可能性があるため、sbx env rm ではデフォルトでそのまま残されます。これらも削除するには --prune-bindings を指定してください。
• チェックイン済みの sbxenv.yaml にシークレットの値をリテラルで直接記述しないでください。 値をファイル内に一切保存せずに済むよう、ref:（1Password／AWS Secrets Manager）または command: を使用してください。value: を一時的に使用した場合、プランと状態に表示されるのはダイジェストだけですが、元の環境ファイルには平文のシークレットが残ります。形式については、以下のラベル付き secrets: フラグメントを参照してください。検証に認証情報をまったく必要としないため、これは意図的に最小アセットには含めていません。

  # OPTIONAL fragment — add only if this environment actually needs a
  # credential; the minimal asset omits this entirely.
  secrets:
    anthropic:
      ref: op://Private/Anthropic/api-key   # never a literal `value:` in a checked-in file
      refresh: 55m
  

kits:、additionalWorkspaces:、mcp:、ports:、sandboxOptions:

• kits: は、ベースエージェントにミックスインキット（および agent: と名前が一致するエージェントキットをちょうど1つ）を組み合わせます。相対パスのソースは、workspace: と同じルールで、宣言元ファイル自身のディレクトリを基準にします。
• additionalWorkspaces: は、プライマリの workspace: 以外に追加のディレクトリをマウントします（ファイルで一方だけを宣言することはできません）。これは sbx run の追加の位置引数によるワークスペース指定（:ro 付き）に相当します。
• mcp.servers: はホストに MCP サーバーを登録し、作成時にサンドボックスの固定（静的）MCP セットに追加します。登録はホスト全体に適用され、sbx env rm の後もそのまま残ります。
• ports: は、サンドボックスが公開するコンテナーポートに対して明示的なホストポートのバインディングを固定します。これは sbx ports --publish に相当し、sbx env rm がサンドボックスを削除すると自動的に解除されます。
• sandboxOptions:（以下の writableEnvFiles を除く）は、残りの sbx create フラグ（template、memory、cpus、pullPolicy、profile、skills）に対応します。

5つのブロックそれぞれの正確なフィールド形式、必須キー、YAML の例については、references/env-schema-fields.md を参照してください。

sandboxOptions.writableEnvFiles — 意図的かつ明示的な保護レベルの引き下げ

• デフォルトでは、ワークスペース内にマウントされたすべての環境ファイルは、そのほかのマウント部分が書き込み可能であっても、それぞれのパスで読み取り専用になります。これにより、次回の呼び出し時にホスト上で実行されるライフサイクルコマンドやシークレット解決コマンドを決めるファイルを、エージェントが編集できないようにします。
• エージェントが自身の環境ファイルを編集することを意図している場合に限り、sandboxOptions.writableEnvFiles: true を設定してください。これは実際にセキュリティを引き下げる設定です。プランではそのファイルが書き込み可能として報告されるため、デフォルトではなく、ほかの明示的な信頼判断と同様に扱ってください。
• 保護が完全なのは、マウント自身のルートにある場合だけです。 読み書き可能なマウントのルートに直接置かれたファイルは、マウントポイント自体をサンドボックスから名前変更できないため、名前を変更しても到達できません。マウントのサブディレクトリ内にあるファイルは別です。現在のパスでは読み取り専用ですが、サンドボックスはそのファイルを含むディレクトリ（書き込み可能）を名前変更し、元のパスにファイルを再作成できます。その結果、サンドボックスが制御するファイルが元のパスに置かれます。マウントのルートに直接置かれていないファイルについては、sbx env plan がこの問題を警告します。名前変更は常に無害だと決めつけず、プランの出力を確認してください。

関連スキル

• このファイルがラップする sbx create/run/rm のフラグベースのワークフローについては、docker-sandboxes-lifecycle を使用してください。
• 実行時の secrets:/registries:/bindings: の意味、および環境ファイルに依存せずにネットワークポリシーを構成する方法については、docker-sandboxes-network-credentials を使用してください。
• kits: エントリ（またはエージェントキットを指す agent:）が参照するキット spec.yaml のスキーマについては、docker-sandboxes-kits を使用してください。

リファレンス

• references/sources.md — 上記のすべてのルールの出典（ヘルプのキャプチャ、ソースパス、ドキュメント URL）。
• references/env-schema-fields.md — kits:、additionalWorkspaces:、mcp:、ports:、sandboxOptions: の正確なフィールド形状と YAML の例。

アセット

• assets/sbxenv.yaml — 完全で最小限かつ安全な例です。宣言元ファイル自身のディレクトリをマウントする shell エージェント、1 つの静的環境変数、そして認証情報は一切含まれていません。オンボーディング認証なしで検証およびプランが実行できます。

チェック

• checks/verification.md — sbxenv.yaml コマンドの検証ランブック（未実行のランブックです。分離された一意の名前の --app-name を使用して手動で実行してください。実際のシークレット値や、信頼できないライフサイクルコマンドを自動承認した状態で実行しないでください）。