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

Claude Code のサンドボックス化された Bash ツールがファイルシステムとネットワークの分離を提供し、より安全で自律的なエージェント実行を実現する方法について学びます。

Bash サンドボックスを使用すると、Claude はほとんどのシェルコマンドを実行できます。各コマンドの実行許可を求める代わりに、コマンドがアクセスできるファイルとネットワークドメインを定義し、オペレーティングシステムがすべての Bash コマンドとその子プロセスに対してその境界を実施します。

開始方法

サンドボックスは Claude Code に組み込まれており、macOS、Linux、WSL2 で実行されます。ネイティブ Windows はサポートされていません。Windows では、Claude Code を WSL2 ディストリビューション内で実行してください。

macOS では、インストールするものはありません。サンドボックス化は組み込みの Seatbelt フレームワークを使用します。Linux と WSL2 では、サンドボックスは 2 つのパッケージに依存しており、Linux と WSL2 をセットアップするで説明されています。まだインストールしていない場合でも、/sandbox で開始できます。そのパネルには、何が不足しているかが表示されます。

/sandbox

パネルでモードを選択すると、Claude Code はそれをプロジェクトのローカル設定 .claude/settings.local.json に保存します。これは現在のプロジェクトに適用されます。Claude Code はそこに設定を保存する際に、そのファイルをグローバル gitignore に追加します。すべてのプロジェクトでサンドボックスを有効化するには、ユーザー設定 ~/.claude/settings.json で sandbox.enabled を true に設定します。組織内のすべての開発者にサンドボックス化を実施するには、管理設定で実施を使用します。

Linux と WSL2 をセットアップする

Linux と WSL2 では、サンドボックスは 2 つのパッケージに依存しています。

• bubblewrap：ファイルシステム分離を実施する非特権サンドボックス化ツール
• socat：サンドボックスプロキシを通じてネットワークトラフィックをルーティングするために使用されるリレー

ディストリビューションのパッケージマネージャーでインストールします。

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

依存関係が不足している場合、/sandbox の Dependencies タブに、ripgrep、bubblewrap、socat、および seccomp フィルターのうち、プラットフォームで不足しているものが表示されます。Claude Code を再起動してから /sandbox を実行しても Dependencies タブが表示されない場合は、すべての依存関係が存在します。

Ripgrep はネイティブ Claude Code バイナリにバンドルされています。seccomp フィルターはオプションで、Unix ドメインソケットのブロッキングを追加します。不足している場合は、npm install -g @anthropic-ai/sandbox-runtime でインストールしてください。

必要な依存関係が不足している場合、Dependencies タブはインストールするまで唯一のタブとして表示されます。オプションの seccomp フィルターのみが不足している場合、Dependencies タブは他のタブと並んで表示されます。依存関係チェックはスタートアップ時に実行されるため、パッケージをインストール後に Claude Code を再起動して、/sandbox がそれらを検出するようにしてください。

WSL2 内を含む、環境がこの制限を実施しているかどうかを確認するには、`sysctl kernel.apparmor_restrict_unprivileged_userns` を実行します。コマンドが `0` を返す場合は、このステップをスキップしてください。`No such file or directory` エラーが表示される場合は、キーが存在しないため、このステップをスキップできます。`1` を返す場合は、`bwrap` にこの機能を付与する AppArmor プロファイルを追加します。

```bash theme={null}
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
```

プロファイルは `bwrap` 自体にのみ適用され、サンドボックス内で実行されるコマンドには適用されません。AppArmor を再度読み込んで適用します。

```bash theme={null}
sudo systemctl reload apparmor
```

サンドボックスモード

Claude Code は 2 つのサンドボックスモードを提供します。どちらでも、サンドボックスは同じファイルシステムとネットワーク制限を実施します。違いは、サンドボックス化されたコマンドが自動承認されるか、明示的な許可が必要かだけです。

自動許可モード

コマンドがサンドボックス化できる場合、Claude Code はそれをサンドボックス内で実行し、許可なしに自動的に承認します。許可されていないホストへのネットワークアクセスが必要なコマンドなど、サンドボックス化できないコマンドは、通常の許可フローにフォールバックします。そこで Claude Code は 許可ルールを確認し、それらのルールが既に許可していないコマンドについてゲートを設定します。Manual モードではプロンプトが表示されるか、自動モードでは分類器が使用されます。

自動許可モードでも、以下が適用されます。

• 明示的な 拒否ルールは常に尊重されます
• 重要なパスをターゲットにする rm または rmdir コマンドは、依然として通常の許可フローを通じます
• Bash(git push *) のようなコンテンツスコープの ask ルールは、サンドボックス化されたコマンドでも強制的にプロンプトを表示します
• 単純な Bash ask ルール、または同等の Bash(*) 形式は、サンドボックス化されて実行されるコマンドではスキップされます。通常の許可フローにフォールバックするコマンドには依然として適用されます。Plan Mode では、ルールはスキップされません。読み取り専用のものを含む、サンドボックス化されたコマンドのプロンプトを表示します。v2.1.212 より前では、スキップは Plan Mode でも適用されていました

通常の許可モード

すべての Bash コマンドは、サンドボックス化されている場合でも、通常の許可フローを通じます。これはより多くの制御を提供しますが、より多くの承認が必要です。

サンドボックス化されていない再試行エスケープハッチ

一部のコマンドはサンドボックス内でまったく実行できません。これは、それと互換性がないツール、または許可していないホストが必要なツールなどです。Claude Code はサンドボックス違反をブロックされたコマンドの結果で報告し、サンドボックスが拒否したパス またはホストを名前で指定するため、Claude はサンドボックスがブロックしたものを確認できます。タスクを失敗させたり、サンドボックス化をオフにするよう要求したりするのではなく、Claude Code には意図的なエスケープハッチが含まれています。Claude は違反を分析し、dangerouslyDisableSandbox パラメータでコマンドを再試行する可能性があります。

再試行されたコマンドはサンドボックス外で実行されるため、通常の許可フローを通じます。Manual モードでは確認プロンプトが表示されます。自動モードでは、分類器は基礎となるコマンドを評価します。permissions.blockReadsOutsideWorkingDirectories がオンの間、サンドボックス外で実行するために承認が必要な再試行はプロンプトを表示します。自動モードでもサンドボックス化されていない再試行のたびにプロンプトが表示されるようにするには、Bash(dangerouslyDisableSandbox:true) の ask ルールを追加してください。

