Claude Media
sandbox.failIfUnavailableでサンドボックス未起動時にClaude Codeを止める
Claude CodeTips

sandbox.failIfUnavailableでサンドボックス未起動時にClaude Codeを止める

sandbox.failIfUnavailableをtrueにすると、サンドボックスが起動できないときClaude Codeは隔離なしで動かず、起動時にエラー終了します。既定値と配り方、Windowsの扱いを解説します。

読了目安 約8分

sandbox.failIfUnavailableは「隔離できないなら動かない」を選ぶ設定

sandbox.failIfUnavailableは、sandbox.enabledがtrueなのにサンドボックスを起動できないとき、Claude Codeを起動時のエラーで終了させるBoolean設定です。起動できない理由として挙がるのは、依存パッケージの欠落とプラットフォーム非対応の2つです。

既定値はfalseです。このとき、サンドボックスが起動できなくてもClaude Codeはそのまま立ち上がり、コマンドを隔離なしで実行します。

値サンドボックスが起動できないとき
false(既定)サンドボックスが起動できないとき起動する。コマンドはサンドボックスなしで実行される
trueサンドボックスが起動できないとき起動時にエラーで終了する

「enabled: trueにしたから守られている」と思っていても、依存が欠けた端末では隔離なしで動いている可能性があります。この穴を塞ぐのが本キーです。enabledそのものの扱いはsandbox.enabledの解説にあります。

managed設定でサンドボックスを組織のゲートにする

個人の端末で手元の安全のために使うこともできますが、効果が大きいのは組織への配布です。サンドボックス設定ページのmanaged設定の例は、次の3キーを組にしています。

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

3つの役割は次のように分かれます。

役割分担

3つのキーが止めるもの

  • enabled

    サンドボックスを使うこと自体を有効にします。

  • failIfUnavailable

    起動できない端末で、隔離なしの実行へ落ちるのを止めます。

  • allowUnsandboxedCommands: false

    コマンドが失敗したとき、Claudeが隔離なしで再試行する抜け道を閉じます。

failIfUnavailableが受け持つのは「起動できなかった場合」だけです。起動後にコマンドが隔離下で失敗したときの再試行は別の仕組みなので、allowUnsandboxedCommandsで塞ぎます。抜け道の詳細はallowUnsandboxedCommandsの解説で扱っています。

managed設定の届け方は、MDMで配るファイルか、claude.aiのserver-managed settingsです。経路ごとの優先順位はmanaged settingsの組織管理ガイドにまとめています。

開発者が手元の設定で外せないか

managed設定でBooleanキーを指定すると、その値が採用され、開発者が手元で書いた値は無視されます。enabledとfailIfUnavailableはどちらもこの扱いです。配列のキーは各スコープの内容が合算されるため、開発者が項目を足せる点が違います。

リポジトリ側の.claude/settings.jsonが隔離を緩める場合にも、管理者の指定が優先される仕組みがあります。allowUnsandboxedCommandsをmanaged設定かコマンドラインの--settingsでfalseにすると、サンドボックスは「admin-required」(管理者が必須にした状態)になります。この状態では、リポジトリの設定ファイルにある次の指定が効きません。

  • enabledとfailIfUnavailableのfalse(開発者の~/.claude/settings.jsonがtrueにしているとき)
  • excludedCommandsやnetwork.allowedDomainsなど、隔離を緩める各種キー

admin-requiredの扱いはClaude Code v2.1.285以降です。v2.1.282からv2.1.284では、同じ設定でリポジトリのexcludedCommandsが無視されていました。

注意したいのは、failIfUnavailable単独ではadmin-requiredにならない点です。この状態を作るのはallowUnsandboxedCommands: falseとallowManagedDomainsOnly: trueのどちらかで、enabledは別に立てる必要があります。ゲートとして配るなら、先の3キーのセットを丸ごと配るのが素直です。

起動できない原因と先に潰すもの

trueにすると、起動できない端末がそのまま「Claude Codeが立ち上がらない端末」になります。展開前に原因の候補を潰しておくと、問い合わせが減ります。

Linux・WSL2は依存の導入が前提

LinuxとWSL2のサンドボックスはbubblewrapとsocatに依存します。Ubuntu/Debianなら次のコマンドで入ります。

sudo apt-get install bubblewrap socat

Ubuntu 24.04以降では、既定のAppArmorポリシーがbubblewrapのユーザー名前空間作成を妨げます。次のコマンドが1を返す環境では、bwrapにだけ権限を与えるAppArmorプロファイルの追加が必要です。

sysctl kernel.apparmor_restrict_unprivileged_userns

インストール手順の全体はUbuntuのインストール解説、NixOSでの権限エラーはNixOSの原因と対処を参照してください。PATHの外にバイナリを置く環境では、sandbox.socatPathで場所を指定できます。

