docker-sandboxes-lifecycle

Docker Sandboxes：ローカルのライフサイクルとワークスペースの分離

概要

Docker Sandboxes（sbx）は、独自のファイルシステム、ネットワーク、Docker デーモンを備えた分離されたマイクロ VM 内で AI コーディングエージェントを実行します。このスキルでは、ローカルサンドボックスのライフサイクル（作成、再接続、一覧表示、停止、削除）と、ワークスペースの分離方法（直接バインドマウントと--clone）を扱います。ネットワークポリシー、認証情報、sbxenv.yaml、キットの作成は対象外です。関連スキルを参照してください。

このスキルを使用する場合

次の場合にこのスキルを有効にします。

• ユーザーがローカルのsbxサンドボックスを起動、再接続、停止、または削除したい場合。
• ユーザーが、ホストの作業ツリーへの書き込み可能なバインドマウントを与えずに（--clone）、エージェントにリポジトリ上で作業させたい場合。
• ユーザーが、プライマリのワークスペースと並べて、追加の読み取り専用（または書き込み制限付き）ワークスペースをマウントしたい場合。
• ユーザーがホストとサンドボックス間でファイルをコピーする、サンドボックスのポートを公開する、またはサンドボックス内で一時的なコマンドを実行する（sbx exec）場合。
• ユーザーが停止済みのサンドボックスをクリーンアップ（sbx prune）する、または特定のサンドボックスを削除（sbx rm）したい場合（破壊的な結果を理解したうえで）。

このスキルを使用しない場合

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

• docker agent run --sandboxを実行する、またはdocker agent sandboxの許可リストを管理するタスクの場合は、docker-agent-runを使用してください。CLI が不明確な場合は、コマンドを選ぶ前に、ユーザーが Docker Agent とスタンドアロンのsbxのどちらを使用しているかを確認してください。
• サンドボックスがネットワーク上で何にアクセスできるか、またはどの認証情報を使用するかに関するタスクの場合は、docker-sandboxes-network-credentialsを使用してください。
• 宣言型のsbxenv.yamlファイルを作成または実行するタスクの場合は、docker-sandboxes-envを使用してください。
• キットのspec.yamlを作成、パッケージ化、署名、または組み立てるタスクの場合は、docker-sandboxes-kitsを使用してください。
• sbx --cloud（Docker Cloud Sandboxes）に関するタスクの場合は、このスキルセットの対象外です。このスキルセットはローカルデーモンのみを扱います。

基本ガイダンス

作成と実行

• sbx run AGENT [PATH...]を使用すると、必要に応じて作成したうえで、1 ステップで接続できます。接続せずに作成するにはsbx create AGENT [PATH...]を使用し、その後sbx run --name SANDBOXで接続します。sbx runに--detached／-dを渡すと、サンドボックス ID を出力して、対話セッションを開始せずに終了します。

  sbx run shell                  # create (if needed) and attach, cwd mounted
  sbx create shell .             # create only, cwd mounted, do not attach
  sbx run --name my-sandbox       # reattach later
  

• AGENTには、組み込み名（claude、codex、cursor、devin、docker-agent、gemini、opencode、shell）またはサンドボックスキットへの参照（ローカルディレクトリ、ZIP、git、OCI）を指定します。相対パスのローカルキット参照は、明示的なパス（./my-kit、親ディレクトリからの相対.zipパス）でなければなりません。my-kitのようにパスを指定しない場合、エージェント／サンドボックス名として解釈され、現在の作業ディレクトリと同じ階層にあるディレクトリとして解釈されることはありません。
• パスを省略した場合の動作は、サブコマンドによって異なります。 パスを指定せずにsbx run claudeを実行すると、現在のディレクトリがマウントされます。パスを指定せずにsbx create claudeを実行すると、何もマウントされません。その場合、エージェントはコンテナ自身のファイルシステム内でのみ作業します。エージェントにワークスペースを与える場合は、必ずsbx createに明示的なパスを渡してください。
• 再接続には--nameを優先してください。位置引数のみの名前も引き続き機能しますが、非推奨です。 sbx run --name NAME（エージェントの位置引数は省略可能で、サンドボックス自身の仕様から読み取られます）が推奨される形式です。既知のエージェントでも明示的なキット参照でもない名前を位置引数に指定するsbx run NAMEは、従来の再接続用の省略形として引き続き受け付けられますが、非推奨の警告（"sbx run NAME is deprecated; use sbx run --name NAME instead"）が表示され、今後のリリースで削除される可能性があります。従来の形式に頼らず、必ず--nameを明示してください。

  sbx run --name existing-sandbox                 # reattach, agent read from spec
  sbx run claude --name existing-sandbox          # reattach, verify expected agent
  