このエスケープハッチは、サンドボックス設定で "allowUnsandboxedCommands": false を設定することで無効化できます。エスケープハッチが無効化されると、Claude Code は dangerouslyDisableSandbox パラメータを無視し、すべてのコマンドは excludedCommands にリストされていない限り、サンドボックス化されて実行される必要があります。/sandbox Overrides タブはこの設定を Strict sandbox mode として表示します。

Strict sandbox mode は Claude が実行するコマンドに適用されます。! シェルモードプロンプトで自分で入力するコマンドは、セッションが以下のいずれかでない限り、サンドボックス外で実行されます。

• バックグラウンドセッション： strict sandbox mode はシェルモードコマンドもカバーします
• CLAUDE_CODE_SUBPROCESS_ENV_SCRUB が設定された Linux セッション： すべてのコマンドがサンドボックス化され、シェルモードコマンドを含みます

v2.1.260 より前では、strict sandbox mode はすべてのセッションでシェルモードコマンドをサンドボックス化していました。

一時ディレクトリ

セッション一時ディレクトリは、デフォルトで作業ディレクトリと並んでサンドボックス内で書き込み可能です。ファイルシステム分離を無効化しない限り、Claude Code はサンドボックス化されたコマンドに対して $TMPDIR をこのディレクトリに設定するため、一時ファイルを書き込むツールは追加の設定なしで動作します。サンドボックス化されていないコマンドは、シェルの $TMPDIR を変更されずに継承するため、ファイルシステム分離がオンの間、サンドボックス化されたコマンドとサンドボックス化されていないコマンドは $TMPDIR を異なるディレクトリに解決します。2 つの間で一時ファイルを渡すには、代わりに作業ディレクトリの下に書き込んでください。

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

settings.json ファイルを通じてサンドボックス動作をカスタマイズします。完全な設定リファレンスについては Settings を参照してください。

デフォルトでは、サンドボックス化されたコマンドは現在の作業ディレクトリ、セッション一時ディレクトリ、および 追加したディレクトリ（--add-dir、/add-dir、または permissions.additionalDirectories で追加）に書き込みできます。kubectl、terraform、npm などのサブプロセスコマンドがこれらのディレクトリ外に書き込む必要がある場合、sandbox.filesystem.allowWrite を使用して特定のパスへのアクセスを付与します。

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

これらのパスは OS レベルで実施されるため、サンドボックス内で実行されるすべてのコマンド（その子プロセスを含む）がそれらを尊重します。これは、excludedCommands でツールをサンドボックスから除外するのではなく、ツールが特定の場所への書き込みアクセスを必要とする場合の推奨アプローチです。

複数の 設定スコープ で同じファイルシステム配列を定義する場合、Claude Code はそれらをマージし、1 つのスコープの配列を別のスコープの配列で置き換えるのではなく、すべてのスコープからのパスを結合します。

CLI で --setting-sources を使用するか、Agent SDK で settingSources を使用してソースを除外する場合、Claude Code はサンドボックス設定を構築するときにその sandbox.filesystem エントリ、その Edit 権限ルール、およびその Read 拒否ルールを無視します。Claude Code v2.1.246 以降が必要です。

セッション中にこれらのファイルシステムリストを編集する場合、Claude Code は 実行中のセッションに変更を適用 するため、次のサンドボックス化されたコマンドは新しいパスで実行されます。

パスプレフィックスはパスの解決方法を制御します。

この構文は Read と Edit 権限ルール とは異なります。これらは絶対パスに //path を使用し、プロジェクト相対に /path を使用します。サンドボックスファイルシステムパスは標準的な規則を使用します。/tmp/build は絶対パスです。Claude Code がこれらのパスの末尾のスラッシュまたはワイルドカードをどのように扱うかについては、Sandbox path prefixes を参照してください。

sandbox.filesystem.denyWrite と sandbox.filesystem.denyRead を使用して書き込みまたは読み取りアクセスを拒否することもでき、sandbox.filesystem.allowRead を使用して拒否された領域内の特定のパスの読み取りを再度許可できます。読み取りルールが重複する場合、より具体的なパスが優先されます。

以下の例は、ホームディレクトリ全体からの読み取りをブロックしながら、現在のプロジェクトからの読み取りを許可します。プロジェクトの .claude/settings.json に配置してください。相対パス . はプロジェクト設定に存在する場合にのみプロジェクトルートに解決されるためです。

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

同じ設定を ~/.claude/settings.json に配置した場合、. は ~/.claude に解決され、プロジェクトファイルは denyRead ルールによってブロックされたままになります。

ホームディレクトリとマウントされたボリュームからの読み取りをサンドボックス化されたコマンドに拒否しながら、作業ディレクトリを読み取り可能に保つには、パスルールを書き込む代わりに permissions.blockReadsOutsideWorkingDirectories を設定します。

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

sandbox.filesystem.disabled を true に設定して、ネットワーク分離を保持しながらファイルシステム分離をスキップします。以下の例は、ネットワークドメインの許可リストを保持しながらファイルシステム分離をオフにします。

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

サンドボックスには 2 つの独立したレイヤーがあります。ファイルシステム分離 はサンドボックス化されたコマンドが読み取りおよび書き込みできるパスを制御し、ネットワーク分離 はそれらが到達できるドメインを制御します。ファイルシステムレイヤーがオフの場合、サンドボックス化されたコマンドはホストファイルシステムへの無制限の読み取りおよび書き込みアクセスを取得しますが、そのネットワーク出力は許可されたドメインに限定されたままです。コマンドが書き込むものではなく、どこに接続するかを制御するためにサンドボックス化する場合、レイヤーをオフにします。

設定はデフォルトでオフであり、サンドボックスが実行されるプラットフォーム（macOS、Linux、WSL2）に適用されます。Claude Code v2.1.216 以降が必要です。

どの設定がそれを無効にできるか

ファイルシステム分離をオフにするとサンドボックス化されたコマンドが実行できることが拡大するため、Claude Code は filesystem.disabled をこれらの設定ソースからのみ尊重します。

• ユーザー設定、管理設定、および --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 を無視し、ファイルシステム分離をオンに保ちます。

管理された credentials.files エントリが filesystem.disabled をピンするかどうか（キーを管理設定にロックして開発者がファイルシステム分離をオフにできないようにする）は、エントリの mode とサンドボックスの開始時にエントリに何が起こるかによって異なります。

