アーキテクチャ

このページでは、Docker Sandboxesの仕組みとその設計思想について詳しく解説します。

なぜマイクロVMなのか？

AIコーディングエージェントは、イメージのビルド、コンテナの実行、Docker Composeの使用などを頻繁に行います。エージェントにホストマシンのDockerデーモンへのアクセスを許可するということは、エージェントがあなたのコンテナを閲覧し、イメージをプルし、システム上で直接ワークロードを実行できることを意味します。これは、自律的なコード実行に与える権限としてはあまりに強力すぎて危険です。

エージェントを通常のコンテナで実行しても、この問題は解決しません。コンテナはホストのカーネルを共有している（Docker Desktopの場合は同じ仮想マシンを共有している）ため、独自のDockerデーモンを必要とするプロセスを安全に隔離することができません。Docker-in-Docker（DinD）の手法も、ホストのソケットをマウントする特権モードで隔離性を損なうか、デーモンを入れ子にする複雑さを招くかのどちらかです。

マイクロVM（microVM）は、必要とされる明確な隔離境界を提供します。各サンドボックスにはプライベートDockerデーモンを備えた専用のVMが割り当てられます。エージェントはホストのDocker環境に一切触れることなく、イメージのビルドやテスト実行が可能です。サンドボックスを削除すれば、内部のイメージ、コンテナ、パッケージなどはすべて消去されます。

隔離モデル

サンドボックスごとのプライベートDockerデーモン

各サンドボックスは、VM内部で独立した完全なDockerデーモンを実行します。このデーモンはホストや他のサンドボックスから完全に隔離されています。

ホストシステム (Docker Desktop)
  ├── あなたのコンテナとイメージ
  │
  ├── サンドボックス VM 1
  │   ├── Dockerデーモン (隔離済み)
  │   ├── エージェント・コンテナ
  │   └── その他のコンテナ (エージェントが作成)
  │
  └── サンドボックス VM 2
      ├── Dockerデーモン (隔離済み)
      └── エージェント・コンテナ

エージェントが docker build や docker compose up を実行すると、それらのコマンドはサンドボックス内のプライベートデーモンを使用して実行されます。エージェントが見ることができるのは自身が作成したコンテナのみであり、ホスト側のコンテナ、イメージ、ボリュームにアクセスすることはできません。

このアーキテクチャは、「自律型エージェントにはフル機能のDockerが必要だが、ホストのDockerデーモンを安全に共有することはできない」という根本的な制約を解決します。

ハイパーバイザーレベルの隔離

サンドボックスは、システムのネイティブな仮想化技術を利用します：

• macOS: virtualization.framework

• Windows: Hyper-V

これにより、サンドボックスとホストの間にハイパーバイザーレベルの隔離が提供されます。ホストのカーネルを共有するコンテナとは異なり、VMは個別のカーネルを持ち、定義された境界を越えてホストのリソースにアクセスすることはできません。

セキュリティ上の利点

VMの境界によって以下の隔離が実現されます：

• プロセス隔離: エージェントのプロセスは独立したカーネル上で動作します。

• ファイルシステム隔離: マウントされたワークスペースのみがアクセス可能です。

• ネットワーク隔離: サンドボックス間での通信はできません。

• Docker隔離: ホストのデーモン、コンテナ、イメージへのアクセス権はありません。

ネットワークフィルタリングにより、HTTP/HTTPSトラフィックに対する追加の制御レイヤーが加わります。詳細はネットワークポリシーを参照してください。

ワークスペースの同期

双方向ファイル同期

ワークスペースは、ホストと同じ絶対パスでサンドボックスに同期されます：

• ホスト: /Users/alice/projects/myapp

• サンドボックス: /Users/alice/projects/myapp

変更は双方向に同期されます。ホストでファイルを編集すればエージェントに反映され、エージェントがファイルを修正すればホスト側にも反映されます。

これはボリュームマウントではなく「ファイル同期」です。ファイルはホストとVMの間でコピーされます。この手法により、異なるファイルシステム間でも動作し、プラットフォームの違いに関わらず一貫したパスを維持できます。

パスの保持

絶対パスが保持されることには以下のメリットがあります：

• エラーメッセージ内のファイルパスが、ホストとサンドボックスで一致する。

• 設定ファイル内のハードコードされたパスが正しく機能する。

• ビルドの出力が、ホスト上でも見つけられるパスを参照する。

エージェントはあなたがバイナリで見ているのと同じディレクトリ構造を見るため、デバッグや変更内容の確認時の混乱が軽減されます。

ストレージと永続性

保持されるもの

サンドボックスを作成すると、削除するまで以下が保持されます：

• Dockerイメージとコンテナ: エージェントがビルドまたはプルしたもの。

• インストールされたパッケージ: aptやyumなどで追加されたシステムパッケージ。

• エージェントの状態: 認証情報、設定、履歴。

• ワークスペースの変更: 作成・変更されたファイルはホストに同期されます。

一時的なもの（エフェメラル）

サンドボックスは軽量ですが、ステートレス（状態を持たない）ではありません。実行の合間も状態は維持されますが、他のサンドボックスからは隔離されています。各サンドボックスは以下の独自のデータを保持します：

• Dockerデーモンの状態

• イメージキャッシュ

• パッケージのインストール状態

docker sandbox rm でサンドボックスを削除すると、VM全体とその内容がすべて削除されます。サンドボックス内でビルドしたイメージやインストールしたパッケージ、ワークスペースに同期されていない状態はすべて消失します。

ディスク使用量

各サンドボックスは以下のためにディスク容量を消費します：

• VMのディスクイメージ（イメージのビルドやパッケージの追加に伴い増加）

• 内部でプルまたはビルドされたDockerイメージ

• コンテナレイヤーとボリューム

複数のサンドボックス間でイメージやレイヤーが共有されることはありません。それぞれが独立したDockerデーモンとストレージを持ちます。

ネットワーク

インターネットアクセス

サンドボックスは、ホストのネットワーク接続を介して外部へのインターネットアクセスが可能です。エージェントはパッケージのインストール、イメージのプル、APIへのアクセスができます。

ホスト上ではHTTP/HTTPSフィルタリングプロキシが動作しており、host.docker.internal:3128 で利用可能です。エージェントは外部へのWebリクエストにこのプロキシを自動的に使用します。許可する送信先を制御するためにネットワークポリシーを設定できます。

認証情報のインジェクション

HTTP/HTTPSプロキシは、サポートされているプロバイダー（OpenAI, Anthropic, Google, GitHubなど）に対するAPIリクエストに、認証情報を自動的に注入（インジェクション）します。ホスト側で OPENAI_API_KEY や ANTHROPIC_API_KEY などの環境変数を設定しておくと、プロキシが外部へのリクエストをインターセプトし、適切な認証ヘッダーを付加します。

この仕組みにより、認証情報はホストシステムに留まり、サンドボックスVM内に保存されることはありません。エージェントは認証情報なしでAPIリクエストを行い、プロキシがそれを透過的に補完します。サンドボックスを削除しても、内部に認証情報が残ることはありません。

サンドボックス間の隔離

サンドボックス同士が通信することはできません。各VMは独自のプライベートなネットワーク名前空間を持っています。あるサンドボックス内のエージェントが、別のサンドボックス内のサービスやコンテナにアクセスすることはできません。

また、サンドボックスはホストの localhost サービスにもアクセスできません。VMの境界により、ホストマシン上で動作しているサービスへの直接アクセスは遮断されます。

ライフサイクル

作成と実行

docker sandbox run は、指定されたエージェント用のワークスペースを持つVMを初期化し、既存のサンドボックス内でエージェントを起動します。VMを再作成することなくエージェントを停止・再起動できるため、インストールしたパッケージやDockerイメージを保持できます。

docker sandbox create はVMの初期化のみを行い、エージェントは自動起動しません。これにより、環境のセットアップとエージェントの実行を切り離すことができます。

状態管理

サンドボックスは明示的に削除するまで存続します。エージェントを停止してもVMは削除されません。つまり：

• インストール済みのパッケージは引き続き利用可能。

• ビルド済みのイメージはキャッシュされたまま。

• 環境設定は実行間で保持される。

ディスク容量を解放するには、docker sandbox rm を使用してサンドボックスを削除してください。

他の手法との比較

サンドボックスと他のアプローチの使い分けは以下の通りです：

サンドボックスは、リソースのオーバーヘッド（VM + デーモン）と引き換えに、完全な隔離を提供します。Dockerアクセスを必要としない軽量なパッケージングには通常のコンテナを、ホスト環境を危険にさらさずに自律型エージェントにフル機能のDockerを使わせたい場合にはサンドボックスを選択してください。