サンドボックス化された Bash ツールを設定する

​

サンドボックスが制限する内容

​

サンドボックスの外で実行されるもの

• 組み込みのファイルツールと Web ツール：Read、Edit、Write、WebFetch、WebSearch などのツールは、代わりに権限ルールに従います。denyRead エントリは Read ツールを止めず、allowedDomains は WebFetch を制限しません
• Claude Code が起動するその他のプロセス：コマンドフック、ローカルの MCP サーバー、プラグインモニター、LSP サーバー、およびステータスラインコマンドや apiKeyHelper などのヘルパーコマンドは、ユーザーの完全なアクセス権で実行されます
• mod：mod は Claude Code の内部で独自のコードを実行するため、そのファイルアクセス、ネットワークリクエスト、および $.process で起動したプログラムはサンドボックス化されません。mod がアクセスできる範囲を参照してください

• 自分で入力したコマンド：! シェルモードのプロンプトで入力したコマンドは、ほとんどのセッションでサンドボックス化されずに実行されます。入力したコマンドがサンドボックス内で実行されるセッションについては、厳格サンドボックスモードを参照してください
• 除外されたコマンド：excludedCommands に一致するコマンドは、サンドボックス化されずに実行されます
• サンドボックス外での再試行：Claude は、通常はサンドボックス内でコマンドが失敗した後に、そのコマンドをサンドボックス外で実行するよう求めることがあります

​

はじめに

• macOS：サンドボックス化には組み込みの Seatbelt フレームワークが使われるため、そのまま手順に進めます
• Linux と WSL2：サンドボックスは bubblewrap と socat に依存しています。これらについては Linux と WSL2 のセットアップで説明しています。まだインストールしていなくても、/sandbox から始められます。そのパネルに不足しているものが表示されるためです

/sandbox

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

​

コマンドがサンドボックス内で実行されることを確認する

​

Linux と WSL2 のセットアップ

• bubblewrap：ファイルシステムの分離を強制する、特権不要のサンドボックス化ツール
• socat：ネットワークトラフィックをサンドボックスプロキシ経由でルーティングするために使われるリレー

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

• Dependencies タブしか表示されない：サンドボックスは起動できません。タブに不足と表示されているものをインストールするか、Ubuntu の AppArmor 制限が報告されている場合は bubblewrap 用の AppArmor プロファイルを追加してください
• Dependencies タブが他のタブと並んで表示される：タブには、seccomp フィルターなど、不足しているオプションの項目が一覧表示されます。サンドボックスはそれがなくても起動できるため、それが追加する機能が必要な場合にのみインストールしてください

​

bubblewrap 用の AppArmor プロファイルを追加する

• Claude Code がユーザー名前空間に対する Ubuntu の AppArmor 制限を報告する
• その制限がオンになっている間に、サンドボックス化されたコマンドが bwrap: setting up uid map: Permission denied または bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted で失敗する

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

​

サンドボックスモード

​

auto-allow モード

• Bash の拒否ルールが一致する形式のコマンドは、引き続きブロックされます
• 重要なパスを対象とすると認識された rm または rmdir コマンドは、引き続き通常の権限フローを経由します
• Bash(git push *) のような内容を限定した確認ルールは、サンドボックス化されたコマンドであっても引き続きプロンプトを強制します
• 単独の Bash 確認ルール、またはそれと同等の Bash(*) 形式は、サンドボックス化されて実行されるコマンドではスキップされます。サンドボックス外で実行されるコマンドには引き続き適用されます。plan モードでは、このルールはスキップされず、読み取り専用のものも含め、サンドボックス化されたコマンドに対してもプロンプトを表示します
• Monitor ツールのコマンドは、引き続きサンドボックス内で実行されますが、自動的には承認されません。プロンプトをスキップするには、Bash(npm run *) など、そのコマンドに一致する許可ルールを追加します

• Bash(make *) は make CC=clang を承認します
• Bash(FOO=bar npm *) は FOO=bar npm test を承認します。コマンドが変数の代入で始まる場合は、その代入をルールに含めてください
• Bash(eval "ls") は eval "ls" を承認します。Bash(eval *) のようなワイルドカードルールではこのプロンプトは止まらないため、コマンド全体に一致するルールを記述してください

​

regular permissions モード

​

サンドボックス外での再試行という抜け道

• bypassPermissions モード：再試行はプロンプトなしで実行されます
• Manual モードと acceptEdits モード：「Bash command (unsandboxed)」というタイトルのプロンプトが表示されます
• auto モード：別の分類器モデルが基になるコマンドを評価します
• dontAsk モード：Claude Code は再試行を拒否します
• plan モード：計画中に Claude Code がコマンドをどのように制御するかを参照してください

• 一致する許可ルール：Bash(curl *) などの許可ルールがコマンドに一致する場合、そのルールは再試行も承認するため、コマンドはプロンプトなしでサンドボックス外で実行されます
• パラメーターに対する確認ルール：Bash の再試行時にプロンプトを表示させるには、Bash(dangerouslyDisableSandbox:true) に対する確認ルールを追加します。auto モードと bypassPermissions モードでもプロンプトが表示され、このルールは一致する許可ルールより優先されます
• permissions.blockReadsOutsideWorkingDirectories：これがオンの間にプロンプトが表示される再試行については、どのモードでも自動承認されないアクションで説明しています

​

strict sandbox モードで再試行をオフにする

• バックグラウンドセッション：strict sandbox モードはシェルモードのコマンドにも適用されます
• CLAUDE_CODE_SUBPROCESS_ENV_SCRUB が設定された Linux セッション：シェルモードのコマンドも含め、すべてのコマンドがサンドボックス化されて実行されます

​

一時ディレクトリ

​

サンドボックスを設定する

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

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

​

excludedCommands でコマンドをサンドボックスの外で実行する

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

• パターンの末尾は * にする: エントリは Bash(...) の権限ルールと同じ構文を使用し、ワイルドカードのないパターンは完全一致になります。docker は引数のない docker のみに一致します。docker * は引数の有無にかかわらず docker に一致します
• 呼び出し内のすべてのコマンドが一致する必要がある: npm ci && docker compose build は、別のエントリが npm ci をカバーしていない限り、サンドボックス化されたままです
• Claude Code は呼び出しのテキストを照合する: 内部で docker を呼び出すスクリプトや make ターゲットは一致せず、/usr/local/bin/docker も一致しません
• サンドボックス化されたままになる呼び出しがある: ファイルへのリダイレクト、cd、または $(...) のようなコマンド置換があると、呼び出し全体がサンドボックス化されたままになります。サンドボックス化されたままになるその他の呼び出しについては、リファレンスのエントリに記載されています
• git clone には相対パスが必要: 絶対パス、~ で始まるパス、または .. セグメントを含むパスを指定するクローンは、エントリの対象になりません。クローン先を作業ディレクトリ内にできる場合は、vendor/lib のような .. セグメントを含まない相対パスを使用するよう Claude に依頼してください
• エントリの保存場所が影響する場合がある: サンドボックスが管理者によって必須化されている間、Claude Code は .claude/settings.json と .claude/settings.local.json 内のエントリを無視します

• 読み取り専用コマンドと、許可ルールでカバーされているコマンドは、プロンプトなしで実行されます
• auto モードでは、その他の除外されたコマンドを分類器がレビューします
• bypassPermissions モードでは、除外されたコマンドは確認ルールに一致しない限りプロンプトなしで実行されます

​

ファイルシステム分離を無効にする

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

​

無効にできる設定

• ユーザー設定、管理設定、および --settings CLI フラグで設定できます。.claude/settings.json と .claude/settings.local.json のプロジェクト設定では設定できないため、チェックアウトしたプロジェクトがファイルシステム分離をオフにすることはできません。
• 管理設定が sandbox.filesystem を何らかの形で設定している場合、または "mode": "deny" の sandbox.credentials.files エントリを記載している場合は、管理設定のみがこのキーを設定できます。これにより、そのようなデプロイで開発者がファイルシステム分離をオフにすることを防ぎます。全員に対してオフにするには、管理設定で "disabled": true を設定します。
• CLAUDE_CODE_SUBPROCESS_ENV_SCRUB が設定されている場合、Claude Code は管理設定を含むすべてのソースからの filesystem.disabled を無視し、ファイルシステム分離をオンのまま維持します。

​

ファイルシステム分離がオフのときに変わること

• サンドボックス化されたコマンドは、ユーザーごとの一時ディレクトリではなく、シェルの $TMPDIR を継承します。すべての一時ディレクトリが書き込み可能になり、Claude Code がコマンドをユーザーごとの一時ディレクトリにリダイレクトしなくなるためです。 Linux では、親シェルでこの変数が設定されていないことがよくあります。Bash ツールのガイダンスは、$TMPDIR に頼るのではなく mktemp -d で作業用ディレクトリを作成するよう Claude に指示します。
• autoAllowBashIfSandboxed のデフォルトは引き続き true であるため、サンドボックス化されたコマンドはプロンプトなしで実行され続けます。サンドボックス化されたコマンドでプロンプトを表示するには、false に設定します。

​

認証情報を保護する

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

• プロジェクト設定またはローカル設定: Claude Code はそれらの credentials エントリをいずれも適用しません。Claude Code v2.1.246 以降が必要です。
• ユーザー設定: Claude Code は ~/.claude/settings.json 内の deny エントリを引き続き適用し、ファイルの mask エントリも制限として維持します（ただし、それらはプロキシが実際の値に置換することを認可しなくなります）が、環境変数の mask エントリは破棄します。

​

認証情報をマスクする

• TLS 終端: プロキシはリクエストの内容の中で実際の値を置換するため、その内容を参照できる必要があります。プロキシ自体が TLS を終端するように、network.tlsTerminate を設定してください。これを設定しない場合、マスキングは何も漏らさずに失敗します。コマンドにはセンチネルしか見えませんが、センチネルはそのままサーバーに届き、認証が失敗します。この設定ミスを確認するには、ターミナルで claude doctor を実行し、TLS termination is unavailable という警告がないか確認してください。
• 許可された送信先: 各 mask エントリには injectHosts（実際の値の送信先として許可されるホスト）を記載できます。プロキシはドメイン許可リストが許可する接続でのみ注入を行うため、各 injectHosts のホストは network.allowedDomains を通じても到達可能である必要があります。injectHosts のない mask エントリの場合、プロキシは network.allowedDomains 内のすべてのホストへのリクエストで実際の値に置換します。
• 信頼できる設定スコープ: マスキングはプロキシが実際の認証情報をどこかに送信することを認可するため、Claude Code は mask エントリ、network.tlsTerminate、credentials.allowPlaintextInject、awsPairs、sigv4 を、ユーザー設定、管理設定、および --settings フラグからのみ尊重します。リポジトリの .claude/settings.json や .claude/settings.local.json 内のこれらは無視されます。管理者がサーバー管理設定を通じて mask エントリ、network.tlsTerminate、または credentials.allowPlaintextInject を配布する場合、それらは承認が必要な設定として扱われます。

​

環境変数をマスクする

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

• network.allowedDomains: "[::1]" のような角括弧付きの形式
• injectHosts: "::1" のような、正規の圧縮形式による角括弧なしのアドレス

​

AWS リクエストを再署名する

​

認証情報ファイルをマスクする

• Linux と WSL2: サンドボックス化されたコマンドはファイルのセンチネルコピーを読み取り、プロキシが送信リクエストで実際の値に置換します。
• macOS: サンドボックス化されたコマンドはファイルをまったく読み取れません。Claude Code はセンチネルコピーを作成しないため、そのファイルを使って認証するツールはサンドボックス内で動作しません。これは deny と同じ効果です。ファイルシステム分離を無効にした場合でも、読み取りブロックは維持されます。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

​

サンドボックス化の仕組み

​

ファイルシステムの分離

• デフォルトの書き込み動作: 現在の作業ディレクトリとそのサブディレクトリ、--add-dir、/add-dir、または permissions.additionalDirectories で追加したディレクトリ、さらに $TMPDIR が指すユーザーごとの一時ディレクトリへの読み取りおよび書き込みアクセス
• デフォルトの読み取り動作: 特定の拒否されたディレクトリを除き、コンピューター全体への読み取りアクセス。このデフォルトでは認証情報ファイルの読み取りも許可されるため、コマンドに読み取らせたくない認証情報を保護してください。
• 読み取りブロック: permissions.blockReadsOutsideWorkingDirectories をオンにすると、サンドボックス化されたコマンドは、ブロック下のサンドボックス化されたコマンドに記載されたパスを除き、ホームディレクトリおよびユーザーファイルを保持するその他のディレクトリへの読み取りアクセスも失います。このセクションでは、ブロックのこの部分が適用されない場合についても説明しています。
• Git worktree: 作業ディレクトリがリンクされた git worktree である場合、サンドボックスはメインリポジトリの共有 .git ディレクトリへの書き込みも許可するため、git commit などのコマンドで ref やインデックスを更新できます。そのディレクトリ内の hooks/ と config への書き込みは引き続き拒否されます。

​

保護されたパス

• 作業ディレクトリとその上位のディレクトリ: .claude 設定ファイル、.claude/skills、.claude/agents、.claude/commands、.claude/hooks ディレクトリ、.mcp.json、および .claude/workflows や .claude/scheduled_tasks.json など Claude Code が自ら実行するファイル
• 作業ディレクトリのみ: .bashrc や .zshrc などのシェル起動ファイル、.gitconfig、.vscode および .idea ディレクトリ、.git 内の hooks と config
• 作業ディレクトリをベア git リポジトリに変えてしまうファイル: 最上位の HEAD、objects、refs、および HEAD ファイルまたはシンボリックリンクが隣にある場合の既存の config と hooks エントリ。config という名前のファイルは、HEAD がなくても拒否されます。後から出現した HEAD、objects、refs は削除されることがあります。Linux と WSL2 では、存在しない場合にサンドボックス化されたコマンドがそれらを作成できます。
• ~/.claude、または CLAUDE_CONFIG_DIR が指すディレクトリ内: その内容の大部分、および ~/.claude.json と .credentials.json 認証情報ストア

​

サンドボックスが HEAD、objects、refs を削除する場合

​

シンボリックリンクを経由する拒否パス

​

ネットワークの分離

• Linux と WSL2: コマンドは、ユーザーのネットワークに接続されていない別のネットワーク名前空間で実行されます
• macOS: Seatbelt サンドボックスフレームワークが、デフォルトでサンドボックスプロキシへの接続以外の接続をブロックします

• プロキシ変数を読み取るツール: curl、npm、HTTPS 経由の git などのツールは、ホストが許可されると接続できます。ポートを指定しない allowedDomains エントリは、そのホストのすべてのポートを許可します
• プロキシ変数を無視するツール: 素の ssh、ほとんどのデータベースドライバーなどのツールは、許可されたホストであっても接続できません。データベースクライアントやその他の非 HTTP ツールが許可されたホストに到達できないを参照してください
• TCP 以外のもの: UDP、QUIC 上の HTTP/3、および ping などの ICMP ツールはサンドボックスの外に出られません

• ドメイン制限: 許可ドメインは最初は空です。コマンドが新しいドメインを初めて必要とした場合の動作については、許可ドメイン外のホストで説明しています。
• 承認の選択: プロンプトで Yes を選択すると、Claude Code は現在のセッションの残りの間、そのホストを許可します。「Yes, and don’t ask again」を選択すると、Claude Code は WebFetch(domain:...) 許可ルールをローカル設定に保存するため、今後のセッションでもそのホストは許可されたままになります。サンドボックスが管理者必須の場合、Claude Code はルールをユーザー設定に保存し、すべてのプロジェクトに適用されます。
• 事前許可ドメイン: allowedDomains でドメインを事前に許可すると、プロンプトを完全に回避できます。権限ルールで説明しているように、Claude Code は WebFetch(domain:...) 許可ルールのドメインも事前に許可します。
• 厳格な許可リスト: ユーザー設定、管理設定、または CLI の --settings 設定で strictAllowlist を true に設定すると、Claude Code はプロンプトを表示する代わりに、サンドボックス化されたコマンドから許可リスト外のホストへのアクセスを拒否します。許可リストは allowedDomains と WebFetch(domain:...) 許可ルールのドメインの合計で、allowManagedDomainsOnly が設定されている場合は管理設定のエントリのみとなります。リポジトリのエントリについては、管理者必須のサンドボックスなしで適用されるロックで説明しています。Claude Code はこれをサンドボックス化されたコマンドにのみ適用します。WebFetch などのプロセス内ツールは引き続き権限ルールに従います。リポジトリの .claude/settings.json または .claude/settings.local.json で設定しても効果はありません。Claude Code v2.1.219 以降が必要です。
• 管理設定によるロックダウン: 管理設定で allowManagedDomainsOnly が設定されている場合、許可されていないドメインはプロンプトを表示せずに自動的にブロックされ、管理設定の allowedDomains と WebFetch(domain:...) 許可ルールのみが適用されます。
• 企業プロキシ: ネットワークで送信トラフィックを企業プロキシ経由にする必要がある場合は、プロキシ設定の説明に従って HTTPS_PROXY、HTTP_PROXY、NO_PROXY を設定します。バックグラウンドエージェントにも適用されるよう設定の env ブロックで設定するか、Claude Code を起動する環境で設定してください。Claude Code はドメイン許可リストを適用したうえで、許可された接続をその上流プロキシ経由でトンネリングします。http:// と https:// のプロキシ URL が使用でき、必要に応じて URL に Basic 認証を含めることもできます。

