sandbox.enabledはClaude CodeのBashコマンドを隔離する設定

sandbox.enabledは、Claude CodeがBashコマンドを実行するときにOSレベルの隔離を挟むかどうかを切り替える設定です。既定値はfalseで、素のままではBashコマンドはファイルシステムにもネットワークにも制限なく触れます。trueにすると、コマンドは書き込み範囲が絞られた領域の中で動き、外向きの通信もプロキシ越しに制御されます。オンにしたときに実際に変わる項目と、変わらずに残る項目は明確に分かれます。

sandbox.enabledは何を切り替える設定か

この設定が制御するのは、Claude Codeが呼び出す個々のBashコマンド(とその子プロセス)がOSのサンドボックス機構を通るかどうかです。対応プラットフォームはmacOS・Linux・WSL2で、sandboxオブジェクトのenabledキーをtrueにすると有効になります。

{
  "sandbox": {
    "enabled": true
  }
}

/sandboxパネルでモードを選ぶと、Claude Codeはこのキーをプロジェクト単位の.claude/settings.local.jsonへ書き込みます。全プロジェクトで既定オンにしたい場合は、~/.claude/settings.json(ユーザー設定)に同じキーを置きます。sandbox自体はfilesystem・network・credentialsという3つのサブオブジェクトを抱える親キーで、enabledはそのうち「隔離そのものをかけるか」だけを決めます。何をどこまで隔離するかは、この後の各設定が個別に絞り込みます。

オンにすると具体的に何が変わるか

sandbox.enabledをtrueにしたときの変化は、ファイルシステムとネットワークの両方に及びます。

書き込みが作業ディレクトリと一時ディレクトリに絞られる一方、読み取りは既定では引き続きコンピューター全体に及びます。ここは見落としやすい点で、サンドボックスを有効にしただけでは~/.aws/credentialsや~/.ssh/のような認証情報ファイルの読み取りが自動でブロックされるわけではありません。読み取りを狭めたい範囲はsandbox.filesystem.denyReadで個別に指定する必要があります。

権限プロンプトはむしろ減る

「サンドボックス化=制約が増えて確認も増える」と考えがちですが、実際の体感は逆方向に動くことがあります。理由はsandbox.autoAllowBashIfSandboxedという別の設定が既定でtrueだからです。隔離済みのコマンドはOS側の境界で保護されている前提で、通常の権限プロンプトを経ずに実行されます。denyルールやBash(git push *)のような内容を絞ったaskルールは引き続き効きますが、素のBashという広いaskルールはサンドボックス化されたコマンドに対してはスキップされます。

つまりsandbox.enabled単体をオンにするだけで、OSレベルの隔離という新しい防御線が増えると同時に、日々の確認プロンプトの回数は減る側に振れます。承認を都度求める運用から、境界そのもので防ぐ運用へ重心を移す設定だと捉えると位置付けが掴みやすくなります。この設計思想の背景はClaude Codeのサンドボックス設計で扱っています。

ブロックされたコマンドを隔離の外で再試行する仕組み

サンドボックスに阻まれたBashコマンドは、dangerouslyDisableSandboxパラメーターを使って隔離の外で再試行できます。既定ではsandbox.allowUnsandboxedCommandsがtrueのため、この再試行の経路自体は開いており、再試行そのものは通常の権限フローに乗るためManualモードでは確認プロンプトが挟まります。

この経路は、コマンドの拒否だけでなく、ヘルパー起動時に一過性で起きるunshare(CLONE_NEWUSER)失敗でも開きます。原因はunshare(CLONE_NEWUSER)がClaude Codeのサンドボックスで失敗する原因で扱っています。

「隔離の外へは一切逃さない」運用にしたい場合は、sandbox.allowUnsandboxedCommandsをfalseにします。こうするとClaude CodeはdangerouslyDisableSandboxパラメーターを丸ごと無視し、実行できるのは隔離済みのコマンドかsandbox.excludedCommandsに列挙したコマンドのどちらかだけになります。/sandboxパネルのOverridesタブでは、この状態は「Strict sandbox mode」と表示されます。

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

ブロック自体を許すのではなく、想定内の失敗を静かにするだけの設定としてsandbox.ignoreViolationsもあります。起動時に/etc/hostsを確認しにいくツールのように、拒否されること自体が想定内のコマンドについて、違反レポートだけを抑制できます。アクセスは引き続きブロックされたままで、減るのはClaudeや利用者に見える通知だけです。

オンにしても自動では守られないもの

sandbox.credentialsは既定で未設定で、組み込みの認証情報拒否リストは存在しません。保護されるのは自分で列挙したファイル・環境変数だけです。sandbox.enabledをtrueにしただけでAPIキーやAWS認証情報が自動で隠れるわけではないため、隠す・偽装するファイルとenvVarsは別途書く必要があります。個別の書き方はClaude Codeの認証情報マスキングをサンドボックスで設定する方法にまとめています。