WSLについては、wsl -l -vで見てSandboxing requires WSL2と出るなら、そのディストリビューションはWSL1です。WSL2へ移行するか、サンドボックスなしで運用することになるため、failIfUnavailableを配る前にWSL2であることを揃えます。

コンテナ内ではbwrapが失敗しうる

権限のないコンテナでは、bubblewrapが新しい/procをマウントできず、bwrapのエラーになります。回避にはenableWeakerNestedSandboxがありますが、外側のコンテナが必要な隔離をすでに提供している場合にだけ使う設定で、/procの情報がサンドボックス内のコマンドに見えるようになります。failIfUnavailableを配る組織では、この弱めるキーを管理設定側でfalseに固定するかどうかも合わせて決めることになります。

ネイティブWindowsは必ず止まる

サンドボックスはネイティブWindowsでは動きません。failIfUnavailableを配ると、Windows端末のClaude Codeは起動時に終了します。Windows端末を含む組織には、次の2案があります。

くらべる

Windows端末を含む組織の配り方

案1

OS別に配る

macOSとLinuxの端末にだけMDMや管理設定ファイルで配ります。server-managed settingsは組織の全ユーザーに適用されるため、この方法には向きません。

案2

Windowsの利用環境を移す

WindowsユーザーにWSL2かコンテナの中でClaude Codeを動かしてもらい、全員に同じ設定を配ります。

ゲートが守る範囲と守らない範囲

failIfUnavailableを含む3キーの構成が隔離するのは、Claudeが実行するコマンドです。開発者が!のシェルモードで自分で打ったコマンドは、サンドボックスの外で動きます。Claude Codeの外のターミナルと同じ権限を持つので、これは想定された境界です。

例外が2つあります。バックグラウンドセッションでは、シェルモードのコマンドもstrict sandbox modeの対象になります。LinuxでCLAUDE_CODE_SUBPROCESS_ENV_SCRUBを設定したセッションも、シェルモードを含めて全コマンドが隔離下で動きます。v2.1.260より前は、strict sandbox modeがすべてのセッションでシェルモードのコマンドを隔離していました。

サンドボックスは完全な隔離境界でもありません。許可ドメインにgithub.comのような広いホストを入れると、データ持ち出しの経路になりえます。ゲートを配ったあとは、excludedCommandsで組織が認めたツールを足し、sandbox.credentialsで~/.awsや~/.sshのような認証情報の置き場を保護する作業が残ります。既定の読み取りポリシーでは、これらは読めるためです。

個人の設定に置くとき、プロジェクトに置くとき

スコープは「どの設定ファイルでも指定可能」です。ただし、プロジェクトの設定とローカル設定には制限があり、サンドボックスが管理者必須になっていると、リポジトリ側のfalseは上で見たとおり無視されます。個人の端末で使う場合は、全プロジェクトに効かせたいなら~/.claude/settings.jsonに書きます。

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

/sandboxのパネルでモードを選ぶと、sandbox.enabledは現在のプロジェクトの.claude/settings.local.jsonへ書き込まれます。failIfUnavailableをパネルが書き込むという記載は設定リファレンスにないため、必要なら自分で追記します。/sandboxのOverridesタブには、allowUnsandboxedCommands: falseの状態がStrict sandbox modeとして表示されます。

導入前の確認手順

配布前に、パイロット端末で次の順に見ておくと安全です。

手順

failIfUnavailableを配る前の確認

  1. 1

    依存の有無を調べる

    Linux・WSL2の端末でcommand -v bwrap socatを実行し、両方のパスが返ることを確かめます。

  2. 2

    /sandboxの表示を見る

    Claude Codeの/sandboxを開きます。依存が欠けていると、Dependenciesタブだけが表示されます。

  3. 3

    効いている設定ソースを確かめる

    /statusのSetting sourcesで、Enterprise managed settingsが読み込まれているかを見ます。

  4. 4

    少数の端末から広げる

    Windows、WSL1、権限のないコンテナのように起動できない端末が混ざっていないかを、少数の端末で洗い出してから全社へ広げます。

/sandboxがSandbox settings are overridden by a higher-priority configurationと出して開かないのは、managed設定などの上位の設定がenabledなどを握っているときです。開発者は/sandboxでは変えられないため、管理者に依頼することになります。

まとめ

failIfUnavailableの既定値はfalseなので、サンドボックスを有効にしただけの端末では、依存が欠けても隔離なしで動き続けます。隔離を必須にしたい組織は、enabled・failIfUnavailable・allowUnsandboxedCommands: falseを組でmanaged設定に置き、Windowsなど非対応の端末をどう扱うかを先に決めます。個人利用では、起動に失敗するたびに気づける設定として使う選択肢があります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →