応用 — 構成の再利用と発展運用

1.Kit — サンドボックス構成をコード化する

Kit は、1 つのサンドボックスの中身を YAML で宣言する仕組みである（ sbx kit --help）。 使うテンプレートや起動コマンド、許可する通信先、環境変数、エージェントへ配る設定ファイルなどをまとめて書いておき、sbx run … --kit <ディレクトリ> でその構成のサンドボックスを作れる。 一方、ホスト側のどのパスをマウントするか（rw / ro）は spec.yaml ではなく、作成時のパス引数で指定する （sbx v0.35.0 で確認。sbx kit validate もマウント用フィールドを受け付けない）。 列挙が要るのは初回作成のときだけで、2 回目以降は名前で再アタッチすれば保存済みのマウント構成が使われる （通常の run と同じ。使い方のワークスペース節）。 --kit も作成時にだけ効く。プロジェクトのリポジトリに入れておけば同じ環境を再現でき、 sbx kit pack / push / pull で OCI レジストリ経由の配布もできる。

既知のツールにたとえると、対象は Docker Compose とは違う。 Compose は複数コンテナのオーケストレーションを定義するのに対し、 Kit はサンドボックス 1 個の中身を宣言する。 1 環境の設定をコードに落とす感覚は devcontainer.json に近い 。

以下は使い方：エージェント別と同じ 4 例 （Claude Code / OpenAI Codex / cursor-agent / Grok Build）を Kit 化する。 前三者は公式テンプレートを sandbox.image に書くだけ。 Grok Build だけは公式未対応のため、イメージを自作してから Kit で包む。

schemaVersion: "1"
kind: sandbox
name: claude-code
sandbox:
  image: "docker/sandbox-templates:claude-code-docker"
  aiFilename: CLAUDE.md
  entrypoint:
    run: [claude, "--dangerously-skip-permissions"]  # 公式デフォルトと同じ YOLO。外すなら [claude] のみ
network:
  allowedDomains:
    - api.anthropic.com:443
    - github.com:443

# ―― 初回: --kit とマウントを列挙して作成（構成はサンドボックスに保存される）――
# 第1パス = プライマリ（rw）。第2パス以降は追加マウント（ro → path:ro）。マウントは spec.yaml には書けない
$ sbx run claude-code --kit ./sbx/kits/claude-code . ~/shared-libs:ro
$ sbx run claude-code --kit ./sbx/kits/claude-code ~/proj ~/docs:ro ~/design:ro

# ―― 2回目以降: マウントも --kit も不要。名前で再アタッチ ――
$ sbx run --name claude-code
$ sbx exec -it claude-code bash

schemaVersion: "1"
kind: sandbox
name: openai-codex
sandbox:
  image: "docker/sandbox-templates:codex-docker"
  aiFilename: AGENTS.md
  entrypoint:
    run: [codex, "--dangerously-bypass-approvals-and-sandbox"]  # 公式デフォルトと同じ YOLO。外すなら [codex] のみ
network:
  allowedDomains:
    - api.openai.com:443
    - openai.com:443
    - auth.openai.com:443
    - github.com:443

# ―― 初回 ――
$ sbx run openai-codex --kit ./sbx/kits/openai-codex . ~/shared-libs:ro
$ sbx run openai-codex --kit ./sbx/kits/openai-codex ~/proj ~/docs:ro

# ―― 2回目以降 ――
$ sbx run --name openai-codex
$ sbx exec -it openai-codex bash

schemaVersion: "1"
kind: sandbox
name: cursor-agent
sandbox:
  image: "docker/sandbox-templates:cursor-agent-docker"
  aiFilename: AGENTS.md
  entrypoint:
    run: [cursor-agent, "--yolo"]  # 公式デフォルトと同じ YOLO。外すなら [cursor-agent] のみ
network:
  allowedDomains:
    - api2.cursor.sh:443
    - api3.cursor.sh:443
    - github.com:443

# ―― 初回 ――
$ sbx run cursor-agent --kit ./sbx/kits/cursor-agent . ~/shared-libs:ro
$ sbx run cursor-agent --kit ./sbx/kits/cursor-agent ~/proj ~/docs:ro

# ―― 2回目以降 ――
$ sbx run --name cursor-agent
$ sbx exec -it cursor-agent bash

FROM docker/sandbox-templates:shell-docker

# grok CLI を焼き込む（インストール先の PATH 設定は install.sh が ~/.bashrc に書く）
RUN curl -fsSL https://x.ai/cli/install.sh | bash

$ docker build -t myname/grok-build ./sbx/kits/grok-build && \
  sbx template load <(docker image save myname/grok-build)

schemaVersion: "1"
kind: sandbox
name: grok-build
sandbox:
  image: "myname/grok-build"
  entrypoint:
    run: [grok]          # shell ではなく grok を直接起動
network:
  allowedDomains:
    # ホスト名は完全一致。x.ai だけでは api.x.ai 等は通らない
    - x.ai:443           # 頂点ドメイン自体
    - "*.x.ai:443"       # サブドメイン一括（sbx policy allow network と同系。ワイルドカード可）
    # 実際に必要なホストは sbx policy log で確認して足す

# ―― 初回: Kit とマウントをここで固定 ――
$ sbx run grok-build --kit ./sbx/kits/grok-build --name grok-build . ~/shared-libs:ro
$ sbx run grok-build --kit ./sbx/kits/grok-build --name grok-build ~/proj ~/docs:ro

# ―― 2回目以降: 名前だけで再アタッチ（マウントも --kit も付け直さない）――
$ sbx run --name grok-build
$ sbx exec -it grok-build bash

spec.yaml のフィールドや詳しい書き方は、 公式の Kits 解説 と Kit spec reference を参照。 チーム向けにオプション依存だけを足す kind: mixin もあるが、個人利用ではほぼ不要 （詳細は Qiita の解説 を参照）。

2.VM イメージ自体のカスタマイズ

ビルドツールや CLI を焼き込みたければ、公式テンプレートを FROM した Dockerfile を作ってロードする。

FROM docker/sandbox-templates:claude-code-docker

RUN claude update
RUN sudo apt update -y && sudo apt install -y build-essential
# 永続させたいシェル初期化はここへ（ENV だけに頼らない）
RUN echo 'eval "$(mise activate bash)"' >> /etc/sandbox-persistent.sh

$ docker build -t myname/claude-code ./sbx/kits/claude-code && \
  sbx template load <(docker image save myname/claude-code)
$ sbx template ls

ローカルで template load したイメージは sbx template ls 上 docker.io/… のように見えることがあるが、レジストリへ push したわけではない。 ベーステンプレートの Dockerfile は非公開でも、ホストに Docker があれば docker history で層の概要を覗ける場合がある。

3.環境変数と AWS 認証情報

ここでは既に動いているサンドボックスへ、ホストから一時的に環境変数を足す方法を扱う。 Kit の environment.variables や Dockerfile の ENV は作成・イメージ側の話で、 起動のたび／コマンドごとに変えたい値には向かない。そういうときが sbx exec -e である。

実行時に環境変数を渡す

sbx exec の -e NAME=value（またはホストに既にある -e NAME）で、その一回のコマンドにだけ変数を渡せる。 サンドボックスの永続状態には残らない。デバッグ用のフラグや、作業ディレクトリ固有の設定を その場で足す用途に向く。

$ sbx exec -it -e FOO=bar mybox bash   # この bash セッションにだけ FOO が付く

AWS 認証情報の特例的な渡し方

エージェントに AWS CLI や SDK を触らせたい場面がある。多くの SaaS 向け API キーは 安全性で述べるサービス資格情報のプロキシ注入で渡せ、 生の秘密を VM に入れずに済む。

ところが AWS の署名（SigV4）はプロキシがヘッダを差し替える方式では扱えない。 そのため AWS だけは、ホスト側で用意したアクセスキー等を環境変数として VM に渡す運用になりやすい。 渡した値はサンドボックス内から読めるので、長命なキーを直書きするのは避け、 aws-vault などで短命クレデンシャルを出してから sbx exec -e で渡すのが定石である。

# ホスト: aws-vault が一時キーを環境に載せたうえで sbx exec を起動する
# -e NAME だけ書くと「ホストの同名変数をそのまま渡す」
$ aws-vault exec dev -- sbx exec -it \
  -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \
  -w $(pwd) $(basename $(pwd)) bash

上の例は、カレントの作業ツリーをワークスペース名にした既存サンドボックスへ入り、 AWS 用の 4 変数だけをそのセッションに載せている。 権限は aws-vault プロファイル側で最小に絞る。詳細は安全性を参照。

4.成果物の回収

clone モードでサンドボックス内でファイルを追加・変更した後、ホスト側へ成果物を回収する方法としては、次の3通りが考えられる。

# A: ファイル単位
$ sbx cp fix-issue-123:/Users/me/project/some-file .

# B: clone モード — ホストのリポジトリで、sandbox 用 remote から取り込む
$ cd ~/path/to/repo                    # --clone を起動したホスト側リポジトリ
$ git remote -v                        # sandbox-fix-issue-123 などが付いているか確認
$ git fetch sandbox-fix-issue-123      # VM 内クローンのコミットを取得
$ git log --oneline sandbox-fix-issue-123/<branch>
$ git merge sandbox-fix-issue-123/<branch>   # または cherry-pick / 別ブランチへ checkout

C が使えない（ホスティングが無い、または外へ push したくない）ときは A か B でローカルに回収する。 B は --clone で作ったサンドボックス向け。通常マウント（rw）ならホストに直接書き込んでいるので不要。 clone の起動例自体は使い方：ワークスペースを参照。

5.自律エージェント運用パターン

Zenn の記事が示すように、 Docker Sandboxes が一番効くのは「サンドボックス上で Issue を読み、バグ修正を行い、プルリクエストを作ってもらう」 ような自律運用。--clone でホストの作業ツリーに触れさせず、成果は 上記の回収法に寄せると、 YOLO モードで放置する場合もホスト側の被害半径を縮小できる。 ただし、許可済みドメインと付与した資格情報の権限内では外部操作が可能。