​

許可ドメイン外のホスト

​

ローカルアドレスに解決されるホスト名

​

auto モードでのコマンドごとの許可ドメイン

​

ドメインリスト内の IPv6 アドレス

• 拒否リスト: Claude Code はエントリが解釈され得るすべての読み方を拒否するため、意図した読み方がどちらであってもブロックされます。解釈可能な読み方がないエントリについては、Claude Code は何もブロックしません
• 許可リスト: Claude Code は記述された以上のものを許可しません。曖昧なエントリは、ホストとポートとしての読み方が正しく解析できる場合はその読み方に書き換え、許可リストを広げるよりはエントリを完全に破棄することがあります

​

OS レベルの適用

• macOS: サンドボックスの適用に Seatbelt を使用します
• Linux: 分離に bubblewrap を使用します
• WSL2: Linux と同じく bubblewrap を使用します

​

サンドボックスが権限と権限モードにどのように関連するか

​

権限ルール

• 権限ルールは Claude Code が使用できるツールを制御し、ツールが実行される前に評価されます。Bash、Read、Edit、WebFetch、MCP、およびその他のツールを含むすべてのツールに適用されます。ただし、deny ルールまたは ask ルールは、他のツールが残っている間はEndConversationをブロックできません。
• サンドボックス化は OS レベルの強制を提供し、シェルコマンドがファイルシステムおよびネットワークレベルでアクセスできるものを制限します。Bash、PowerShell、および Monitor ツールのコマンドとその子プロセスに適用されます。

​

権限モード

​

組織のサンドボックスを設定する

​

管理設定でサンドボックス化を実施する

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

• failIfUnavailable：プラットフォームがサンドボックスをサポートしていない場合や、起動時の依存関係チェックが失敗した場合、サンドボックス化されていない実行にフォールバックするのではなく、Claude Code は起動を拒否します
• allowUnsandboxedCommands: false：Claude Code は dangerouslyDisableSandbox エスケープハッチを無視するため、サンドボックス内でコマンドが失敗しても、Claude はそれをサンドボックス外で再試行できません

• 分離なしで実行する必要がある組織承認済みのツールについて excludedCommands を追加します。この設定により、リポジトリの設定でコマンドをサンドボックスの外に出すことができなくなるためです
• ~/.aws や ~/.ssh などの認証情報ディレクトリと、秘密の環境変数について sandbox.credentials エントリを追加します。デフォルトの読み取りポリシーではこれらが引き続き許可されるためです

• オペレーティングシステムごとに設定を配信する：MDM を通じて、または管理設定ファイルとして、macOS と Linux のマシンにのみデプロイします。サーバー管理設定はデバイスではなくメンバーに従います。
• Windows ユーザーをサポートされている環境に移行する：WSL2 またはコンテナ内で Claude Code を実行してもらいます

​

開発者がポリシーを広げるのを防ぐ

• enableWeakerNestedSandbox
• enableWeakerNetworkIsolation
• network.allowAllUnixSockets
• network.allowLocalBinding
• allowAppleEvents（リポジトリではオンにできません）
• allowNestedUserNamespaces（リポジトリではオンにできません）

​

管理者必須のサンドボックスにおけるリポジトリ設定

• allowUnsandboxedCommands が管理設定で false に設定されている場合、または管理設定で true に設定されていない限り --settings フラグで false に設定されている場合
• allowManagedDomainsOnly が管理設定で true に設定されている場合

• リポジトリのファイル内：deny エントリと autoAllowBashIfSandboxed の値。リポジトリによる変更を防ぐには、管理設定でこのキーを設定してください
• 開発者自身の設定内：表にある設定は、allowManagedDomainsOnly などの管理専用ロックの対象でない限り、~/.claude/settings.json または --settings から引き続き適用されます。excludedCommands や filesystem.allowWrite など、そのほとんどには管理専用ロックがありません

​

管理者必須のサンドボックスがなくても適用されるロック

​

カスタムプロキシ設定

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

• allowManagedDomainsOnly がオンの場合：管理設定のみ
• サンドボックスが管理者必須である場合、またはより限定的なネットワークロックが適用される場合：管理設定、--settings、およびユーザー設定
• それ以外の場合：任意の設定ファイル

​

トラブルシューティング

​

コマンドがホスト許可なしエラーで失敗する

​

jest がハングまたは失敗する

​

Go ベースの CLI が macOS で TLS 検証に失敗する

​

open、osascript、またはブラウザベースの認証フローが macOS でエラー -600 で失敗する

​

docker コマンドが失敗する

​

Chromium またはルートレス Podman が Linux のサンドボックス内で失敗する

• Chromium が No usable sandbox! で終了する
• unshare -U true が unshare: unshare failed: Operation not permitted を出力する。allowAllUnixSockets がオンの場合は、代わりに No space left on device を出力することがある
• ルートレス Podman が cannot clone: Operation not permitted を出力する、またはそれより前に自身のフォルダのいずれかで read-only file system により停止する

• Chromium または Electron の場合は、ブラウザを --no-sandbox で起動します。Claude Code のサンドボックスはそのままですが、ブラウザは独自のサンドボックスなしで Web コンテンツを実行します。
• ルートレス Podman、Buildah、またはブラウザや unshare を実行するスクリプトやテストコマンドの場合は、podman * などのパターンを sandbox.excludedCommands に追加します。一致するコマンドはユーザーの完全なアクセス権でサンドボックス外で実行され、Claude は実行前に作業ディレクトリ内のスクリプトを編集できます。パターンは Claude が実行するコマンドに一致する必要があるため、ブラウザの場合はブラウザではなくテストコマンドに一致させてください。
• Chromium や Electron 独自のサンドボックスを維持する場合、またはネストされた bubblewrap や unshare を実行する場合は、プロジェクトの .claude/settings.json ではなく ~/.claude/settings.json で sandbox.allowNestedUserNamespaces を true に設定します。Claude Code v2.1.305 以降が必要です。unshare は他の任意のプログラムを起動できるため、unshare で始まるコマンドは、どの excludedCommands パターンを指定してもサンドボックス内のままです。この設定だけではルートレス Podman や Buildah には不十分です。サンドボックスはこれらを他の方法でも停止するためです。

​

pbcopy、xclip、または wl-copy がクリップボードを更新しない

​

git コマンドが unable to unlink old で失敗する

• .claude/skills などの保護されたパスの下
• denyWrite エントリの 1 つの下
• サンドボックスがコマンドに書き込みを許可するディレクトリの外

​

git コマンドが Unable to create '…/index.lock' で失敗する

​

objects または refs という名前のフォルダがコマンドの後に消える

​

Bubblewrap がコンテナ内で起動に失敗する

​

Ubuntu の AppArmor 制限により bubblewrap が停止する

• Claude Code が /usr/bin/bwrap を実行する場合は、bubblewrap 用の AppArmor プロファイルを追加します
• シェルで sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 を実行します。これにより、マシン上のすべてのプログラムに対して制限が解除され、再起動するまで有効です

​

サンドボックス化されたコマンドが bwrap: setting up uid map: Permission denied で失敗する

• kernel.apparmor_restrict_unprivileged_userns = 1：制限がオンになっています。Claude Code が /usr/bin/bwrap を実行する場合は AppArmor プロファイルを追加するか、sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 を実行します。これにより、再起動するまですべてのプログラムに対して制限が解除されます。その後、Claude Code を再起動し、サンドボックスが機能することを確認してください
• その他の出力：この制限は原因ではありません。失敗を報告するには、Claude Code のプロンプトで /feedback を実行してください

​

0 バイトの読み取り専用ファイルが .claude 設定パスに表示され、「はい、今後は聞かない」が保存されない

• SIGKILL などによって、そのクリーンアップが実行される前にセッションが強制終了された場合
• バックグラウンドコマンドなど、サンドボックス化されたコマンドがまだ実行中の間にセッションが終了した場合

​

サンドボックスがオンの状態で SSH 経由の git が失敗する

• ホストがポート 22 で許可されている："git.example.com" のようにポートを指定しない allowedDomains エントリで対象になります
• 企業プロキシがポート 22 を許可している：ネットワークでアップストリームプロキシが必要な場合、トンネルもそれを経由します
• 鍵がファイルとして読み取り可能である：サンドボックスは ssh-agent ソケットをブロックする場合があり、~/.ssh に対する denyRead または credentials エントリは鍵ファイルを隠します

git remote set-url origin https://git.example.com/example-org/example-repo.git

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

​

データベースクライアントやその他の非 HTTP ツールが許可されたホストに到達できない

• macOS：Operation not permitted、または Could not resolve host などの名前解決エラー
• Linux と WSL2：Network is unreachable、または Temporary failure in name resolution などの名前解決エラー

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

​

コマンドが localhost 上のサーバーに到達できない

• macOS：network.allowLocalBinding を true に設定します。これにより、サンドボックス化されたコマンドはネットワークポートでリッスンし、localhost の任意のポートに接続できるようになります。これには、そこでリッスンしている他のすべてのサービスが含まれます。その結果、認証を必要としない localhost サービス（デバッガーなど）がサンドボックス外でコマンドの代わりに動作できるようになり、非ループバックアドレスでリッスンするコマンドは他のマシンからの接続を受け入れます
• Linux と WSL2：サンドボックス化されたコマンドの localhost はそのコマンド専用です。コマンドはポートでリッスンでき、自身が起動したサーバーに到達できます。localhost または 127.0.0.1 への直接接続はホスト上のサーバーには到達せず、allowLocalBinding は効果がありません。ホストのサーバーを必要とするコマンドは、excludedCommands でサンドボックス外で実行してください。そこではファイルシステムやネットワークの制限はありません。サンドボックスプロキシを経由する接続については、ローカルアドレスに解決されるホスト名を参照してください

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

​

許可されたホスト名が resolved to a loopback address で拒否される

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

​

コマンドが Sandbox is required で拒否される

• Sandbox is required but failed to initialize: <reason>：Claude Code は起動しましたが、その後サンドボックスの初期化に失敗しました。メッセージに示された手順（Restart to retry. または Fix the sandbox settings to retry）に従ってください。
• Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>：Linux または WSL2 で、サンドボックスは起動しましたが、その後 Claude Code が依存関係の不足を検出しました。理由に示された問題を修正し（不足している依存関係のインストールなど）、Claude Code を再起動してください。

• 除外されたコマンド：excludedCommands エントリに一致するコマンドは、引き続きサンドボックス外で実行されます。そのようなコマンドが作業ディレクトリ外の filesystem.allowWrite パスに書き込む場合、その書き込みは通常の権限フローを経由します。管理者必須のサンドボックスの下では、Claude Code はリポジトリの設定からのエントリを無視します
• ! シェルモードのプロンプトで入力したコマンド：引き続きサンドボックス外で実行されます。バックグラウンドセッションでは、これらも拒否されます
• サンドボックス外での再試行：Claude Code はサンドボックス外での再試行の dangerouslyDisableSandbox パラメータを無視します

​

/sandbox が Sandbox settings are overridden by a higher-priority configuration で失敗する

• Command line arguments：--settings を指定して Claude Code を起動した場合は、渡したファイルまたは JSON がこれらのキーのいずれかを設定しているか確認してください。設定している場合は、そこで値を変更するか、これらのキーを含めずに Claude Code を再起動してください。
• Enterprise managed settings：組織の管理設定が読み込まれています。それらがこれらのキーのいずれかを設定している場合、そのキーは /sandbox からも、ユーザーが管理するどの設定ファイルからも変更できないため、管理者に問い合わせてください。

​

/sandbox が Sandbox settings not changed を出力する

✗ Sandbox settings not changed: /home/you/project/.claude/settings.local.json couldn't be updated (EACCES). Start Claude Code in a project folder you can write to.

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

​

制限事項

​

セキュリティ上の制限

• ネットワークフィルタリング：サンドボックスは、プロセスが接続できるドメインを制限します。デフォルトでは、組み込みプロキシは発信トラフィックの TLS を終端または検査しないため、暗号化された接続の内容は検査されません。実験的な network.tlsTerminate 設定は、mask 認証情報置換のためにプロキシで TLS を終了しますが、コンテンツフィルタリングは追加しません。ポリシーで許可されるのは信頼できるドメインのみであることを確認する責任があります。

• Unix ソケットを通じた権限昇格：allowUnixSockets 設定は、サンドボックスバイパスにつながる可能性のあるシステムサービスへのアクセスを不注意に付与する可能性があります。たとえば、/var/run/docker.sock へのアクセスを許可すると、Docker ソケットを通じてホストシステムへのアクセスが効果的に付与されます。サンドボックスを通じて許可する Unix ソケットを慎重に検討してください。
• ファイルシステム権限昇格：過度に広いファイルシステム書き込み権限は権限昇格攻撃を有効にする可能性があります。$PATH の実行可能ファイルを含むディレクトリ、システム設定ディレクトリ、またはユーザーシェル設定ファイル（.bashrc または .zshrc）への書き込みを許可すると、他のユーザーまたはシステムプロセスがこれらのファイルにアクセスするときに異なるセキュリティコンテキストでコード実行につながる可能性があります。
• Linux サンドボックス強度：Linux 実装は強力なファイルシステムとネットワーク分離を提供しますが、特権付き名前空間のない Docker 環境内で動作できるようにする enableWeakerNestedSandbox モードが含まれています。このオプションはセキュリティを大幅に弱め、追加の分離が別の方法で実施される場合にのみ使用する必要があります。
• macOS での Apple Events：macOS サンドボックスはデフォルトで Apple Events をブロックします。allowAppleEvents 設定はこの制限を解除して、open や osascript などのツールが動作するようにしますが、コード実行分離を削除します。サンドボックス化されたコマンドは、ユーザープロンプトなしで他のアプリケーションをサンドボックス化されていない状態で起動でき、実行中のアプリケーションに AppleScript コマンドを送信できます。これはアプリごとの macOS オートメーション同意プロンプト（TCC）の対象です。これはユーザー、管理、または CLI 設定からのみ有効です。プロジェクト設定では有効にできません。
• macOS での Mach および XPC サービス：サンドボックス化されたコマンドは、network.allowMachLookup に列挙した各サービスにサンドボックスの外へ出てアクセスでき、それらのサービスがそのコマンドのために行う処理はサンドボックスによって制限されません。
• Linux および WSL2 でのユーザー名前空間：デフォルトでは、サンドボックス化されたコマンドはユーザー名前空間を作成できません。allowNestedUserNamespaces を true に設定すると、セキュリティ境界をオフにすることになり、サンドボックス化されたコマンドのコードがサンドボックス外で実行される可能性があります。この設定をオンにする前に、Linux のサンドボックス内で Chromium または rootless Podman が失敗するの警告を確認してください。

​

スコープ

• コンピュータ使用：Claude がアプリを開いてスクリーンを制御する場合、分離された環境ではなく実際のデスクトップで実行されます。アプリごとの権限プロンプトが各アプリケーションをゲートします。CLI でのコンピュータ使用または Desktop でのコンピュータ使用を参照してください。
• サブエージェント：subagentsは親セッションと同じプロセスで実行され、同じサンドボックス設定を使用します。親セッションでサンドボックス化が有効な場合、サブエージェント内の Bash コマンドはサンドボックス化されます。
• バックグラウンドセッション：バックグラウンドセッションは独自のプロセスで実行され、その設定でサンドボックス化が有効になっている場合、その Bash コマンドはサンドボックス化されます。
• プロセス全体を囲む境界：サンドボックス外で実行されるものに記載されたプロセスも境界の内側に置くには、承認したホストに限定したネットワーク許可リストを指定して sandbox runtime 内で Claude Code（ローカルモード）を実行するか、ファイアウォールスクリプトを備えた dev container 内で実行します。バックグラウンドサービスとそれがホストするセッションについては、企業ランチャーの背後で Claude Code を実行するを参照してください。
• Mod：mod は Claude Code 内で独自のコードを実行するプラグインであり、mod が起動するプロセスはサンドボックス外で実行されます。mod がアクセスできる範囲を参照してください。

​

関連項目

• Sandbox environments：組み込みサンドボックスと dev コンテナ、コンテナ、VM を比較する
• Security：セキュリティ機能とベストプラクティス
• Permissions：許可設定とアクセス制御
• All settings：すべての設定キー
• CLI reference：コマンドラインオプション