Docker Sandboxes の使い方

1.clone かマウントか — ワークスペースの渡し方

エージェントを起動する前に決めるべきなのが、プロジェクトをどうサンドボックスに見せるか。 選択肢は「通常マウント（rw）」「読み取り専用マウント（ro）」「--clone」の 3 つで、 モードは作成時に固定され、後から切り替えられない（安全性の詳細の clone モードの節も参照）。

判断の目安

• 対話的にペアプロ感覚で進める → 通常マウント。変更が即ホストに現れるので、手元のエディタ・git で随時レビューできる。
• 任せて放置する・並列に走らせる・リスクの高い作業 → clone。ホストの作業ツリーを直接変更させず、失敗時はサンドボックスを捨てられる。
• 迷ったら「エージェントが暴走したとき、その書き込みが即ホストに反映されて困るか？」で決める。困るなら clone。

それぞれの起動法

$ cd ~/path/to/project
$ sbx run claude                                # カレントを同じ絶対パスに rw マウント
$ sbx run claude . ~/shared-libs:ro ~/docs:ro   # カレント＋参照専用の追加マウント（公式例の形）
$ sbx run claude ~/scratch ~/project:ro         # プロジェクトを「読ませるだけ」にしたい場合

$ cd ~/path/to/repo                             # Git リポジトリであることが必須
$ sbx run --clone --name fix-issue-123 claude   # プライベートクローン内で作業させる
# ブランチは自動で切られないので、エージェントに指示して切らせる
# clone モードからの成果物の回収 → 応用へ
$ sbx cp fix-issue-123:/Users/me/project/some-file .

成果物の回収法は 応用：成果物の回収にまとめた。

sbx create — エージェントを開かずにサンドボックスだけ作る

ここまでの例は主に sbx run（無ければ作り、すぐエージェントに入る）だった。 sbx create はアタッチせずにサンドボックスだけを作るコマンドである （sbx create --help）。マウント構成や --name / --clone / --kit は run と同じ考え方で指定できる。作ったあとエージェントを開くときは sbx run --name …、シェルだけ入るときは sbx exec （実践レシピでも対比する）。

$ sbx create --name mybox claude .
$ sbx run --name mybox                 # → Claude など、作成時に指定したエージェントを開く
$ sbx exec -it mybox bash              # → エージェントは開かず、任意コマンド（ここではシェル）

どちらも「既にある mybox に入る」点は同じで、何を起動するかが違う。 run は Kit の起動コマンド（エージェント本体）、exec はこちらが指定したコマンド。

一つのリポジトリに複数パッケージがあるとき

フロントエンド・バックエンドなどを一つの Git リポジトリ配下のサブディレクトリに並べる構成 （いわゆるモノレポ）では、サブディレクトリだけをプライマリにすると .git/ が見えず Git 操作ができない。 また、マウント点より親のパスはホストと中身を共有しない（親ディレクトリ名は見えるが、中身は別物になりうる）。 だから create / run ではリポジトリルートをマウントし、パッケージ配下での作業は sbx exec -w でカレントだけ移す。

$ cd /Users/me/monorepo                 # リポジトリルート（.git がある場所）
$ sbx create --name my-mono claude .
$ sbx exec -it -w /Users/me/monorepo/packages/app my-mono bash
# -w はマウント済みパスの中の作業ディレクトリ（ホストと同じ絶対パス）

後から構成（rw / ro / --clone・マウント一覧）を変えたくなったら

rw ⇄ ro の切り替えだけでなく、「どのパスを見せるか」というマウント一覧そのものも作成時に固定で、 既存のサンドボックスに対して後からディレクトリを追加・削除する手段はない。 構成はサンドボックスの spec として保存され、変えたくなったら新しいサンドボックスを作るのが答え。 同じディレクトリに対して複数のサンドボックスを --name で区別して共存させられるので、 「切り替える」というより「用途ごとに名前の違うサンドボックスを持つ」と考えるのが実態に近い。

裏を返すと、マウントパスの列挙が必要なのは初回（作成時）だけ。 2 回目以降の run は同じディレクトリから sbx run claude と打つか --name を指定すれば、保存された spec どおりのマウント構成で再アタッチされる。 exec に至ってはマウントを受け取る引数自体が存在しない （-w でマウント済みパスの中から作業ディレクトリを選ぶだけ）。

# ―― 初回: マウント構成を列挙して作成（spec に保存される）――
$ cd ~/proj
$ sbx run claude . ~/shared-libs:ro
#   ↑ 名前を指定していないので、この時点でデフォルト名 claude-proj
#     （<agent>-<ディレクトリ名>）が自動的につく

# ―― 2回目以降: マウントするパスの列挙は不要。作成時に保存された構成が復元される ――
$ sbx run claude                    # デフォルト名 claude-proj を計算 → その名前のサンドボックスが既にあるので再アタッチ
$ sbx run --name claude-proj        # 自動命名された名前を直接指定しても同じサンドボックス
$ sbx exec -it claude-proj bash     # エージェントを開かず、既存サンドボックスで bash を実行

# ―― 後から ~/design-docs も見せたくなった。選択肢は 3 つ ――
# (a) 数ファイル要るだけ → マウントせず cp で持ち込む（構成は不変のまま）
$ sbx cp ~/design-docs/spec.md claude-proj:/Users/me/proj/

# (b) 恒久的に必要 → 作り直す（構成は変更不可のため）
$ sbx rm claude-proj
$ sbx run claude . ~/shared-libs:ro ~/design-docs:ro

# (c) 今の作業を止めたくない → 新構成のサンドボックスを別名で並行に作り、移行後に旧サンドボックスを消す
$ sbx run --name proj-v2 claude . ~/shared-libs:ro ~/design-docs:ro
$ sbx rm claude-proj                # 移行が済んだら

新しいサンドボックスにはエージェントの認証・インストール済みツールは引き継がれない点だけ注意 （ツール類は Kit 化しておけば作り直しは安い。認証はサンドボックスごとに初回 1 回)。

# ① ふだんの対話的開発（rw、いつものサンドボックス。デフォルト名は <agent>-<workdir> → claude-proj）
$ cd ~/proj
$ sbx run claude

# ② 見知らぬ OSS 由来のコードを「読ませて調査だけ」させたくなった
#    → ①のサンドボックスはそのまま残し、読み取り専用のサンドボックスを別名で追加
$ sbx run --name proj-audit claude ~/scratch ~/proj:ro

# ③ 大きめのリファクタを放置で走らせたくなった
#    → clone のサンドボックスをさらに別名で追加（成果は応用の回収法へ）
$ sbx run --clone --name proj-refactor claude

# ④ サンドボックスは互いに独立。一覧で確認し、不要になったものから消す
$ sbx ls
$ sbx rm proj-audit

$ sbx rm proj-audit                             # いったん削除して
$ sbx run --name proj-audit claude ~/proj       # 権限を変えて同名で作り直す（認証はやり直し）

2.エージェント別の使い方

公式に対応しているエージェントは Claude Code / Codex / Copilot / Cursor / Droid / Gemini / Kiro / OpenCode / Docker Agent、それに手動セットアップ用の shell。 ここでは4つの例を示す。以下の例は通常マウントで書いているが、 どのエージェントでも前章の判断で --clone を付ければそのまま clone モードになる。初回はエージェントごとに認証（ブラウザ経由の OAuth など）を求められるが、認証状態はサンドボックス内に永続化されるので 2 回目以降は不要。

$ cd ~/path/to/project
$ sbx run claude

$ cd ~/path/to/project
$ sbx run codex

$ cd ~/path/to/project
$ sbx run cursor

$ sbx run --name grok-build shell

# docker version
            # docker run --rm hello-world
            # docker build -t my-app .
            # docker compose up

# curl -fsSL https://x.ai/cli/install.sh | bash

# exec bash          # 環境変数をリロード
# grok               # 表示される URL をホストのブラウザで開き、認証コードを打ち込む

$ sbx run --name grok-build
# 注: sbx run grok-build（--name なしの旧形式）も動くが、v0.35 では deprecated 警告が出る

3.実践レシピ集

sbx create / run / exec の使い分け

Docker の create / run / exec の違いと同様 （ワークスペース節でも触れた）。

• sbx create — サンドボックスを作るだけ（エージェントは起動しない）。docker create に相当。
• sbx run — 無ければ作って、エージェントとの対話を始める・再開する。docker run に相当。
• sbx exec — 既にあるサンドボックスで任意コマンドを実行する。docker exec に相当。

だから create のあとに続くのは二択になる。 sbx run --name … は作成時に決めたエージェントを開き、 sbx exec … はエージェントを開かずにシェルや単発コマンドだけを走らせる。

エージェントが作業している最中でも、別ターミナルから sbx exec -it mybox bash で同じサンドボックスに入って ログや生成物を直接確認できる。停止中なら起動してからコマンドを実行する。ポリシーでブロックされた通信の調査 （sbx policy log と合わせて）にも便利。

デフォルトのサンドボックス名は <agent>-<workdir>（例: claude-proj）。 つまり同じディレクトリでもエージェントが違えば自動的に別のサンドボックスになる。 名前未指定の run はこのデフォルト名のサンドボックスだけを見る（名前解決の詳細はワークスペース節のコラム参照）。 --name で再アタッチするときはエージェント指定を省略でき（仕様から読まれる）、 エージェント自身に渡す引数は -- の後ろに書く。

