Docker Sandboxes クイックスタート

Docker Sandboxes は、隔離された microVM サンドボックス内で AI コーディング エージェントを実行します。各サンドボックスには独自の Docker デーモン、ファイル システム、ネットワークが割り当てられ、エージェントは共有したリソースを超えてホスト リソースにアクセスすることなく、コンテナーのビルド、パッケージのインストール、ファイルの変更を行うことができます。

このページでは、最初のセッションの手順を説明します。サンドボックスでエージェントを実行し、サンドボックスがどのようにエージェントを隔離するかを確認し、ネットワーク上でアクセスできるものを制御し、クリーンアップを行います。

---

前提条件

• sbx CLI をインストールし、Docker にサインインします。
• 使用するエージェントの認証方法を設定します。ほとんどのエージェントでは、モデル プロバイダーの API キーが必要です。プロバイダー固有の手順については、エージェント ページを参照してください。

---

エージェントの認証

Claude サブスクリプション (Max、Team、または Enterprise) を使用する Claude Code の場合、事前の設定は不要です。サンドボックス内で /login コマンドを使用して OAuth でサインインします。セッション トークンはホスト上に残り、サンドボックス内に保存されることはありません。

API キーを使用した認証を希望する場合は、sbx secret set でキーを保存する方法について、資格情報 (英語) を参照してください。

プル リクエストの作成やリポジトリとのやり取りを行うためにエージェントに GitHub へのアクセス権を与えるには、次のように実行します:

$ sbx secret set github --command 'gh auth token'

---

最初のサンドボックスの実行

プロジェクト ディレクトリを選択し、sbx run でエージェントを起動します:

$ cd ~/my-project
$ sbx run --name my-sandbox claude

初めてサンドボックスを実行すると、CLI によってデフォルトのネットワーク プリセットを選択するよう求められます:

Initialize the global network policy for your sandboxes:

  Applies to all sandboxes, current and future — change it later with
  "sbx policy allow/deny/rm". Kits, including built-in agent kits, may
  also add per-sandbox rules.

     1. Open         — All network traffic allowed, no restrictions.
  ❯  2. Balanced     — Default deny, with common dev sites allowed.
     3. Locked Down  — All network traffic blocked unless you allow it.

  Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel.

Balanced は良い出発点です。一般的な開発サービスへのトラフィックを許可し、それ以外をブロックします。個々のルールは後で調整できます。各オプションの完全な説明については、ローカル ポリシー (英語) を参照してください。

claude を使用したいエージェントに置き換えてください。すべてのリストについては、エージェントを参照してください。

最初の実行では、エージェント イメージがプルされるため少し時間がかかります。以降の実行ではキャッシュされたイメージが再利用され、数秒で起動します。

これにより、サンドボックス内で実行されているエージェントに接続されます。機能の追加、依存関係のインストール、プロジェクトのビルドと実行など、実際のタスクを与えてみてください。エージェントは独自の Docker デーモンを備えた完全な Linux 環境を持っているため、作業中にパッケージのインストール、イメージのビルド、コンテナーの起動を独自に行うことができます。

---

エージェントが触れられるものを確認する

別のターミナルから、サンドボックスをリストします:

$ sbx ls
SANDBOX       AGENT    STATUS    PORTS   WORKSPACE
my-sandbox    claude   running           ~/my-project

各行には、サンドボックスの名前、実行されているエージェント、ステータス、公開されているポート、およびそのワークスペース (サンドボックスと共有されているホスト ディレクトリ) が表示されます。そのワークスペースは、エージェントが見ることができるマシンの唯一の部分です。

ワークスペース パスを渡さずにプロジェクト ディレクトリから sbx run を実行すると、現在のディレクトリが読み書き可能でマウントされます。エージェントとホストは同じファイルを確認します。エージェントがプロジェクトに加えた変更は、書き込まれると作業ツリーに表示され、コミットする前に通常の Git 差分として確認できます。

その他はすべて microVM 内で実行され、ホストから隔離されます:

• エージェントには独自のファイル システム、Docker デーモン、ネットワークがあります。
• エージェントがインストールするパッケージ、プルするイメージ、起動するコンテナーはサンドボックス内に留まります。ホスト システムは変更されず、サンドボックスを削除するとそれらも破棄されます。

