Claude Code sandbox の使い方｜/sandbox で安全に自動実行

Claude Code の sandbox とは — /sandbox が縛る境界

sandbox は、Claude Code が実行する Bash コマンドとその子プロセスに対し、触れてよいファイルと到達してよいネットワークドメインを OS レベルで強制 する機能です。コマンド一つひとつを承認する代わりに境界をあらかじめ定義しておくため、ビルドやテストのような長い作業を、確認に中断されずに任せられます。

ポイントは「信頼」や指示文ではなく OS のセキュリティ基盤で強制する ことです。許可されたコマンドが名前以上のことをしようとしても、走っているプロセスに対して境界が効くため、モデルが何を選んだかに依存しません。仕様の一次情報は Claude Code 公式ドキュメント「Configure the sandboxed Bash tool」 にまとまっています。

sandbox を有効化する手順(/sandbox コマンド)

セッション内で次のコマンドを打つと sandbox パネルが開きます。

1. Claude Code のセッションで /sandbox を実行する。
2. Mode タブ で承認方式を選ぶ(auto-allow で自動許可、regular permissions で従来どおりプロンプト)。
3. Overrides タブ で、sandbox 下で失敗したコマンドを非 sandbox にフォールバックさせるか(allowUnsandboxedCommands)を選ぶ。
4. Config タブ で、解決済みの sandbox 設定を確認する。
5. ビルドやテストなどのコマンドを Claude に実行させ、初回の新規ドメインアクセスでプロンプトが出ることを確認する。

パネルで Mode を選ぶと、プロジェクト直下の .claude/settings.local.json(git 管理外)に書き込まれます。全プロジェクトで常用するなら、ユーザー設定 ~/.claude/settings.json の sandbox.enabled を true にします。/sandbox を開いて Dependencies タブしか出ない場合は必要パッケージが不足 しているサインです。

macOS と Linux・WSL2 のセットアップの違い

OS レベル強制の実装は環境で異なります。

• macOS: 追加インストール不要。OS 内蔵の Seatbelt フレームワークを使います。
• Linux / WSL2: 隔離を担う bubblewrap と、通信をプロキシへ中継する socat が必要です。

Ubuntu/Debian なら sudo apt-get install bubblewrap socat、Fedora なら sudo dnf install bubblewrap socat で導入します。インストール後に Claude Code を再起動すると、/sandbox の Dependencies タブで ripgrep・bubblewrap・socat・seccomp フィルターの有無を確認できます。Unix ドメインソケットの遮断を担う seccomp フィルターが無ければ、npm install -g @anthropic-ai/sandbox-runtime で補えます。

注意点として、ネイティブ Windows は非対応 で、Windows では WSL2 上の Claude Code を使います。WSL1 は bubblewrap が必要とするカーネル機能を持たないため動きません。また Ubuntu 24.04 以降は AppArmor の既定ポリシーが bubblewrap のユーザー名前空間生成を阻むことがあり、その場合は bwrap 用の AppArmor プロファイルを追加します。

ファイルシステム分離の仕組みと allowWrite 設定

既定の挙動は次のとおりです。

• 書き込み: 作業ディレクトリ(とその配下)とセッション用 temp($TMPDIR)のみ可能。~/.bashrc や /bin/ などは保護され、明示許可なしには変更できません。
• 読み取り: 一部の拒否ディレクトリを除き、原則コンピュータ全体を読めます。この既定では ~/.aws/credentials や ~/.ssh/ も読める 点に注意が必要です。

kubectl・terraform・npm などが作業ディレクトリ外へ書き込む必要がある場合は、sandbox.filesystem.allowWrite で許可します。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

逆に資格情報を守るには denyRead を使い、必要な場所だけ allowRead で再許可します。下の例はホーム全体の読み取りを止めつつ、プロジェクト直下だけ読めるようにする設定です(プロジェクトの .claude/settings.json に置くと . がプロジェクトルートに解決されます)。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

これらは OS レベルで効くため、Claude のファイルツールだけでなく、子プロセスとして起動した CLI 全体に適用されます。

ネットワーク分離の仕組みと allowedDomains 設定

ネットワーク制御は、sandbox の外で動くプロキシサーバ が担います。

• 事前許可ゼロ: 既定ではどのドメインも許可されておらず、新しいドメインへ初めてアクセスするときにプロンプトが出ます。よく使うドメインは allowedDomains に書いて事前許可します。
• 組織ロックダウン: managed settings で allowManagedDomainsOnly を立てると、非許可ドメインはプロンプトを出さずに自動遮断され、managed の allowedDomains だけが有効になります。
• カバレッジ: 制限はコマンドが生成するスクリプト・プログラム・子プロセスすべてに及びます。

重要な限界として、内蔵プロキシは要求されたホスト名でフィルタするだけで TLS を終端・検査しません。そのため github.com のような広いドメインを許可すると、ドメインフロンティングなどでデータ持ち出しの経路になり得ます。厳密に縛りたい場合は、network.httpProxyPort などで TLS を終端・検査するカスタムプロキシ を立て、その CA 証明書を sandbox 内に入れます。詳細は 公式 sandboxing ドキュメントの Security limitations を参照してください。