$ sbx run --name mybox                    # 既存のサンドボックスへ再アタッチ（エージェント指定は省略可）
$ sbx run mybox                           # ← 旧形式。動くが v0.35 で deprecated 警告が出る（--name を使う）
$ sbx run claude -- --continue            # "--" 以降はエージェント自身への引数（例: 前回の続きから）
$ sbx create --name mybox claude .        # アタッチせず作成（前述）。後で sbx run --name mybox
$ sbx run --cpus 4 -m 8g claude           # リソース割当（デフォルト: CPU=ホスト全部 / メモリ=ホストの50%・最大32GiB）

サンドボックスを使い回すか、作り直すか

同じエージェントを使う場合でも「既存のサンドボックスを使い回す」か「新規に作る」かは場面で変わる。 基本方針は「1 プロジェクト = 1 サンドボックスで使い回し、怪しくなったら捨てて作り直す」。 状態（インストール済みツール・エージェントの認証・ビルドキャッシュ・取得済み Docker イメージ）は rm するまで残るので、継続作業では使い回すほど起動が速く快適になる。 一方でサンドボックスは「汚染されうる環境」でもあるので、疑わしくなった時点で捨てるのが正しい。

• 使い回す — 同一プロジェクトの継続作業。grok-build のように手動で環境を育てたサンドボックス。認証をやり直したくない場合。
• 新規に作る — 別プロジェクトを始めるとき（デフォルト名はエージェント名と作業ディレクトリ名から決まる）。 同一リポジトリで複数タスクを並列に走らせるとき（--clone --name task-a / task-b のように分ける）。
• 捨てて作り直す — 実験的なインストールで環境を壊した疑いがあるとき。信頼できない依存パッケージや 怪しい入力をエージェントに触らせた後（サンドボックスごと汚染されたとみなす）。Kit 化しておけば再構築コストはほぼゼロ。

日常操作チートシート

$ sbx                                # 引数なしで対話モード（概要・状態の確認。版で UI は変わりうる）
$ sbx ls                             # 一覧・状態確認
$ sbx exec -it mybox bash            # 中にシェルで入る
$ sbx exec mybox ls /Users/me/project       # 単発コマンド実行
$ sbx cp ./local.txt mybox:/Users/me/project/   # ファイル転送（双方向）
$ sbx stop mybox                     # 一時停止
$ sbx rm mybox                       # 削除（--force で強制）

パッケージ・Docker イメージ・設定などサンドボックス内の状態は、rm するまで永続する。エージェントのログイン状態もそのサンドボックスに残る。sbx rm や作り直しではサンドボックス内の認証・インストール済みツールは消える（ホスト側ブラウザのエージェント用セッションとは別）。

複数ディレクトリのマウント

第 1 パスがプライマリワークスペースになる。第 2 パス以降の追加ワークスペースは、パス末尾に :ro を付けて読み取り専用（ro）にできる（詳細と変更時の扱いはワークスペース節）。

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

開発サーバーのポート公開

サンドボックスはネットワーク隔離されている。VM 内で npm run dev や python -m http.server を起動しても、ホストのブラウザから http://localhost:… では届かないのが正常である。 ホスト側へ明示的に穴を開けるのが sbx ports --publish。

1. サンドボックス内で開発サーバーを起動する（例: 待ち受けが 3000）。
2. ホストの別ターミナルでポートを公開する。ホスト側:VM内 の順。
3. ホストのブラウザで 公開したホスト側ポートにアクセスする。

# 例: VM 内で 3000 番を待っている開発サーバーを、ホストの 8080 から見る
$ sbx ports mybox --publish 8080:3000    # ホスト8080 → VM内3000
$ open http://localhost:8080             # ホスト側は 8080（VM の 3000 ではない）

$ sbx ports mybox                        # 公開中の一覧で確認
$ sbx ports mybox --unpublish 8080:3000  # 公開を解除

サンドボックス内での Docker 実行

組み込みエージェントをテンプレート指定なしで起動すると、デフォルトでは 名前が -docker で終わるテンプレート（例: shell-docker、claude-code-docker）が選ばれる。 これを本文では -docker 版と呼ぶ。 中身は「ホストの Docker を使う設定」ではなく、 そのサンドボックス用 microVM に Docker Engine（dockerd）が同梱されたイメージである。 そのためホストに Docker Desktop / Docker Engine がなくても、サンドボックス内でコンテナをビルド・実行できる。 Engine・イメージ・コンテナ・ボリュームはホストや他のサンドボックスと共有されない。

$ cd ~/path/to/project
$ sbx run --name sbx-docker-lab shell

# サンドボックス内
# docker version
# docker run --rm hello-world
# docker build -t my-app .
# docker compose up

shell のデフォルトは docker/sandbox-templates:shell-docker（-docker 版）。 サンドボックス内 Docker が不要な軽量環境にしたい場合だけ、サフィックスのない非 Docker 版 --template docker.io/docker/sandbox-templates:shell を明示する （この場合 microVM 内に dockerd は無く、docker run は使えない）。

よくある失敗（症状 → 原因 → コマンド）

本文で触れた落とし穴を、診断用に短く並べた。