ネットワーク側も既定では、sandbox.network.allowedDomainsに無いホストへの接続は「拒否」ではなく「都度の確認」に倒れます。確認なしで自動拒否に切り替えたい場合はsandbox.network.strictAllowlistをtrueにします(ユーザー設定かmanaged設定でのみ指定可能で、プロジェクト側からはオン・オフを変更できません)。組織として許可ドメインをmanaged設定の値だけに固定したいときは、sandbox.network.allowManagedDomainsOnlyを使うと開発者側が追加したドメインを無視できます。ファイルシステム分離だけを外して隔離の一部を緩めたいときはsandbox.filesystem.disabledという別キーがあり、これはsandbox.filesystem.disabledはファイルシステム分離だけ外す設定で扱っています。

Linux・WSL2で追加に必要なもの

macOSはOS標準のサンドボックス機構をそのまま使えますが、LinuxとWSL2ではbubblewrapとsocatのインストールが前提になります。この2つが無い環境でsandbox.enabled: trueを設定すると、サンドボックスは起動できません。

起動できないときの既定の挙動は「警告を出して隔離なしでコマンドを実行する」です。隔離なしでの実行自体を止めたい場合はsandbox.failIfUnavailableをあわせてtrueにします。こちらをオンにすると、サンドボックスが起動できない時点でClaude Code自体が起動時エラーで止まり、隔離されていない実行が紛れ込む余地をなくせます。組織で「サンドボックス必須」を強制するmanaged設定では、この2つを組にして配布するのが基本形です。

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

macOSでローカル開発サーバーに繋がらなくなることがある

macOSでサンドボックスをオンにすると、隔離済みのコマンドは既定でlocalhostのポートにバインドできなくなります。npm run devのような開発サーバーの起動コマンド自体は成功しても、ブラウザーから繋がらないという形でこの制限に当たります。原因がsandbox.enabledそのものだと気づきにくく、ポート番号やコマンドの引数を疑って時間を使いがちな落とし穴です。

対処はsandbox.network.allowLocalBindingをtrueにすることです。

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

このキーはmacOS専用で、LinuxとWSL2の挙動には影響しません。ローカルサーバーを起動しながら開発するワークフローでサンドボックスをオンにする場合は、enabledと同時にこのキーもセットで検討する価値があります。

設定を書く場所と優先順位

sandbox.enabledやsandbox.failIfUnavailableのようなBoolean値は、読み込まれた設定ファイルのうち最も優先順位が高いスコープの値がそのまま採用されます。個人が~/.claude/settings.jsonでオフにしていても、組織のmanaged設定でenabled: trueが指定されていれば、そちらが勝ちます。一方excludedCommandsやnetwork.allowedDomainsのような配列値は、読み込まれた全スコープの内容がマージされます。プロジェクト側で配列に追記しても、ユーザー設定やmanaged設定の値が消えるわけではありません。

複数の周辺設定を組み合わせると、次のような形になります。

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

この例は、サンドボックスをオンにしつつ隔離済みコマンドの確認プロンプトを省略し、dockerだけは隔離の外で動かし、ビルド用ディレクトリと~/.kubeへの書き込みを追加で許可し、~/.aws/credentialsの読み取りを塞ぎ、GitHubとnpmへの接続をあらかじめ許可する設定です。1つのsandboxオブジェクトの中に「隔離をどこまでかけるか」と「隔離の中で何を許すか」が同居する構造だと分かれば、個々のキーの役割も追いやすくなります。

どんな場面でオンにする価値が大きいか

同じ隔離設定でも、効き方は使い方によって変わります。

sandbox.excludedCommandsは、サンドボックス内では正しく動かないツールをコマンドパターンで指定し、そのコマンドだけ隔離の外で実行する設定です。除外しても通常の権限フローには乗るため、便宜的な抜け道ではあってもセキュリティ境界そのものを崩すわけではありません。指定はexactなコマンド・docker *のようなprefix・ワイルドカードパターンのいずれかで書け、パイプやコマンド連結を含む複合コマンドは一部が一致しただけでコマンド全体が隔離の外に出る点には注意が必要です。設定はプロジェクト単位・ユーザー単位のいずれにも書けるため、個人開発では~/.claude/settings.jsonで常時オンにし、チームではsandbox.excludedCommandsやsandbox.filesystem.allowWriteをプロジェクト設定に積み増していく運用が組みやすくなります。他のAIコーディングエージェントがサンドボックスをどう実装しているかはAIコーディングエージェントのサンドボックス実装比較で比較しています。

対応プラットフォームはmacOS・Linux・WSL2の3つで、ネイティブWindows(WSL2を介さない環境)は現時点のドキュメントの対象に含まれていません。該当環境でsandbox.failIfUnavailableまでtrueにすると、サンドボックス自体が使えないことを理由にClaude Codeの起動が止まる構成になる点は事前に把握しておく価値があります。

まとめ

sandbox.enabledは、Bashコマンドの書き込み範囲とネットワーク接続先をOSレベルで絞る設定です。オンにすると隔離が増える一方、autoAllowBashIfSandboxedが既定で効くため権限プロンプトは減る側に振れます。ただし認証情報の保護とネットワークの明示的な許可リストは別設定であり、sandbox.enabled単体では完結しません。Linux・WSL2ではbubblewrapとsocatが前提になり、macOSではallowLocalBindingを足さないとローカル開発サーバーが繋がらなくなる点も、有効化前に確認しておく価値があります。