フォールバックはサンドボックスの開始時に発生し、Claude Code が既に設定を読み込んだ後にピンチェックが実行されるため、フォールバックされたエントリはピンしません。検証は設定の読み込み中に無効なエントリを deny に書き直すため、低下したエントリは deny として書いたもののようにピンします。

ファイルシステム分離がオフの場合に何が変わるか

filesystem.disabled を設定するとファイルシステムレイヤー自体が実施する保護が解除されます。他のレイヤーが実施する保護は適用され続けます。

2 つの他のことが変わります。

• サンドボックス化されたコマンドはセッション一時ディレクトリではなくシェルの $TMPDIR を継承します。すべての一時ディレクトリは書き込み可能で、Claude Code はもはやコマンドをセッション一時ディレクトリにリダイレクトしないためです。

  Linux では変数は親シェルでしばしば設定されていないため、サンドボックス化されたコマンド内で空に展開される可能性があります。Claude Code は Bash ツールガイダンスを通じて Claude に $TMPDIR に依存するのではなく mktemp -d でスクラッチディレクトリを作成するよう指示します。

• autoAllowBashIfSandboxed はまだデフォルトで true なので、サンドボックス化されたコマンドはプロンプトなしで実行され続けます。サンドボックス化されたコマンドにプロンプトを表示するには false に設定します。

認証情報を保護する

sandbox.credentials 設定は、サンドボックス化されたコマンドから保護するファイルパスと環境変数を宣言します。各エントリはファイルパスまたは環境変数と mode を指定します。専用の credentials ブロックは、認証情報ルールをグループ化し、一般的なファイルシステムルールから分離します。Claude Code v2.1.187 以降が必要です。

"mode": "deny" のエントリの場合、ファイルパスはサンドボックス内の読み取りに対して拒否されます。これは filesystem.denyRead が適用するのと同じ制限であり、環境変数は各サンドボックス化されたコマンド実行前に設定解除されます。ファイル保護はファイルシステムレイヤーの一部なので、ファイルシステム分離を無効にする 場合は適用されません。環境変数保護は依然として適用されます。

以下の例は、AWS 認証情報ファイルと SSH ディレクトリの読み取りをブロックし、サンドボックス化されたコマンドの環境から GITHUB_TOKEN と NPM_TOKEN を削除します。

{
  "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" }
      ]
    }
  }
}

環境変数エントリとファイルエントリは "mode": "mask" も受け入れます。これは 認証情報をマスクする の下で説明されています。

ファイルパスは sandbox.filesystem.* 設定と同じ プレフィックスルール に従います。

Claude Code はセッションが読み込むすべての 設定スコープ から deny エントリをマージします。deny エントリはアクセスを狭めるだけなので、任意のスコープは 1 つを追加できますが、別のスコープが追加したものを削除することはできません。

設定ソースを除外する 場合。

• プロジェクトまたはローカル設定: Claude Code はそれらの credentials エントリをまったく適用しません。Claude Code v2.1.246 以降が必要です。
• ユーザー設定: Claude Code は ~/.claude/settings.json の deny エントリを依然として適用し、その ファイル mask エントリ を制限として保持しますが、その 環境変数 mask エントリ をドロップします。

組み込みの認証情報拒否リストはないため、リストしたファイルと変数のみが制限されます。

sandbox.credentials はサンドボックス化された Bash コマンドのみに影響します。サンドボックス化に関係なくすべてのサブプロセスから認証情報を削除するには、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB を設定します。

認証情報をマスクする

マスキングは 認証情報を保護する の下の deny エントリよりも進みます。認証情報をブロックする代わりに、Claude Code はサンドボックス化されたコマンドにプレースホルダーであるセンチネルを表示し、サンドボックスプロキシ は許可したホストへのアウトバウンドリクエストで実際の値を交換します。ファイルの場合、置き換えは Linux と WSL2 の動作です。macOS はファイルをブロックします。

環境変数をマスクする

"mode": "mask" は認証情報を保護しながら、それで認証するツールが機能し続けるようにします。deny は変数を完全に削除するため、gh や npm などそれを必要とするツールも壊します。Claude Code v2.1.199 以降が必要です。

mask を使用すると、サンドボックス化されたコマンドは実際の値の代わりにセッションごとのセンチネル値を見ます。各 mask エントリは injectHosts をリストできます。これはリクエストが許可されている実際の値に到達するホストです。リクエストがそれらの 1 つに対してサンドボックスを離れるとき、サンドボックスプロキシ はセンチネルを実際の値に置き換えます。コマンドとそれがログに記録するものは実際の認証情報を保持しませんが、そのリクエストは依然として認証されます。

プロキシはリクエストコンテンツ内の認証情報を置き換えるため、それらを見る必要があります。network.tlsTerminate を設定して、プロキシが TLS 自体を終了するようにします。

それなしでは、マスキングは安全に失敗します。コマンドはセンチネルのみを見ますが、センチネルは変更されずにサーバーに到達し、認証は失敗します。Claude Code はこの設定ミスをスタートアップ時に報告します。

置き換えはリクエストコンテンツ内のヘッダーとリクエストボディをカバーします。認証情報自体ではなく認証情報から派生した署名で認証するリクエストは、プロキシで再署名する必要があります。AWS リクエストを再署名する は AWS でそれがどのように機能するかをカバーしています。

プロキシは ドメイン許可リスト が認める接続でのみ注入するため、各 injectHosts 宛先も network.allowedDomains を通じて到達可能である必要があります。

以下の例は 2 つのトークンをマスクします。GH_TOKEN は api.github.com へのリクエストでのみ置き換えられ、NPM_TOKEN は injectHosts を持たず、network.allowedDomains 内のすべてのホストへのリクエストで置き換えられます。

{
  "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" }
      ]
    }
  }
}

IPv6 宛先は 2 つのリストで異なるスペルを使用します。各リストは独自のマッチャーを持つためです。

• network.allowedDomains: ドメインリストが使用する括弧形式（"[::1]" など）。プロキシはこのリストをチェックして接続を認めます。
• injectHosts: 正規の圧縮形式での裸のアドレス（"::1" または "2001:db8::1" など）。プロキシは各エントリを接続の裸の宛先アドレスと照合し、ポートを無視するため、括弧形式、ゾーン ID、または異なる圧縮スペルはマッチしません。プロキシはそこで認証情報を注入しません。