ワークスペースの分離：バインドマウントと--clone

• **デフォルト（バインドマウント）：**ワークスペースのパスは、ホスト上と同じパスでサンドボックス内に読み書き可能な状態でマウントされます。エージェントは作業ツリーに直接書き込めます。
• --clone（作成時のみ）：エージェントは、ホストの Git リポジトリをコンテナ内に複製したプライベートなクローンを使って動作します。ホストのリポジトリは読み取り専用でマウントされます。エージェントのコミットはコンテナ内のクローンに保存され、sandbox-<name> Git リモート経由でホストからアクセスできます。コミットをホストに取り込むには、そこからフェッチまたはプルしてください。

  sbx create --clone --name demo claude .
  # on the host, later:
  git fetch sandbox-demo
  

• --cloneには作成時に確認される実際の前提条件があり、満たされない場合は明確なエラーで失敗します。
  • 明示的なPATHを指定する必要があります（複製元となるワークスペースが必要です）。
  • そのパスは Git リポジトリ内になければなりません。
  • Git worktreeであってはなりません（コンテナ内のクローンから、worktreeの.gitポインターをたどって別の場所にある共通ディレクトリにアクセスできないためです）。
  • その.gitはファイルではなく、実際のディレクトリでなければなりません（サブモジュールや--separate-git-dirを使った構成では.gitが別の場所を指しており、読み取り専用のソースマウントに含まれないためです）。
