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

sandbox.socatPathとは

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

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

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

対応プラットフォームはLinuxとWSL2のみです(macOSが対象外である理由は後述の「よくあるつまずき」を参照してください)。同じv2.1.133では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インストールが扱っており、この2記事を読めば/sandboxパネルの依存関係タブから不足パッケージを見つけて入れる流れが分かります。

sandbox.socatPathが必要になるのは、その先の話です。air-gapped環境やパッケージマネージャーを使わない社内配布物のように、socatをPATHの外の固定パス(社内ベンダリング済みのバイナリなど)に置いている組織では、Claude CodeがPATH検索だけではsocatを見つけられません。管理者がこのキーで場所を明示すれば、PATHに依存せずサンドボックスにそのバイナリを使わせられます。

挙動の仕様

• 型: 絶対パスの文字列(相対パスは無視され、PATH検索にフォールバックします)
• 既定値: 未設定。この場合Claude CodeはPATH上のsocatを探します
• スコープ: Managedのみ

sandbox.bwrapPathも同じくManaged専用です。

sandbox.bwrapPathとの組み合わせ

sandbox.socatPathは単独ではなく、sandbox.bwrapPathとペアで導入されました。役割が違う点に注意してください。

どちらもsandboxオブジェクトの直下のキーで、Linux/WSL2限定という制約も共通です。air-gapped環境で両方のバイナリを社内配布パスに置いている組織は、次のように2つのキーを同時に設定することになります。

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

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

Claude Codeのサンドボックスには、外部バイナリの場所を指定するキーがもう1つあります。sandbox.ripgrepです。役割も設計思想も異なるので、混同しないよう並べておきます。

sandbox.ripgrepはユーザー設定からでも変更できます。rg自体はネイティブのClaude Codeバイナリに同梱されているため通常は設定不要ですが、独自ビルドのrgを検証目的で使いたい場合などにこのキーで差し替えます。rgは検索結果の見え方に関わるだけのツールであるのに対し、socatPathとbwrapPathはネットワーク中継とファイルシステム隔離というサンドボックスの防御そのものを担うバイナリです。この違いが、両者のスコープが分かれている理由と考えられます。管理設定に書くと開発者側の値を上書きできるキーとしては、allowUnsandboxedCommandsもあります(こちらはどのスコープにも書けますが、managed settingsにfalseを書けば優先順位で上書きされます)。

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

socatPathやbwrapPathのようにManaged限定のキーは、ほかにもあります。sandbox.filesystem.allowManagedReadPathsOnlyとsandbox.network.allowManagedDomainsOnlyは、開発者側の設定でポリシーを緩められないようにすることを目的として公式ドキュメントに明記されているキーです。

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

sandbox.network.allowManagedDomainsOnlyも同じ構造です。trueにすると、ネットワークの許可リストは管理設定のallowedDomainsだけに固定され、開発者が.claude/settings.jsonなどで追加したドメインは無視されます。拒否ドメインのリストは、この許可リストのロックとは無関係に、常にすべてのスコープからマージされます。

配布経路はmanaged-settings.jsonだけではない

Managedスコープの設定は一般に、ローカルに置くmanaged-settings.jsonファイルだけでなく、MDMポリシー・サーバー管理設定(server-managed settings)・ポリシーヘルパープログラムといった経路でも配布されます。managed-settings.jsonはOSごとに決まった固定パスに置くファイルです。

sandbox.socatPathをCI環境やコンテナイメージに固定したい場合は、組織がこれらのうちどの経路を使っているかを先に確認してから設定します。

使い分け早見表

WSL2特有の注意点

WSL2では、サンドボックス化されたコマンドからcmd.exeやpowershell.exe、/mnt/c/配下のWindowsバイナリを起動しようとすると、WSLがUnixソケット経由でWindowsホストにその起動を委ねます。これを許可するかどうかはサンドボックスのUnixソケット設定に従いますが、そもそもこのソケットをブロックするには任意でインストールできるseccompフィルタが必要です。Linux/WSL2ではこのseccompフィルタがソケットパスを判別できないため、パスの許可リストであるsandbox.network.allowUnixSocketsは無視され(このキーはmacOS専用です)、許可するにはsandbox.network.allowAllUnixSocketsを、対象コマンドをサンドボックスの外に出すにはexcludedCommandsを使います。

WSL2のバージョン自体が要件を満たしているかは、PowerShellからwsl -l -vで確認できます。Sandboxing requires WSL2という表示が出た場合はWSL1で動いているディストリビューションなので、WSL2へアップグレードするか、サンドボックスなしでClaude Codeを実行する必要があります。

設定してもサンドボックスが起動しないとき

sandbox.socatPathを設定しても、指し先に実行できるsocatが無ければ、依存関係が欠けた状態として扱われます。sandbox.enabled: trueだけを設定した状態で依存関係が欠けている場合、Claude Codeは警告を表示してサンドボックスなしでコマンドを実行します。この挙動を許さず起動時にエラーで止めたいときは、sandbox.failIfUnavailableをtrueにして組織のハードゲートにします。

依存関係の状況は/sandboxパネルのDependenciesタブで確認できます。このタブにはripgrep・bubblewrap・socat・seccompフィルタのうち、その環境に不足しているものが一覧されます。パッケージをインストールした後はClaude Codeを再起動しないと/sandboxが検出しないため、インストール後の再起動を忘れないようにします。なおripgrepはネイティブのClaude Codeバイナリに同梱されているため、socatやbubblewrapのように別途インストールが必要になることはありません。

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

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

よくあるつまずき

• 相対パスを渡してしまう: "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にも依存しないため、このキー自体が意味を持ちません

よくある質問

sandbox.socatPathを設定すればsocat自体のインストールは不要になりますか

いいえ、なりません。このキーはClaude Codeに「どこにあるsocatを使うか」を教えるだけで、バイナリ自体の配置は別途必要です。パッケージマネージャーでインストールする通常の環境では、PATHが通っていればこのキー自体が不要になります。

まとめ

sandbox.socatPathは、LinuxとWSL2でサンドボックスのネットワークプロキシが使うsocatバイナリの場所を、PATHに頼らず管理設定で固定するキーです。sandbox.bwrapPathとともにv2.1.133で追加されたキーなので、それより古いバージョンでは利用できません。通常のパッケージインストールでPATHが通っていれば設定は不要で、air-gapped環境や社内ベンダリング済みバイナリを使う組織のような、PATH検索が効かない配布形態のときにsandbox.bwrapPathと組みで使います。設定前には、対象マシンでsocatとbubblewrapが実際に実行できる状態かを/sandboxパネルの依存関係タブで確認しておくと手戻りが減ります。