例えば、1 つのリポジトリで複数のエージェントを実行する場合など、エージェントが作業ツリーに全く触れないようにしたい場合は、代わりにプライベートなクローンを提供するクローン モードを使用します。

---

エージェントがアクセスできるものを制御する

隔離はファイル システムだけではありません。サンドボックスがネットワーク上で到達できるものも制御できます。サンドボックスが起動する前にデフォルトのポリシーを選択しましたが、いつでも確認または調整できます。

現在有効なルールを確認します:

$ sbx policy ls

特定のホストを許可するには:

$ sbx policy allow network registry.npmjs.org

Locked Down を選択した場合、明示的に許可しない限り、モデル プロバイダーの API であってもブロックされます。Balanced を選択した場合、一般的な開発サービスはデフォルトで許可されます。完全なルール セットとカスタマイズ方法については、ローカル ポリシーを参照してください。

---

クリーンアップ

サンドボックスはエージェントが終了した後も存続するため、停止して後で再開することができます:

$ sbx stop my-sandbox

インストールされたパッケージ、Docker イメージ、および設定の変更は再起動後も保持されます。サンドボックスが不要になった場合は、削除してディスク領域を解放します:

$ sbx rm my-sandbox

サンドボックスを削除すると、インストールされたパッケージ、Docker イメージ、およびクローン モードを使用した場合のサンドボックス内の Git クローンなど、内部のすべてのものが削除されます。ホストの作業ツリー内のファイルには影響しません。

このページではローカル サンドボックスについて説明します。クラウド コマンド、ファイル転送、ポート、および有効期限については、Cloud sandboxes の使用を参照してください。

日常の sbx オペレーション向けのコマンドベースのガイドとしてご利用ください。シナリオベースの推奨事項については、ワークフロー パターン (英語)を参照してください。

---

サインイン

ターミナルからサインインします:

$ sbx login

ブラウザーが利用できないスクリプトや CI ランナーの場合は、CI およびヘッドレス使用 (英語) を参照してください。

---

開始、停止、および削除

基本的なワークフローは、開始に run、ステータス確認に ls、一時停止に stop、クリーンアップに rm を使用します:

$ sbx run claude                    # 現在のディレクトリでエージェントを起動
$ sbx ls                            # 実行中のサンドボックスを確認
$ sbx stop my-sandbox               # 一時停止
$ sbx rm my-sandbox                 # 完全に削除

サンドボックスにアクティブなセッション（開いているアタッチ、SSH 接続、または進行中の SFTP 転送など）がある場合、--force を渡さない限り sbx rm は拒否されます:

$ sbx rm --force my-sandbox

クリーンな状態が必要な場合は、サンドボックスを削除して再度実行します:

$ sbx stop my-sandbox
$ sbx rm my-sandbox
$ sbx run claude

停止しているすべてのローカル サンドボックスを削除するには、sbx prune を使用します。実行中のサンドボックスは決して削除されません。削除されるサンドボックスをプレビューしたり、過去 1 週間に停止したサンドボックスをフィルタリングしたりできます:

$ sbx prune --dry-run
$ sbx prune --filter since=168h

フラグなしで sbx prune を実行すると、停止しているすべてのサンドボックスを確認して削除します。

---

ワークスペースの選択

ワークスペース パスを渡さない場合、sbx run は現在のディレクトリをマウントします。別のディレクトリをマウントするにはパスを渡します:

$ sbx run claude
$ sbx run claude ~/my-project

最初のワークスペース パスがプライマリ ワークスペースとなります。エージェントはそこから開始し、sbx exec はそれをデフォルトの作業ディレクトリとして使用します。ホスト ディレクトリは、サンドボックス内の同じ絶対パスにマウントされます。パスを渡さない場合は、現在のディレクトリがプライマリ ワークスペースになります。

sbx バージョン 0.42.0 以降では、sbx create のワークスペース パスはオプションです。ホスト ワークスペースのバインド マウントなしのサンドボックス（マウントなしのサンドボックス）を作成する場合はパスを省略し、名前でサンドボックスにアタッチします:

$ sbx create --name scratch claude
$ sbx run --name scratch

マウントなしのサンドボックスでは、エージェントはテンプレート イメージの作業ディレクトリで起動します。Docker が提供するテンプレートでは /home/agent/workspace を使用します。そこのファイルは停止や再起動後も保持されますが、サンドボックスを削除すると削除されます。サンドボックスに名前を割り当てて再接続できるようにし、ホストとサンドボックス間でファイルを転送するには sbx cp を使用します。

