Sandboxing in Gemini CLI

概要

シェルコマンドやファイル変更といった危険になりうる操作をホストシステムから隔離する仕組み。プロセス全体を隔離する方式と、ツール単位で隔離する方式がある。

仕様

有効化の方法（優先順位順）

コマンドフラグ: -s または --sandbox
環境変数: GEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc
settings ファイル: settings.json の tools オブジェクトの "sandbox"

sandbox の方式

1. macOS Seatbelt（macOS 専用）

sandbox-exec を使った軽量な組み込み sandbox
既定プロファイルは permissive-open: 既定で操作を拒否し、書き込みをプロジェクトディレクトリに閉じ込めつつ、広いファイル読み取りとネットワークアクセスを許す
組み込みプロファイル（SEATBELT_PROFILE 環境変数で指定）

プロファイル	内容
`permissive-open`（既定）	書き込み制限、ネットワーク許可
`permissive-proxied`	書き込み制限、ネットワークはプロキシ経由
`restrictive-open`	厳しい制限、ネットワーク許可
`restrictive-proxied`	厳しい制限、ネットワークはプロキシ経由
`strict-open`	読み書きとも制限、ネットワーク許可
`strict-proxied`	読み書きとも制限、ネットワークはプロキシ経由

2. コンテナベース（Docker / Podman）

既定イメージは ghcr.io/google/gemini-cli:latest
前提: Docker または Podman がインストール・起動されていること
現在の作業ディレクトリは、ホストと完全に同じ絶対パスでコンテナ内にマウントされる
カスタムイメージ
- Option A: レジストリ上のイメージを settings.json の tools.sandbox にオブジェクトで指定するか、GEMINI_SANDBOX_IMAGE 環境変数で指定する
- Option B: プロジェクトルートに .gemini/sandbox.Dockerfile を置き、BUILD_SANDBOX=1 を付けて実行すると自動ビルドする。既定の ghcr.io/google/gemini-cli をベースにする場合、gh CLI のインストールと認証が必要
bash などの標準シェルユーティリティが入っていれば、任意の Docker / Podman イメージを sandbox に使える

3. Windows Native Sandbox（Windows 専用）

書き込みが必要なファイルとディレクトリに icacls で "Low Mandatory Level" を設定する
この整合性レベルの変更はファイルシステム上に永続する。 sandbox セッション終了後も、作成・変更されたファイルは "Low" のまま
手動でリセットするには icacls "C:\path\to\dir" /setintegritylevel Medium
C:\Windows などのシステムフォルダには安全のため整合性レベルを設定しない

4. gVisor / runsc（Linux 専用）

利用可能な中で最も強い隔離。ユーザー空間カーネル内でコンテナを走らせる
前提: Linux、Docker のインストールと起動、gVisor/runsc ランタイムの設定
sandbox: "runsc" にすると docker run --runtime=runsc ... を実行する
runsc は自動検出されない。明示的に指定する必要がある（GEMINI_SANDBOX=runsc または sandbox: "runsc"）

5. LXC/LXD（Linux 専用、experimental）

systemd や snapd を含む完全な Linux システムを走らせるコンテナ。標準の Docker コンテナで動かない Snapcraft や Rockcraft のようなツール向け
前提: Linux 専用、LXC/LXD のインストール、コンテナが Gemini CLI 起動前に作成・起動されていること（Gemini は自動でコンテナを作らない）
GEMINI_SANDBOX_IMAGE でコンテナ名を指定できる
制限: Linux のみ、コンテナが既に存在して動いていること、ワークスペースは同じ絶対パスで bind-mount されるためそのパスがコンテナ内で書き込み可能である必要がある

tool sandboxing

shell_exec や write_file といった個々のツール実行を隔離する方式。Gemini CLI プロセス全体を sandbox に入れるのではない
UI 描画や設定読み込みといったツール以外の処理でローカル環境との統合性を保ちつつ、ツール操作にセキュリティを与える
無効にするには settings.json の security.toolSandboxing を false にする。変更には Gemini CLI の再起動が必要

sandbox expansion

コマンドに追加の権限を動的に要求する仕組み。

検出: sandbox の拒否を検出するか、追加権限が要るコマンド（npm install など）を先回りで判定する
要求: 必要な追加権限（特定のディレクトリ、ネットワークアクセスなど）を説明するモーダルを表示する
承認: 承認すると、その実行に限り拡張された権限でコマンドを実行する

ワークスペース外のファイル

既定では sandbox は現在のプロジェクトワークスペースにしかアクセスできない
SANDBOX_MOUNTS 環境変数に from:to:opts 形式のカンマ区切りリストを渡してマウントする
to を省略すると from と同じパス、opts を省略すると ro（read-only）になる。from は絶対パスでなければならない

Docker コンテナ内で Gemini CLI を動かす場合

Docker ソケットをマウントする（/var/run/docker.sock）。CLI がホストの Docker デーモン経由で兄弟 sandbox コンテナを起動できるようにするため
ワークスペースのパスを揃える。コンテナ内のワークスペースパスがホスト上の絶対パスと完全に一致する必要がある。sandbox コンテナはホストの Docker デーモンが起動するため、ボリュームマウントをホストのファイルシステムに対して解決するから

詳細設定

SANDBOX_FLAGS: コンテナベースの sandbox で docker / podman コマンドにカスタムフラグを注入する。複数はスペース区切り
SANDBOX_SET_UID_GID: Linux での UID/GID の扱い。sandbox は自動で処理するが、true でホストの UID/GID を強制、false でマッピングを無効化する

設定

gemini -s -p "analyze the code structure"
export GEMINI_SANDBOX=docker
export GEMINI_SANDBOX_IMAGE="us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"
export SANDBOX_MOUNTS="/path/on/host:/path/in/container:rw,/another/path:ro"
export SANDBOX_FLAGS="--security-opt label=disable"

{
  "tools": {
    "sandbox": {
      "command": "docker",
      "image": "us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"
    }
  }
}

{
  "security": { "toolSandboxing": false }
}

BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "run my custom build"

docker run -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /absolute/path/on/host/project:/absolute/path/on/host/project \
  -w /absolute/path/on/host/project \
  -e GEMINI_SANDBOX=docker \
  ghcr.io/google/gemini-cli:latest

制約・注意点

sandbox はリスクを減らすが、すべてを無くすわけではない
作業ができる範囲で最も制限的なプロファイルを使う
コンテナのオーバーヘッドは初回ビルド後は最小
GUI アプリケーションは sandbox 内で動かないことがある

切り分け:

「Operation not permitted」: sandbox 外へのアクセスが必要な操作。より緩いプロファイルにするかマウントポイントを足す
コマンドが無い: カスタム Dockerfile に追加する。自動の BUILD_SANDBOX ビルドは Gemini CLI をソースから実行しているときのみ使える。npm でインストールした場合はビルド済みイメージが必要。または sandbox.bashrc でインストールする
ネットワークの問題: プロファイルがネットワークを許しているか、プロキシ設定を確認する
デバッグは DEBUG=1 gemini -s -p "..."。プロジェクトの .env に DEBUG=true があっても自動除外により gemini-cli には効かない。gemini-cli 向けには .gemini/.env を使う