sandbox.socatPathでLinux/WSL2のsocatパスを管理設定に固定する

sandbox.socatPathとは

sandbox.socatPathは、Claude CodeのサンドボックスがLinuxとWSL2で使うネットワークプロキシに対し、PATHの外にインストールしたsocatバイナリの場所を教える設定キーです。v2.1.133(2026年5月7日)でsandbox.bwrapPathとセットで追加されました。

値は絶対パスの文字列で、~/.claude/settings.jsonのような通常の設定ファイルではなくManaged(管理設定)からのみ読み込まれます。ユーザー設定・プロジェクト設定・ローカル設定でこのキーを書いても、Claude Codeは無視します。

{
  "sandbox": {
    "enabled": true,
    "socatPath": "/opt/admin/socat"
  }
}

対応プラットフォームはLinuxとWSL2のみです(macOSが対象外である理由は後述の「よくあるつまずき」を参照してください)。同じv2.1.133では、SDKが渡すmanagedSettingsを管理ポリシーの統合に含めるかを選ぶparentSettingsBehaviorも追加されています。

なぜこの設定が要るのか

Claude Codeのサンドボックスは、LinuxとWSL2ではファイルシステム分離にbubblewrap、ネットワークトラフィックをサンドボックスプロキシ経由に流す中継役にsocatを使います。通常はこの2つをPATHが通ったディレクトリにインストールしておけば、Claude Codeが自動的に見つけます。

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

インストール手順そのものはClaude Code WSL2セットアップやClaude Code Ubuntuインストールが扱っています。/sandboxパネルの依存関係タブから不足パッケージを見つけて入れる流れも、この2記事で追えます。

sandbox.socatPathが必要になるのは、その先の話です。bwrapPathの説明は、air-gapped環境(外部ネットワークから切り離された環境)に社内でベンダリングしたコピーを置く例を挙げています。socatPathも同じ場面で使います。socatがPATHの外にあると、Claude CodeはPATH検索だけではそれを見つけられません。管理者がこのキーで場所を明示すれば、PATHに依存せずサンドボックスにそのバイナリを使わせられます。

socatPathとbwrapPathは何が違うのか

sandbox.socatPathは単独ではなく、sandbox.bwrapPathとペアで導入されました。どちらもsandboxオブジェクト直下のキーで、Managed専用、Linux/WSL2限定、相対パスは捨ててPATH検索へ戻る点まで共通です。違うのは、指しているバイナリの役割です。

air-gapped環境で両方のバイナリを社内配布パスに置いている組織は、2つのキーを同時に設定します。

{
  "sandbox": {
    "enabled": true,
    "bwrapPath": "/opt/admin/bwrap",
    "socatPath": "/opt/admin/socat"
  }
}

同じ「カスタムバイナリ指定」でもスコープが違うキーがある

サンドボックスには、外部バイナリの場所を指定するキーがもう1つあります。sandbox.ripgrepです。並べると、スコープだけが違います。

sandbox.ripgrepはcommandにバイナリのパス、argsに先頭へ足す引数の配列を取るオブジェクトです。公式の用途は「プラットフォームに合わせて別ビルドのrgが要るとき」で、未設定ならClaude Codeと同じrg(ネイティブバイナリ同梱のもの)を使います。

Managed専用にしている理由について、bwrapPathの節は「ユーザー・プロジェクト・ローカルのファイルがサンドボックスを別のバイナリへ向けられないようにするため」と書いています。socatとbubblewrapはネットワーク中継とファイルシステム隔離を担うので、書き換えられると防御の前提が崩れます。

管理設定が開発者側の値を押し切る別のキーとしては、allowUnsandboxedCommandsがあります。こちらはどのファイルにも書けますが、managed settingsにfalseを書くと、開発者がdangerouslyDisableSandboxで再試行する余地のない厳格モードになります。

管理設定が複数あるとき、サーバー管理で配るとき

Managedスコープの設定は、ローカルに置くmanaged-settings.jsonのほか、MDMポリシー、サーバー管理設定(server-managed settings)、ポリシーヘルパープログラムといった経路でも配られます。socatPathでは、この経路の違いが2点で効いてきます。

1点目は、複数の管理経路が併存するときの読まれ方です。既定の"first-wins"では、ほとんどのキーは選ばれた1つの経路からだけ読まれ、選ばれなかった経路の値は無視されます。sandbox.socatPath、sandbox.bwrapPath、sandbox.ripgrepはこの例外で、どの管理経路からも読まれます。選ばれた経路が未設定でも、順位の低いMDMポリシーや管理設定ファイルの値が効くということです。

2点目は、サーバー管理設定で配ったときの承認です。この3つのキーは実行ファイルを指し、Claude Codeがそのファイルを実行するため、v2.1.232(2026年8月13日)から、対話セッションでユーザーの承認を求める対象に入っています。ユーザーが拒否するとClaude Codeは終了します。

サンドボックスはネイティブWindowsでは動かないので、failIfUnavailableを併用した設定をサーバー管理設定で全員に配ると、Windowsの端末ではClaude Codeが起動時に終了します。WindowsとLinuxが混在する組織では、OSごとにMDMや管理設定ファイルで配るか、WindowsユーザーをWSL2やコンテナへ移す選択肢があります。経路ごとの優先順位の全体像はmanaged settingsの解説にあります。