permission ルール・permission mode との違い

sandbox は許可の仕組みと「別レイヤー」です。

• permission ルール: どのツールを使ってよいかを、実行前に評価します。Bash・Read・Edit・WebFetch・MCP などすべてに適用されます。
• sandbox: Bash コマンドと子プロセスが、ファイル/ネットワークで何に触れられるかを 実行中のプロセスに対し OS レベルで強制 します。

さらに /sandbox は permission mode でもありません。permission mode は「そのツール呼び出しを実行するか/事前に確認するか」を決め、sandbox は「実行されたコマンドが何に触れられるか」を縛ります。sandbox の auto-allow は「境界が封じ込めているから Bash を自動許可する」もので、classifier が行動を審査する auto mode とは独立しており、両者は併用できます。なお auto-allow でも、/ やホームを対象にした rm、Bash(git push *) のような内容スコープの ask ルール、明示的な deny ルールは引き続きプロンプトや拒否が効きます。

組織で sandbox を強制する(managed settings)

全開発者に sandbox を必須化するには、MDM 管理ファイルや Claude.ai の server-managed settings 経由で sandbox キーを配ります。

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable: bubblewrap 不足などで sandbox が起動できないとき、警告して非 sandbox で続行するのではなく、Claude Code の起動自体を止めます。
• allowUnsandboxedCommands: false: 失敗コマンドを sandbox 外で再試行する dangerouslyDisableSandbox の抜け道を無効化します。

加えて、~/.aws や ~/.ssh を denyRead に入れて既定の読み取りを塞ぐこと、excludedCommands を狭く保つことが推奨されます。読み取りパスを managed の値だけに固定したいときは allowManagedReadPathsOnly を true にします。boolean キーは managed 値が優先されますが、配列キーは各スコープがマージされるため、excludedCommands の肥大化には注意します。

sandbox が守ること・守らないこと(limitations)

sandbox はリスクを下げますが、完全な隔離境界ではありません。設計上の限界を押さえておきます。

• TLS 非検査: 前述のとおり広いドメイン許可は持ち出し経路になり得ます。
• Unix ソケット経由の昇格: /var/run/docker.sock の許可は、実質ホストへのアクセスを与えてしまいます。
• 書き込み権限の昇格: $PATH 上の実行ファイルや .bashrc などへの書き込みを許すと、別コンテキストでのコード実行につながります。
• 設定ファイル保護: sandbox は全スコープの settings.json への書き込みを自動拒否し、自分のポリシーを書き換えられないようになっています。
• 対象範囲: sandbox が縛るのは Bash の子プロセスです。Read/Edit/Write は permission 系で別管理、computer use は実デスクトップ上で動きます。資格情報を子プロセスから除くには CLAUDE_CODE_SUBPROCESS_ENV_SCRUB を使います。

公式も「ファイルシステムとネットワークの両方の分離が揃って初めて有効」と明言しています。片方を緩めると、SSH 鍵の持ち出しやネットワーク奪取の穴が開くためです。

Docker・dev container との使い分け

/sandbox はプロセス内蔵の軽量な境界で、ローカル開発でコマンド承認を減らすのに向きます。一方、より強い隔離が要るときは Docker / dev container / VM が選択肢です。Docker 公式ドキュメントの Claude Code 連携 ではコンテナ内で Claude Code を動かす手順が示されています。Claude Code の同じ OS プリミティブは、プロセス全体を包む独立パッケージ @anthropic-ai/sandbox-runtime としても提供されています。

なおコンテナ内で --dangerously-skip-permissions を root で使おうとすると Linux/macOS では弾かれます。コンテナで自律実行したい場合は、非 root ユーザーで動く dev container 構成を使うのが安全です。複数の隔離方式の比較は 公式「Sandbox environments」 が詳しいので、脅威モデルに合わせて選びましょう。

よくあるトラブルと対処

• host-not-allowed エラー: CLI が特定ホストへ到達できないだけなので、プロンプトで許可すると以後は sandbox 内で動きます。
• jest が固まる: watchman が sandbox と非互換です。jest --no-watchman を使います。
• gh・gcloud・terraform が macOS で TLS 検証に失敗: Seatbelt 下で失敗することがあるため、excludedCommands に入れて外で動かします。
• docker コマンドが失敗: docker は非互換なので docker * を excludedCommands に追加します。
• コンテナ内で bubblewrap が起動しない: 非特権コンテナでは /proc を新規マウントできないため、外側コンテナが隔離を担う前提で enableWeakerNestedSandbox を true にします(セキュリティは弱まる点に留意)。

詳細な対処は 公式 sandboxing ドキュメントの Troubleshooting に網羅されています。sandbox は「許可確認を減らしつつ OS で境界を強制する」現実的な落とし所です。まずは /sandbox を auto-allow で試し、denyRead で資格情報を塞ぎ、必要なドメインだけ allowedDomains に足す——この三点から始めるのが安全な導入手順です。