claude doctor は injectHosts エントリに警告 Sandbox credential injectHosts entries can never match their destination でフラグを立てます。これらはそれらの宛先と決してマッチできません。このチェックには Claude Code v2.1.229 以降が必要です。

deny とは異なり、マスキングはプロキシに実際の認証情報をリストされたホストに送信することを認可するため、Claude Code はあなたまたはあなたの管理者が制御する設定からのみそれを尊重します。ユーザー設定、管理設定、および --settings CLI フラグです。Claude Code はリポジトリの .claude/settings.json または .claude/settings.local.json 内の mask エントリを無視します。これらのファイルではまた network.tlsTerminate と credentials.allowPlaintextInject を無視します。これはプロキシが暗号化されていないリクエストに認証情報を注入することを許可する設定です。ユーザー設定を除外する 場合、Claude Code は ~/.claude/settings.json の環境変数 mask エントリもドロップします。

あなたの管理者がサーバー管理設定を通じて mask エントリ、network.tlsTerminate、または credentials.allowPlaintextInject を配信する場合、それらは 承認が必要な設定 として数えられます。

同じ変数が任意のスコープで deny でリストされている場合、deny が優先されます。

マスキングはデフォルトで変数の全体値を置き換えます。これは裸のトークンに適しています。オプションのエントリフィールド（Claude Code v2.1.224 以降が必要）は構造を持つ値を処理します。

• extract: Claude Code が値全体に適用する正規表現。各マッチのグループ 1 でキャプチャされたテキストのみを置き換えるため、DATABASE_URL 接続文字列などの値を解析するツールはサンドボックス内で依然として機能します。パターンは少なくとも 1 つのキャプチャグループを含む必要があります。
• onExtractNoMatch はパターンが何もマッチしない場合に何が起こるかを制御します。
  • warn（デフォルト）は警告を出し、変数を未マスク状態で渡します
  • deny はサンドボックス内で変数を設定解除します
  • error は設定を修正するまでサンドボックスセットアップを停止します
• decode: "jwt"：JSON Web Token（JWT）を保持する変数の場合。Claude Code は値が JWT であることを検証し、それを構造的に有効な偽のトークンで置き換えるため、サンドボックス内でトークンをデコードするコードは機能し続けます。maskClaims を追加して、トークン全体を置き換える代わりに個別にマスクするトップレベルペイロードクレームをリストします。他のクレームは読み取り可能なままです。値が JWT として検証されない場合、またはリストされたクレームがマッチしない場合、Claude Code は警告を出して変数を未マスク状態で渡します。decode は extract と組み合わせることはできません。

設定リファレンスの credentials.envVars[] 行 を参照して、完全なフィールドリストを確認してください。

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

AWS リクエストはリクエストコンテンツ上に SigV4 署名を持つため、AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を一緒にマスクします。プロキシはアクセスキーのセンチネルで SigV4 リクエストを検出し、実際の値を置き換えた後にそれを再署名します。シークレットのみをマスクするとリクエストはプレースホルダーで署名されたままになり、プロキシはそれを検出できないため、AWS で失敗します。Claude Code はこのケースをスタートアップ時に警告しますが、アクセスキー ID のみがマスクされている場合は警告しません。プロキシが再署名できない検出されたリクエスト（x-amz-date ヘッダーが欠落しているなど）は、壊れた署名でサーバーに到達する代わりにプロキシエラーで失敗します。

Claude Code は、全体値をマスクする場合、従来の AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、および AWS_SESSION_TOKEN 変数を 1 つの認証情報に自動的にリンクします。AWS 認証情報が他の名前の変数に存在する場合、credentials.awsPairs で自分でグループ化します。これには Claude Code v2.1.224 以降が必要です。この例は、既に MY_KEY_ID、MY_SECRET_KEY、および MY_SESSION_TOKEN を全体値としてマスクする設定（上記の マスキング設定 のように）にペアリングを追加します。

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

各エントリは以下のルールに従います。

• accessKeyIdVar と secretAccessKeyVar はアクセスキー ID とシークレットキーを保持するマスク envVars エントリを指定します。オプションの sessionTokenVar は一時認証情報のセッショントークンを保持するエントリを指定します。設定されている場合、プロキシは再署名されたリクエストで x-amz-security-token として実際のトークンを送信します。
• 指定された各変数は、extract または decode なしで全体値をマスクする mask エントリである必要があります。
• プロキシは injectHosts にリストされたホストでリクエストを再署名します。
• ペアで従来の変数を指定すると、自動ペアリングが置き換えられます。

mask エントリのように、awsPairs はユーザー設定、管理設定、および --settings CLI フラグからのみ尊重されます。

3 つの AWS リクエスト形式はプロキシが再計算できない署名を持ちます。そのようなリクエストがマスク済みペアのプレースホルダーで署名されている場合、プロキシは壊れた署名を転送する代わりにそれを失敗させます。未マスク認証情報で署名されたリクエストは影響を受けません。credentials.sigv4 設定（Claude Code v2.1.224 以降が必要）は形式ごとにこれを緩和します。形式のキーを passthrough に設定すると、プロキシはプレースホルダー派生署名でリクエストを転送するため、呼び出しツールはプロキシエラーの代わりに AWS 独自の拒否応答を受け取ります。awsPairs のように、sigv4 はユーザー設定、管理設定、および --settings CLI フラグからのみ尊重されます。

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

ファイルエントリは "mode": "mask" も受け入れます。これには Claude Code v2.1.221 以降が必要です。サンドボックス化されたコマンドが見るものはプラットフォームに依存します。

• Linux と WSL2：サンドボックス化されたコマンドはファイルのセンチネルコピーを読み取ります。これはシークレットがプレースホルダー値で置き換えられたスタンドインであり、サンドボックスプロキシ は出力時に実際の値を置き換えます。
• macOS：サンドボックス化されたコマンドはリストされたファイルを読み取ることができません。Claude Code はセンチネルコピーを構築せず、出力時に何も置き換えないため、ファイルで認証するツールはサンドボックス内で機能しません。これは deny と同じ効果です。deny エントリとは異なり、ファイルシステム分離を無効にする 場合でも読み取りブロックは保持されます。

すべてのプラットフォームで、Claude Code は network.tlsTerminate 要件と injectHosts を マスク済み環境変数 と同じ方法で適用し、リポジトリ設定を同じ方法で無視します。ユーザー設定を除外する 場合、Claude Code は ~/.claude/settings.json のファイル mask エントリを制限として保持しますが、エントリはもはやプロキシに実際の値を置き換えることを認可しません。