設定したあと、動いているかを確かめる

sandbox.socatPathを書いただけでは、サンドボックスが正しく起動したかは分かりません。依存関係の欠けは/sandboxパネルのDependenciesタブに出ます。このタブにはripgrep・bubblewrap・socat・seccompフィルタのうち、その環境に不足しているものが並びます。

/sandboxにSandboxing requires WSL2と出た場合は、WSL1で動いているディストリビューションです。PowerShellのwsl -l -vでバージョンを見て、WSL2へ上げるか、サンドボックスなしで使います。

試験コマンドは、必ずClaudeに実行させます。!プロンプトに自分で打ったコマンドは通常サンドボックスの外で動くため、試験になりません。Claudeが失敗したコマンドを外で再試行したいと尋ねてきたら、断ります。もしtouchが成功し、ホームディレクトリがサンドボックスの書き込み許可に入っていないなら、~/sandbox-probeを消してから/sandboxで状態を見直します。

依存関係が欠けたときに止めるか、続行するか

sandbox.enabled: trueだけを設定した状態で、依存関係が欠けていたりプラットフォームが非対応だったりすると、Claude Codeはサンドボックスなしでコマンドを実行します。この挙動を許さず起動時にエラーで止めたいときは、sandbox.failIfUnavailableをtrueにして、組織のハードゲートにします。

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "socatPath": "/opt/admin/socat"
  }
}

seccompフィルタは任意の依存関係です。Unixドメインソケットのブロックを加えるもので、無い場合はnpm install -g @anthropic-ai/sandbox-runtimeで入れます。ripgrepはネイティブのClaude Codeバイナリに同梱されているので、socatやbubblewrapのように別途入れる必要はありません。

Ubuntu 24.04以降では、既定のAppArmorポリシーがbubblewrapのユーザー名前空間作成をブロックすることがあります。sysctl kernel.apparmor_restrict_unprivileged_usernsの戻り値が1ならこの制限が有効なので、bwrap用のAppArmorプロファイルを追加します。戻り値が0、またはNo such file or directoryエラーが出る場合は、この手順自体が不要です。追加するプロファイルはbwrap自体にのみ適用され、サンドボックス内で実行するコマンドには影響しません。socatPathとは別の問題ですが、Linuxでサンドボックスが起動しないときの切り分け先になります。

開発者側の設定では緩められない他のManagedキー

socatPathやbwrapPathのように、開発者側のファイルでは書き換えられないManaged系のキーは、ほかにもあります。sandbox.filesystem.allowManagedReadPathsOnlyとsandbox.network.allowManagedDomainsOnlyは、開発者側の設定でポリシーを緩められないようにするキーです。

sandbox.filesystem.allowManagedReadPathsOnlyをtrueにすると、ファイルの読み取り許可(allowRead)は管理設定に書かれたエントリーだけが有効になります。ユーザー設定やプロジェクト設定で読み取り許可を追加しても、その追加分は無視されます。一方で読み取りを禁止するdenyReadは、すべての設定スコープからマージされます。開発者側は制限を厳しくする変更はできても、組織が閉じたパスを再び開くことはできません。

sandbox.network.allowManagedDomainsOnlyも同じ構造です。trueにすると、許可されるのは管理設定のallowedDomainsとWebFetch(domain:...)の許可ルールだけになります。開発者が追加したドメインは無視され、許可されていないドメインは確認なしで自動的にブロックされます。

allowManagedDomainsOnlyをtrueにする、またはallowUnsandboxedCommandsを管理設定でfalseにすると、サンドボックスは「管理者必須」の状態になります。その間、リポジトリの.claude/settings.jsonが書くexcludedCommandsやnetwork.allowedDomainsは、エントリーごと無視されます。enabledは自動では立たないので、別にtrueを書きます。

使い分け早見表

よくあるつまずき

• 相対パスを渡してしまう: "socatPath": "bin/socat"のような相対パスを渡すと、Claude Codeはその値を捨ててPATH検索にフォールバックします。指定するなら/opt/admin/socatのような絶対パスにします
• プロジェクトの.claude/settings.jsonに書いて反映されないと勘違いする: sandbox.socatPathはManaged専用キーです。リポジトリにチェックインした設定ファイルや~/.claude/settings.jsonに書いても反映されません
• macOSでも効くと思い込む: sandbox.socatPathはLinuxとWSL2限定の設定です。macOSはOS標準のSeatbeltフレームワークでサンドボックスを実装しており、socatとbubblewrapを使うのはLinuxとWSL2なので、このキー自体が意味を持たないと読めます
• 配布先のユーザーが承認ダイアログを拒否する: サーバー管理設定でsocatPathを配ると承認が求められ、拒否されるとClaude Codeが終了します。配布前に、承認ダイアログが出ることを利用者へ伝えておきます

まとめ

sandbox.socatPathは、socatをPATHの外へ置く組織だけが管理設定に書く設定です。サーバー管理設定で配る場合は、利用者側に承認ダイアログが出る点が運用上の論点になります。