• 再接続時にsbx runで--cloneを指定しても、すでにクローンモードで作成されたサンドボックスの場合にのみ何も起こりません。新たな検証は行わず、既存のコンテナ内クローンを使い続けます。--cloneを指定して、これを指定せずに作成されたサンドボックス（通常のバインドマウントのサンドボックス）に再接続しようとした場合は、何も起きないわけではなく、sbx create --clone ...でサンドボックスを作り直すよう促すエラーが発生します。どちらの場合も、作成後に既存のサンドボックスのモードを変更することはできません。
• クローンモードのサンドボックスを削除またはプルーニングすると、ホストにフェッチされていないエージェントのコミットはすべて完全に失われます。コンテナ内のクローンはサンドボックス独自のファイルシステム上にあり、サンドボックスとともに削除されます。クローンモードのサンドボックスを削除する前に、作業内容をフェッチしてください。

  git fetch sandbox-demo
  

  フェッチすると、2つの refspec が作成されます。通常のrefs/remotes/sandbox-demo/*（サンドボックスの削除時にリモートとともに削除されます）と、保持用のコピーであるrefs/sandboxes/demo/*（リモートの名前空間の外にあるため、リモートを削除しても削除されません）です。サンドボックスの削除後に保持用コピーからブランチを復元するには、次を実行します。

  git branch <local-name> refs/sandboxes/demo/<branch>
  

  sbx rm／sbx pruneは、削除しようとしているクローンモードのサンドボックスについて、この警告を自動的に表示します。確認する前に内容を読み、習慣で--forceを使って警告を抑制しないでください。
• 追加のワークスペースは、最初のパスの後に追加する位置引数として指定します。読み取り専用でマウントするには、末尾に:roを付けます。:roで禁止されるのは書き込みだけで、読み取りは可能です。サンドボックスは:roマウント配下のすべてのファイルを引き続き読み取れます。機密情報を隠す方法ではなく、サンドボックスによる変更を防ぐ方法です。読み取り専用の引数にはディレクトリではなく単一のファイルを指定することもできます。これにより、サンドボックスがそれ以外は書き込み可能なワークスペース内で、そのパスだけを書き込み対象外にできます。

  sbx run claude . /path/to/docs:ro
  

  シークレット／認証情報のファイルは、この方法（:roなど）で絶対にマウントしないでください。読み取り専用のマウントでも、サンドボックス（およびその内部で動作するプロキシを介さないエージェントプロセス）はシークレットを平文で読み取れます。代わりに認証情報ストアを使用してください。詳細はdocker-sandboxes-network-credentialsを参照してください。

再接続、停止、削除

• sbx ls は、エージェント、状態、公開ポート、ワークスペースとともにサンドボックスを一覧表示します（スクリプトでの利用には --json、-q／--quiet を使用します）。
• sbx stop SANDBOX [SANDBOX...] はサンドボックスを削除せずに停止します。状態は保持され、サンドボックスは sbx run --name で再起動します。
• sbx rm [SANDBOX...] [--all] [--force] は、サンドボックス、そのコンテナ、Git ワークツリー、状態、サンドボックス単位のシークレットを削除します。この操作は取り消せません。クローンモードのサンドボックスでは、取得していないコミットもすべて破棄されます（上記参照）。破棄される内容を確認し、同意済みの場合に限り --force を使用してください。これは、このセッションで作成した一意の名前のリソースをスクリプトで削除する場合に使用するものであり、常用するものではありません。
• sbx prune [--dry-run] [--filter until=VALUE] [--force] は、停止中のサンドボックスのみを削除します。実行中のサンドボックスには決して触れません。ただし、これは破壊的で取り消せない一括削除です。一致する停止中のサンドボックスの状態とシークレットに加え、クローンモードのサンドボックスでは取得していないコミットもすべて失われます。実際に削除する前に必ず --dry-run でプレビューし、表示されるクローンのコミットに関する警告を読んでください。既定の指定として --force を渡さないでください。
  • 現在のソースでのフラグは since= ではなく --filter until=VALUE です。 VALUE には RFC 3339 のタイムスタンプ、Unix タイムスタンプ、または現在を基準とする Go の期間を指定できます（例：until=168h は過去 1 週間以内に停止したものを保持し、つまりその時点より前に停止したものをプルーニングします）。固定されたコミットにおけるソースのみの挙動であり、インストール済みの一部のビルドとは異なります。古い sbx では、レガシーエイリアスとして --filter since=DURATION が引き続き表示される場合があります。--help の出力に until= がない場合は、until= を優先し、since= はレガシーのみとして扱ってください。

  sbx prune --dry-run --filter until=168h
  # after reviewing the dry-run output and any clone-commit warnings:
  sbx prune --filter until=168h
  

ファイルのコピーとアドホックコマンドの実行

• sbx cp SRC DST はホストとサンドボックス間でコピーします。片方だけを SANDBOX:PATH にする必要があります。2 つのサンドボックス間のコピーはサポートされていません。

  sbx cp ./config.json my-sandbox:/home/agent/
  sbx cp my-sandbox:/home/agent/output.log ./
  

• sbx exec [flags] SANDBOX COMMAND [ARG...] はサンドボックス内でコマンドを実行します（停止中の場合は先に起動します）。フラグは docker exec と同様です（-it、-d、-u、-w、-e、--env-file、--privileged）。

  sbx exec -it my-sandbox bash
  sbx exec -u root my-sandbox apt-get update
  

• sbx ports SANDBOX [--publish SPEC] [--unpublish SPEC] は、作成後に公開ポートを管理します。sbx create／sbx run の -p／--publish はサンドボックスの作成時にのみ有効で、再接続時には適用されません。

サイズと名前

• --cpus（0 = 自動：ホストの全 CPU）と --memory／-m（既定値はホストメモリの 50％、512 MiB～32 GiB の範囲に制限）は、作成時にのみ設定できます。
• --name はサンドボックス名を設定します（既定値は <agent>-<workdir>）。2 文字以上で、先頭は英字または数字、使用できるのは英字、数字、ハイフン、ピリオドのみです。ASCII 文字で最大 63 文字、末尾は英字または数字にしてください。default は予約語です。

関連するスキル

• docker agent run --sandbox および docker agent sandbox コマンドについては、docker-agent-run を使用してください。

• ネットワークの外向き通信ポリシーとサービス／レジストリの認証情報については、docker-sandboxes-network-credentials を使用してください。

• この同じ作成／実行／削除のライフサイクルをラップする、宣言的でチェックイン済みの sbxenv.yaml 環境については、docker-sandboxes-env を使用してください。

• AGENT リファレンスから指定できるキットの spec.yaml を作成または組み合わせる場合は、docker-sandboxes-kits を使用してください。

参考資料

• references/sources.md — 上記の各ルールの出典（ヘルプのキャプチャ、ソースパス、ドキュメント URL）。

アセット

• なし。

チェック

• checks/verification.md — サンドボックスのライフサイクルコマンドの検証手順書（未実行の手順書です。手動で実行する際は分離された --app-name を使用し、--force は手順書独自の一意の名前が付いたテスト用サンドボックスの削除に同意済みの場合を除き、決して使用しないでください）。