以下の例は ~/.config/gh/hosts.yml に保存された GitHub トークンをマスクします。以下で説明する extract パターンは、Claude Code にファイルのどの部分がシークレットであるかを指示します。Linux と WSL2 では、ファイルを読み取るサンドボックス化されたコマンドはトークンの代わりにセンチネルを取得し、プロキシは api.github.com へのリクエストで実際のトークンを置き換えます。

{
  "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"]
        }
      ]
    }
  }
}

マスクがアクティブであることを確認するには、Claude に cat ~/.config/gh/hosts.yml をサンドボックス化されたコマンドで実行するよう依頼します。Linux と WSL2 では出力はトークンの代わりにセンチネル値を表示し、macOS では読み取りが失敗します。

Linux と WSL2 では、extract パターンは hosts.yml の残りを読み取り可能に保つものです。Claude Code は正規表現を全体ファイルに適用し、各マッチのグループ 1 でキャプチャされたテキストのみを置き換えるため、gh は依然としてその設定を解析し、トークンのみがプレースホルダーです。.netrc、JSON、YAML などのツールが解析する構造化ファイルに extract を使用します。パターンは少なくとも 1 つのキャプチャグループを含む必要があります。extract なしでは、Claude Code はファイル全体のコンテンツを 1 つのセンチネル値で置き換えます。これは単一の裸のシークレットと何も保持しないファイルに適しています。

JWT を保持するファイルの場合、extract の代わりに、または一緒に decode: "jwt" を設定します。decode には Claude Code v2.1.224 以降が必要です。Claude Code は組み込みパターンで JWT 候補を見つけるか、設定されている場合は extract パターンで見つけ、各候補が JWT であることを検証し、それを構造的に有効な偽のトークンで置き換えるため、サンドボックス内でトークンをデコードするコードは機能し続けます。maskClaims を追加して、トークン全体を置き換える代わりに、各検証済みトークン内の指定されたトップレベルペイロードクレームのみをマスクし、他のクレームは読み取り可能なままにします。候補が検証されない場合、またはリストされたクレームがマッチしない場合、以下の onExtractNoMatch フィールドが結果を支配します。これはパターンが何もマッチしない場合と同じです。

2 つのオプションフィールドはマッチング動作を改善します。両方は mode が mask で extract または decode が設定されている場合にのみ適用されます。macOS では、ファイルシステム分離がオンの場合、Claude Code は mask エントリを deny として適用してからパターンが実行されるため、これらのフィールドと以下の不一致結果は、ファイルシステム分離がオフ の場合にのみそこで有効になります。

• onExtractNoMatch はマッチングがファイル内でマスクするものを見つけない場合に何が起こるかを制御します。

  • warn（デフォルト）は警告を出し、エントリをスキップするため、サンドボックス化されたコマンドは実際のファイルを未マスク状態で読み取ることができます。デフォルトは認証情報が合法的に存在しない可能性がある場合に適しています。シークレットが存在する可能性があるがパターンが見落とす可能性がある場合は、deny を使用します
  • deny はファイルを読み取り不可にします
  • error は設定を修正するまでサンドボックスセットアップを停止します

  Claude Code は、読み取りブロックが実施されない場合は常に deny を error として扱います。ファイルシステム分離を無効にする 場合、および任意の設定ソースからの filesystem.allowRead エントリがファイルのパスを再度開く場合です。

• maskDuplicates はまた、マスク済み認証情報値の逐語的コピーを置き換えます。これは extract キャプチャまたは decode 検証済みトークンであり、マッチした範囲外で見つかります。短いまたは一般的な値は出現するすべての場所で置き換えられるため、長く高エントロピーのシークレット用に予約します。デフォルト：false。

mask は単一のファイルに適用されるため、各認証情報ファイルを個別にリストします。Claude Code は、安全にマスクできない mask エントリ、つまりディレクトリパス、グロブパターン、8 MiB より大きいファイル、または UTF-8 テキストではないファイルについては deny にフォールバックします。ディレクトリは代わりに明示的な deny エントリとして記述してください。どの設定がそれを無効にできるか の下の表は、各形式が filesystem.disabled をピンするかどうかと、ファイルシステム分離がオフの場合にどのように動作するかをカバーしています。

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

ファイルシステム分離

サンドボックス化された Bash ツールはファイルシステムアクセスを特定のディレクトリに制限します。

• デフォルトの書き込み動作：現在の作業ディレクトリとそのサブディレクトリへの読み取りおよび書き込みアクセス、--add-dir、/add-dir、または permissions.additionalDirectories で追加したディレクトリ、加えて $TMPDIR が指すセッション一時ディレクトリへのアクセス
• デフォルトの読み取り動作：特定の拒否ディレクトリを除く、コンピュータ全体への読み取りアクセス。このデフォルトは ~/.aws/credentials や ~/.ssh/ などの認証情報ファイルの読み取りを許可することに注意してください。sandbox.credentials を使用してこれらのファイルの読み取りをブロックし、シークレット環境変数の設定を解除するか、パスを denyRead に追加してください。
• ブロックされたアクセス：明示的な許可なしに作業ディレクトリ、追加されたディレクトリ、およびセッション一時ディレクトリ外のファイルを変更できません。これには ~/.bashrc などのシェル設定ファイルと /bin/ のシステムバイナリが含まれます。
• Git worktrees：作業ディレクトリがリンクされた git worktreeの場合、サンドボックスはメインリポジトリの共有 .git ディレクトリへの書き込みも許可するため、git commit などのコマンドが refs とインデックスを更新できます。そのディレクトリ内の hooks/ と config への書き込みは引き続き拒否されます。
• 設定可能：設定を通じてカスタム許可パスと拒否パスを定義します

ファイルシステム分離をスキップして、ネットワーク分離を維持するには、sandbox.filesystem.disabled を設定します。

保護されたパス

サンドボックス化されたコマンドが書き込みできるディレクトリ内でも、サンドボックスは Claude Code が設定とコードを読み込むファイルへの書き込みを拒否します。これらのファイルを編集できるコマンドは、自身に権限を付与したり、Claude Code がサンドボックス外で実行する hook または MCP サーバーを追加したりする可能性があります。権限システムには独自の保護されたパスがあり、ツールが実行される前に Claude Code が承認する内容を制御します。サンドボックスのリストは既に実行中のコマンドに適用されます。4 つのパスグループをカバーしています。