---

サンドボックスの再接続と命名

サンドボックスはエージェントの終了後も存続します。同じワークスペース パスを再度実行すると、別のサンドボックスを作成するのではなく、既存のサンドボックスに再接続します:

$ sbx run claude ~/my-project  # サンドボックスを作成
$ sbx run claude ~/my-project  # 同じサンドボックスに再接続

サンドボックスに明示的な識別子を与えるには --name を使用します:

$ sbx run --name my-project claude

名前付きサンドボックスが存在するようになれば、任意の作業ディレクトリから sbx run --name で再アタッチできます。再アタッチ時はエージェント名を省略できます:

$ sbx run --name my-project        # どこからでも再アタッチ
$ sbx run claude --name my-project # 上記と同じ（エージェントを確認）

同じワークスペースに対して複数のサンドボックスを実行するには、それぞれに異なる名前を付けます:

$ sbx run claude --name feature ~/my-project
$ sbx run claude --name spike ~/my-project

---

アタッチせずに作成

sbx run はサンドボックスを作成し、エージェントにアタッチします。アタッチせずにバックグラウンドで現在のディレクトリをマウントしたサンドボックスを作成するには、次のようにします:

$ sbx create --name my-project claude .

パスを省略すると、マウントなしのサンドボックスが作成されます。後で sbx run --name を使用してアタッチします:

$ sbx create --name scratch claude
$ sbx run --name scratch

---

環境変数の設定

サンドボックス内で環境変数を設定するには、sbx run または sbx create に -e または --env を渡します:

$ sbx run -e LOG_LEVEL=debug claude

ホスト環境から値をコピーするには、値なしで変数名を指定します:

$ export API_URL=https://api.example.com
$ sbx run -e API_URL claude

複数の変数をロードするには、1 つ以上の環境ファイルを渡します:

$ sbx create --name my-project --env-file .env.sandbox claude .

フラグは docker run の優先順位ルールに従います。-e で渡された値は環境ファイルからの値を上書きします。複数の環境ファイルを渡した場合、後から指定したファイルの値が先に指定したファイル内の同じ変数を上書きします。

将来のセッションで環境変数を保持するには、/etc/sandbox-persistent.sh に export 追記します:

$ sbx exec -d <sandbox-name> bash -c "echo 'export INTERNAL_API_URL=https://api.example.com' >> /etc/sandbox-persistent.sh"

---

サンドボックス内でコマンドを実行

実行中のサンドボックス内でシェルを取得するには、sbx exec を使用します:

$ sbx exec -it <sandbox-name> bash

---

インタラクティブ モード

サブコマンドなしで sbx を実行すると、インタラクティブ ターミナル ダッシュボードが開きます:

$ sbx

ダッシュボードには、ライブ ステータス、CPU、およびメモリ使用量を備えたカードとしてすべてのサンドボックスが表示されます。ダッシュボードからは以下が可能です:

• Create (作成): c
• Start/Stop (開始/停止): s
• Attach (アタッチ): Enter
• Shell (シェルを開く): x
• Remove (削除): r

---

Git ワークスペース モード

プライマリ ワークスペースが Git リポジトリである場合、サンドボックスを作成するときにワークスペースをどのように受け取るかを選択できます:

• 直接モード (Direct mode) は sbx run のデフォルトです。エージェントは作業ツリーへの読み取り/書き込みアクセス権を持ち、変更はすぐにホストに表示されます。
• クローン モード (Clone mode) は --clone を使用します。エージェントはサンドボックス内の別の Git クローンを編集します。変更はフェッチするかエージェントがプッシュするまでそこに留まります。ホスト リポジトリも /run/sandbox/source で利用可能ですが、読み取り専用アクセスとなります。

クローン モード

クローン モードのサンドボックスを作成するには、実行または作成時に --clone を渡します:

$ sbx run --clone claude .

---

複数のワークスペース

メイン ワークスペースと一緒に、追加のディレクトリをサンドボックスにマウントできます。追加のワークスペースを読み取り専用でマウントするには :ro を追加します:

$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro

---

ホストとサンドボックス間でファイルをコピー

ホストとサンドボックス間でファイルまたはディレクトリをコピーするには sbx cp を使用します。

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

コピーのどちらか一方は SANDBOX:PATH を使用する必要があります。2 つのサンドボックス間で直接コピーすることはサポートされていません。

---

ポートの公開

サンドボックスはネットワーク的に隔離されています。デフォルトでは、ブラウザーやローカル ツールはサンドボックス内で実行されているサーバーに到達できません。8080:3000 のポート マッピングは、サンドボックス ポート 3000 をホスト ポート 8080 に公開します。

サンドボックスの作成時にポートを公開するには:

$ sbx run --publish 8080:3000 --name my-sandbox claude

既存のサンドボックスの場合は、sbx ports を使用します:

$ sbx ports my-sandbox --publish 8080:3000
$ open http://localhost:8080

ポートの公開を停止するには:

$ sbx ports my-sandbox --unpublish 8080:3000

---

保持されるもの

サンドボックスが存在する間は、インストールされたパッケージ、Docker イメージ、設定の変更、コマンド履歴、およびマウントなしのワークスペース ファイルはすべて、停止と再起動を繰り返しても保持されます。サンドボックスを削除すると、内部のすべてのものが削除されます。

Cloud sandboxes は、ローカル マシンではなく Docker が管理するインフラストラクチャ上で AI エージェントを実行します。ホストのコンピュート リソースや仮想化サポートに依存しない、隔離された環境が必要な場合に使用します。

Cloud sandboxes は、ローカル サンドボックスと同じ sbx CLI を使用します。グローバルの --cloud フラグを追加することで、サポートされているコマンドを Cloud Sandboxes API に送信します:

$ sbx --cloud ls

Cloud sandboxes とローカル サンドボックスは、状態が異なり、機能も異なります。Cloud sandboxes はホスト ワークスペースをマウントしたり、ホストのハードウェアを使用したりすることはできず、シークレット、ネットワーク ポリシー、ポート、およびライフサイクルはクラウド内で管理されます。ローカル ワークフローを適用する前に、ローカルとクラウドの違い (英語) を確認してください。

---

前提条件

Cloud sandboxes を使用するには、以下が必要です:

• sbx CLI、バージョン 0.42.0 以降
• sbx login を通じてサインインした Docker アカウント
• 有効な Docker Agentic Platform プラン

サブスクライブするには、Docker Agentic Platform を開いてサインインします。このプランは Docker Personal および Docker Pro アカウントで利用可能です。

Cloud sandboxes のコンピュートは、Docker Agentic Platform の従量課金プランを通じて計測されます。推論の料金は含まれていません。構成した API キーまたは OAuth 資格情報を使用して行われたリクエストに対しては、モデル プロバイダーが課金します。

---

始め方

ローカル サンドボックス用に構成された資格情報は、Cloud sandboxes では利用できません。エージェントを起動する前に、エージェント用のクラウド資格情報を構成してください。
Claude Code の場合、Anthropic API キーを保存します:

$ sbx --cloud secret set anthropic

Cloud sandboxes はデフォルトで 1 時間後に期限切れになり、期限切れになると削除されます。保持したい作業は有効期限が切れる前にコピーして取り出してください。その他のタイムアウト オプションについては、有効期限の設定 (英語) を参照してください。

この例では、アタッチせずにサンドボックスを作成し、GitHub へのアクセスを許可します:

$ sbx --cloud create --name cloud-project --allow-network github.com:443 claude

Cloud sandboxes はローカル ワークスペース パスを受け付けません。サンドボックス内でパブリックの Welcome to Docker リポジトリをクローンします:

$ sbx --cloud exec cloud-project git clone \
    https://github.com/docker/welcome-to-docker.git /home/agent/workspace/project

エージェントにアタッチします:

$ sbx --cloud attach cloud-project

Claude に /home/agent/workspace/project を調べ、アプリケーションの説明を /home/agent/workspace/review.md に書き込むように依頼します。ファイルの準備ができたら、Ctrl+\ を押してデタッチし、エージェントを実行したままにします。

結果をローカル マシンにコピーします:

$ sbx --cloud cp cloud-project:/home/agent/workspace/review.md ./review.md

結果を確認し、終了したらサンドボックスを削除します:

$ sbx --cloud rm cloud-project

削除すると、サンドボックス内にのみ保存されているファイルが削除されます。ご自身のプロジェクトの場合は、プライベート リポジトリをクローンする前に、ファイル転送 (英語) とクラウド エージェントの認証 (英語) について確認してください。