• 作業ディレクトリおよびその上のディレクトリ内：.claude 設定ファイル、.claude/skills、.claude/agents、.claude/commands、.claude/hooks ディレクトリ、.mcp.json、および Claude Code が独自に実行するファイル（.claude/workflows や .claude/scheduled_tasks.json など）
• 作業ディレクトリのみ：.bashrc や .zshrc などのシェルスタートアップファイル、.gitconfig、.vscode および .idea ディレクトリ、.git 内の hooks および config
• 作業ディレクトリをベア git リポジトリに変えるファイル：トップレベルの HEAD、objects、refs、加えて config と hooks（既に存在する場合）。config ディレクトリがプロジェクトに属する場合でも git に属する場合でも同様です。Linux および WSL2 では、サンドボックス化されたコマンドの実行中に表示されるトップレベルの HEAD ファイルまたは objects または refs ディレクトリをサンドボックスが削除します。
• ~/.claude または CLAUDE_CONFIG_DIR が指すディレクトリ内：そのほとんどのコンテンツ、加えて ~/.claude.json および .credentials.json 認証情報ストア

セッション中に保護された設定ファイルのパスにシンボリックリンクが表示される場合、サンドボックスは次のコマンドから、それが指すファイルへの書き込みも拒否します。

これらのパスの 1 つを除外する方法はありません。パスをカバーする allowWrite エントリまたは Edit 許可ルールは保護を解除しません。保護をオフにする唯一の方法は filesystem.disabled です。これはすべてのパスのファイルシステム分離をオフにします。マシンで解決されたこれらのパスのほとんどを確認するには、/sandbox を実行して Config タブを開きます。このタブは、独自の denyWrite エントリと混在して、Denied within allowed の下にそれらをリストします。

git merge または git checkout がこれらのパスの 1 つで unable to unlink old で失敗する場合は、Troubleshooting を参照してください。

ネットワーク分離

ネットワークアクセスはサンドボックス外で実行されるプロキシサーバーを通じて制御されます。

• ドメイン制限：Claude Code はデフォルトでドメインを事前に許可しません。コマンドが新しいドメインにアクセスする必要がある場合、Claude Code はプロンプトを表示するか、オートモードで分類器にリクエストを送信します。プロンプトで「はい」を選択すると、Claude Code は現在のセッションの残りの期間そのホストを許可し、同じホストへの後続の接続ではプロンプトを表示しません。「はい、今後は聞かない」を選択すると、Claude Code は WebFetch(domain:...) 許可ルールをローカル設定に保存するため、そのホストは今後のセッションで許可されたままになります。allowedDomains でドメインを事前に許可してプロンプトを完全に回避します。Claude Code は、Permission rules で説明されているように、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 はドメイン許可リストを実施してから、許可されたコネクションをそのアップストリームプロキシを通じてトンネルします。
• カスタムプロキシサポート：高度なユーザーは発信トラフィックにカスタムルールを実装できます
• 包括的なカバレッジ：制限はすべてのスクリプト、プログラム、およびコマンドによって生成されるサブプロセスに適用されます

WebFetch(domain:...) ルールでは、サンドボックスは 2 つのワイルドカード形式を尊重します。*.example.com などの先頭の *. とベアの *。ベアの * 形式には Claude Code v2.1.186 以降が必要です。WebFetch(domain:example.*) などの他の位置のワイルドカードはフェッチに一致しますが、サンドボックス化されたコマンドには効果がありません。

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

サンドボックスのドメインリストは allowedDomains、deniedDomains、およびそれらに供給する WebFetch(domain:...) ルールです。それらのいずれかで IPv6 アドレスに一致させるには、リテラルを括弧で囲んで記述します。"[::1]" はすべてのポートでそのアドレスに一致し、"[::1]:443" はポート 443 でのみ一致します。ポートを 1 から 65535 の数値として先頭のゼロなしで記述します。括弧で囲まれた形式には Claude Code v2.1.229 以降が必要です。v2.1.229 より前では、括弧で囲まれていないエントリの最後のコロンの後のテキストがポート番号の場合、Claude Code はそれを 1 つとして読み取ったため、::1:443 はポート 443 でアドレス ::1 を指定しました。

IPv6 アドレスのネットワーク承認プロンプトで「はい、今後は聞かない」を選択すると、Claude Code は WebFetch(domain:...) ルールをアドレスを括弧で囲んで保存するため、ルールは今後のセッションでアドレスに一致し続けます。

括弧で囲まれていないエントリで 2 つ以上のコロンがある場合は曖昧です。::1:443 は完全な IPv6 アドレスとアドレスの後にポートの両方です。Claude Code は、どの読み取りを意図したかを推測する代わりに、曖昧なスペルを保守的に実施します。

• 拒否リスト：Claude Code はエントリが解析するすべての読み取りを拒否するため、意図した読み取りがブロックされます。解析可能な読み取りがないエントリの場合、Claude Code は何もブロックしません。
• 許可リスト：Claude Code は記述したもの以上を許可しません。その読み取りが正常に解析される場合、曖昧なエントリをホストとポートの読み取りに書き直し、許可リストを拡大するのではなく、エントリを完全にドロップする可能性があります。

ターミナルで claude doctor を実行して、影響を受けるエントリを見つけます。Sandbox network domain entries have unreliable spellings 警告は最大 3 つを指定し、残りをカウントします。括弧で囲まれた形式で各エントリを書き直して、警告をクリアします。警告は、@、パスまたはクエリ文字、括弧内のワイルドカードなど、他の理由でスペルが信頼できないエントリも指定します。

OS レベルの実施

サンドボックス化された Bash ツールはオペレーティングシステムセキュリティプリミティブを使用します。

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

WSL1 は bubblewrap が WSL2 でのみ利用可能なカーネル機能を必要とするため、サポートされていません。

これらの同じプリミティブは、スタンドアロン @anthropic-ai/sandbox-runtime パッケージとして利用可能です。Sandbox environments ページでは、Claude Code プロセス全体をラップするための別のアプローチとしてこれについて説明しています。

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

サンドボックス化、許可ルール、および 許可モードは補完的なレイヤーです。以下のセクションでは、サンドボックスが各レイヤーとどのように相互作用するかについて説明します。

許可ルール

許可ルールとサンドボックス化は異なるものを制御します。

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

2 つのレイヤーは実施方法も異なります。Claude Code はコマンド文字列に基づいて、また自動モードでは、コマンドが安全かどうかについての別の分類器の判断に基づいて、コマンドが実行される前に許可決定を評価します。オペレーティングシステムは実行中のプロセスにサンドボックス境界を実施するため、モデルが何を実行することを選択したかに関係なく、許可されたコマンドが名前が示唆するもの以上のことを行う場合でも、それは保持されます。

ファイルシステムとネットワーク制限は、サンドボックス設定と許可ルールの両方を通じて設定されます。

サンドボックス設定と許可ルールの両方からのパスとドメインは、最終的なサンドボックス設定にマージされます。

claude-code リポジトリの examples ディレクトリには、一般的なデプロイメントシナリオ（サンドボックス固有の例を含む）のスターター設定が含まれています。これらを出発点として使用し、ニーズに合わせて調整してください。

許可モード

/sandbox は 許可モードではありません。許可モードはツール呼び出しが実行されるかどうか、および最初にプロンプトが表示されるかどうかを決定しますが、サンドボックスは Bash コマンドが実行されたら何にアクセスできるかを制限します。これらは制御対象と、1 回のアクション プロンプトを置き換えるものが異なります。

サンドボックスの 自動許可モードは 自動モードとは別です。自動許可はサンドボックス境界がそれらを含むため Bash コマンドを承認し、自動モードは分類器を使用してアクションをレビューします。2 つは独立して動作し、組み合わせることができます。無人実行の分離境界を選択するには、Sandbox environments を参照してください。一般的な許可モードとサンドボックスのペアリングと、各ペアリングを開始するフラグのテーブルについては、Common setups を参照してください。

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

管理者はすべてのユーザーにサンドボックス化を要求し、開発者がポリシーを広げるのを防ぎ、サンドボックストラフィックを企業プロキシを通じてルーティングできます。

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

すべての開発者にサンドボックスを要求するには、管理設定を通じて sandbox キーを配信します。MDM で管理されるファイルまたは Claude.ai の server-managed settingsを通じて配信します。

以下の管理設定構成はサンドボックスを有効化し、サンドボックスが初期化できない場合は Claude Code の起動を拒否し、モデルがサンドボックス外でコマンドを再試行するのを防止します。

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

enabled を超える 2 つのキーは、サンドボックスがコマンドを実行できない場合に何が起こるかを制御します。

• failIfUnavailable：Linux の bubblewrap などの不足している依存関係は、警告を表示してサンドボックス化されていない実行にフォールバックするのではなく、Claude Code の起動をブロックします
• allowUnsandboxedCommands: false：Claude Code は dangerouslyDisableSandbox エスケープハッチを無視するため、サンドボックス内で失敗するコマンドはサンドボックス外で再試行できません

それらと一緒に検討する価値のある 2 つの追加があります。サンドボックス化なしで実行する必要がある組織承認ツールについて excludedCommands を追加します。~/.aws や ~/.ssh などの認証情報ディレクトリについて sandbox.credentials エントリを追加します。また、秘密環境変数についても追加します。デフォルトの読み取りポリシーはこれらを許可します。

このサンドボックス構成は Claude が実行するコマンドをサンドボックス化します。開発者は依然として ! シェルモードプロンプトでコマンドを入力し、Claude Code の外の任意のターミナルで既に持っているのと同じアクセス権でサンドボックス外で実行できます。入力されたコマンドがサンドボックス化される場合のセッションについては、サンドボックス化されていない再試行エスケープハッチを参照してください。

サンドボックスはネイティブ Windows では実行されないため、フリートに Windows ホストが含まれている場合、この設定を macOS と Linux にスコープするか、それらのユーザーに WSL2 またはコンテナ内で Claude Code を実行させてください。

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

enabled と failIfUnavailable などのブール値キーの場合、Claude Code は管理値を使用し、開発者がローカルで設定したものを無視します。excludedCommands と allowRead などの配列キーの場合、Claude Code はセッションが読み込むすべてのスコープからエントリをマージするため、開発者はポリシーを広げるエントリを追加できます。

管理設定で allowManagedReadPathsOnly を true に設定して、管理設定からの allowRead エントリのみが尊重されるようにします。これにより、開発者は組織承認パスを超えて読み取りアクセスを広げるのを防止します。ネットワークドメインを同じ方法で管理値にロックするには、allowManagedDomainsOnlyを設定します。

管理設定が sandbox.filesystem を設定するか、"mode": "deny" を含む sandbox.credentials.files エントリをリストする場合、管理設定のみが filesystem.disabledを設定できるため、開発者は管理者がデプロイしたファイルシステム制限をオフにすることはできません。mask エントリがキーをピンするかどうかは、それがどのように解決されるかに依存します。どの設定がそれを無効にできるかの下の表は 4 つのケースをカバーしています。

excludedCommands には同等の管理のみロックダウンがないため、開発者は常にサンドボックス外で実行する追加コマンドを追加するエントリを追加できます。管理リストを狭く保ちます。

カスタムプロキシ設定

高度なネットワークセキュリティを必要とする組織の場合、カスタムプロキシを実装して以下を行うことができます。

• HTTPS トラフィックを復号化して検査する
• カスタムフィルタリングルールを適用する
• すべてのネットワークリクエストをログに記録する
• 既存のセキュリティインフラストラクチャと統合する

Claude Code をプロキシにポイントするには、サンドボックス設定でプロキシポートを設定します。

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

トラブルシューティング

一部のコマンドはサンドボックス内で失敗しますが、サンドボックス外では機能します。以下の修正は最も一般的なケースをカバーしています。

• コマンドがホスト許可なしエラーで失敗する：多くの CLI ツールは特定のホストに到達する必要があります。プロンプトが表示されたときに許可を付与すると、ホストが許可リストに追加されるため、ツールは将来サンドボックス内で実行されます。

• jest がハングまたは失敗する：watchman はサンドボックスと互換性がありません。代わりに jest --no-watchman を実行してください。

• Go ベースの CLI が macOS で TLS 検証に失敗する：gh、gcloud、terraform などのツールは Seatbelt の下で TLS 検証に失敗する可能性があります。これらのツールを excludedCommands にリストして、サンドボックス外で実行してください。httpProxyPort を MITM プロキシとカスタム CA で使用している場合は、代わりに enableWeakerNetworkIsolation を true に設定してください。

• open、osascript、またはブラウザベースの認証フローが macOS でエラー -600 で失敗する：サンドボックスはデフォルトで Apple Events をブロックします。ユーザー、管理、または CLI 設定で allowAppleEvents を true に設定して、それらを許可してください。プロジェクト設定はこのキーでは無視されます。これを有効にするとコード実行の分離が削除されます。サンドボックス化されたコマンドはユーザープロンプトなしで他のアプリケーションをサンドボックス化されていない状態で起動でき、macOS オートメーション同意プロンプト（TCC）の対象となる実行中のアプリケーションに AppleScript コマンドを送信できるためです。または、コマンドを excludedCommands に追加して、サンドボックス外で実行してください。

• docker コマンドが失敗する：docker はサンドボックスと互換性がありません。docker * を excludedCommands に追加して、サンドボックス外で実行してください。

• pbcopy、xclip、または wl-copy がクリップボードを更新しない：これらのクリップボードユーティリティはサンドボックス内からシステムクリップボードに到達できず、パイプされたテキストが到達しない場合があります。Claude の出力をクリップボードに配置するには、Claude にレスポンスで出力するよう依頼してから、/copy を実行してください。これはサンドボックス化されたコマンドではなく Claude Code プロセスからクリップボードに書き込みます。または、pbcopy *、wl-copy *、または xclip * を excludedCommands に追加して、コマンドをサンドボックス外で実行してください。

• git コマンドが unable to unlink old で失敗する：git merge、git checkout などのコマンドは、サンドボックスが書き込みを拒否するファイルを置き換える必要がある場合にこのように失敗します。そのファイルが .claude/skills などの保護されたパスの下にあるか、denyWrite エントリの 1 つの下にあるか、またはサンドボックスがコマンドに書き込みを許可するディレクトリの外にあるかどうかです。Linux と WSL2 ではエラーは Read-only file system で終わります。

  失敗後、Claude はコマンドをサンドボックス外で再実行することを提案する場合があります。その再試行を承認するか、別のターミナルで git コマンドを自分で実行してください。allowUnsandboxedCommands を false に設定している場合、Claude は再試行を提案できないため、コマンドを自分で実行してください。同じ git コマンドが頻繁に失敗する場合は、excludedCommands に追加してください。

• Bubblewrap がコンテナ内で起動に失敗する：非特権コンテナでは、bubblewrap は新しい /proc ファイルシステムをマウントできないため、サンドボックス化されたコマンドは bwrap エラー（Can't mount proc on /newroot/proc: Operation not permitted など）で失敗します。enableWeakerNestedSandbox を true に設定して、内部サンドボックスがコンテナの既存の /proc をバインドマウントするようにしてください。このオプションは、外部コンテナが既に必要な分離境界を提供する場合にのみ使用してください。新しい /proc マウントが隠すサンドボックス化されたコマンドにプロセス情報を公開するためです。

• 0 バイトの読み取り専用ファイルが .claude 設定パスに表示され、「はい、今後は聞かない」が保存されない：Linux と WSL2 では、サンドボックスはサンドボックス化されたコマンドが実行されている間に、まだ存在しないファイルに対する書き込み拒否を保持するために、そこに 0 バイトの読み取り専用プレースホルダーを作成します。サンドボックスはその後プレースホルダーを削除します。SIGKILL などによってセッションがそのクリーンアップが実行される前に強制終了された場合、プレースホルダーは残ります。後のセッションは毎回起動時にそれらを読み取り専用で再度バインドするため、プレースホルダーが残っている箇所では、権限の選択を保存するなどの設定書き込みが失敗します。

  claude doctor を実行して、残されたプレースホルダーファイルをリストアップしてください。Stale sandbox mask files left by a killed session 警告は最大 3 つの名前を表示し、残りをカウントします。そのプロジェクトで他の Claude Code セッションが実行されていない間に、rm で各ファイルを削除してください。v2.1.257 より前では、Claude Code は同じプレースホルダーを残していましたが、フラグを立てていませんでした。

• --dangerously-skip-permissions が root として失敗する：このフラグは Linux と macOS で root として実行するか sudo 経由で実行する場合にブロックされます。root アクセスと許可プロンプトなしを組み合わせるとシステム上のあらゆるファイルまたはサービスを変更できるためです。チェックは認識されたサンドボックス内で自動的にスキップされます。コンテナで自律的に実行するには、dev container 設定を使用してください。これは Claude Code を非 root ユーザーとして実行します。

制限事項

サンドボックス化はリスクを軽減しますが、完全な分離境界ではありません。ハードセキュリティ制御として依存する前に、以下の制限事項を確認してください。

セキュリティ上の制限

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

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

プラットフォームとツールの互換性

• プラットフォームサポート：macOS、Linux、WSL2 をサポートします。WSL1 とネイティブ Windows はサポートされていません。
• パフォーマンスオーバーヘッド：最小限ですが、一部のファイルシステム操作はわずかに遅くなる可能性があります。
• ツール互換性：特定のシステムアクセスパターンを必要とするツールの中には、設定調整が必要な場合や、サンドボックス外で実行する必要がある場合があります。

スコープ

サンドボックスは Bash サブプロセスを分離します。他のツールは異なる境界の下で動作します。

• 組み込みファイルツール：Read、Edit、Write はサンドボックスを通じて実行するのではなく、権限システムを直接使用します。permissionsを参照してください。
• コンピュータ使用：Claude がアプリを開いてスクリーンを制御する場合、分離された環境ではなく実際のデスクトップで実行されます。アプリごとの権限プロンプトが各アプリケーションをゲートします。CLI でのコンピュータ使用または Desktop でのコンピュータ使用を参照してください。
• 環境変数：サンドボックス化された Bash コマンドはデフォルトで親プロセス環境を継承します。そこに設定されたすべての認証情報を含みます。サンドボックス化されたコマンドの特定の変数を設定解除またはマスクするには sandbox.credentialsを使用するか、すべてのサブプロセスから認証情報を削除するには CLAUDE_CODE_SUBPROCESS_ENV_SCRUBを設定してください。
• サブエージェント：subagentsは親セッションと同じプロセスで実行され、同じサンドボックス設定を使用します。親セッションでサンドボックス化が有効な場合、サブエージェント内の Bash コマンドはサンドボックス化されます。

関連項目

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