サンドボックス化された 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/settings.local.json に書き込まれます。これは現在のプロジェクトに適用され、git にチェックインされません。すべてのプロジェクトでサンドボックスを有効化するには、ユーザー設定 ~/.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 フィルターがプラットフォームで利用可能かどうかが表示されます。Ripgrep はネイティブ Claude Code バイナリにバンドルされています。seccomp フィルターはオプションで、Unix ドメインソケットのブロッキングを追加します。不足している場合は、npm install -g @anthropic-ai/sandbox-runtime でインストールしてください。

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

WSL2 内を含む、環境がこの制限を実施しているかどうかを確認するには、`sysctl kernel.apparmor_restrict_unprivileged_userns` を実行します。キーが存在しないか 0 を返す場合は、このステップをスキップしてください。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 つのサンドボックスモードを提供します。

自動許可モード：Bash コマンドはサンドボックス内で実行を試みられ、許可なしに自動的に許可されます。サンドボックス化できないコマンド（許可されていないホストへのネットワークアクセスが必要なコマンドなど）は、通常の許可フローにフォールバックします。そこで Claude Code は 許可ルールを確認し、それらのルールが既に許可していないコマンドについてプロンプトを表示します。

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

• 明示的な 拒否ルールは常に尊重されます
• /、ホームディレクトリ、または他の重要なシステムパスをターゲットにする rm または rmdir コマンドは、依然として許可プロンプトをトリガーします
• コンテンツスコープの ask ルール（Bash(git push *) など）は、サンドボックス化されたコマンドでも強制的にプロンプトを表示します
• 単純な Bash ask ルール、または同等の Bash(*) 形式は、サンドボックス化されて実行されるコマンドではスキップされます。通常の許可フローにフォールバックするコマンドには依然として適用されます

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

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

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

一部のコマンドはサンドボックス内でまったく実行できません。これは、それと互換性がないツール、または許可していないホストが必要なツールなどです。タスクを失敗させたり、サンドボックス化をオフにするよう要求したりするのではなく、Claude Code には意図的なエスケープハッチが含まれています。サンドボックス制限のためにコマンドが失敗した場合、Claude は失敗を分析し、dangerouslyDisableSandbox パラメータでコマンドを再試行する可能性があります。再試行されたコマンドはサンドボックス外で実行されるため、通常の許可フローを通じて実行され、承認が必要です。

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

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

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

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

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

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

同じファイルシステム配列が複数の 設定スコープ で定義されている場合、配列はマージされます。すべてのスコープからのパスが結合され、置き換えられません。

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

この構文は Read と Edit 許可ルール とは異なります。これらは絶対パスに //path を使用し、プロジェクト相対に /path を使用します。サンドボックスファイルシステムパスは標準的な規則を使用します。/tmp/build は絶対パスです。

sandbox.filesystem.denyWrite と sandbox.filesystem.denyRead を使用して書き込みまたは読み取りアクセスを拒否することもでき、sandbox.filesystem.allowRead を使用して拒否された領域内の特定のパスの読み取りを再度許可できます。

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

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

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

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

ファイルシステム分離

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

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

sandbox.filesystem.allowWrite を設定で使用して、追加のパスへの書き込みアクセスを付与できます。これらの制限は OS レベルで実施されるため、Claude のファイルツールだけでなく、kubectl、terraform、npm などのツールを含むすべてのサブプロセスコマンドに適用されます。

ネットワーク分離

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

• ドメイン制限：事前に許可されたドメインはありません。コマンドが新しいドメインにアクセスする必要がある場合、Claude Code はプロンプトを表示します。allowedDomainsでドメインを事前に許可してプロンプトを回避します。
• 管理ロックダウン：allowManagedDomainsOnlyが管理設定で設定されている場合、許可されていないドメインはプロンプトの代わりに自動的にブロックされ、管理設定からの allowedDomains のみが尊重されます。
• カスタムプロキシサポート：高度なユーザーは発信トラフィックにカスタムルールを実装できます
• 包括的なカバレッジ：制限はすべてのスクリプト、プログラム、およびコマンドによって生成されるサブプロセスに適用されます

OS レベルの実施

サンドボックス化された Bash ツールは OS セキュリティプリミティブを活用します。

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

WSL1 は bubblewrap が WSL2 でのみ利用可能なカーネル機能を必要とするため、サポートされていません。これらの OS レベルの制限により、Claude Code のコマンドによって生成されたすべての子プロセスが同じセキュリティ境界を継承することが保証されます。

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

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

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

許可ルール

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

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

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

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

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

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

許可モード

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

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

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

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

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

すべての開発者にサンドボックスを要求するには、管理設定を通じて 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：dangerouslyDisableSandbox エスケープハッチは無視されるため、サンドボックス内で失敗するコマンドはサンドボックス外で再試行できません

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

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

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

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

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

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 に設定してください。
• docker コマンドが失敗する：docker はサンドボックスと互換性がありません。docker * を excludedCommands に追加して、サンドボックス外で実行してください。
• Bubblewrap がコンテナ内で起動に失敗する：非特権コンテナでは、bubblewrap は新しい /proc ファイルシステムをマウントできません。enableWeakerNestedSandbox を true に設定して、内部サンドボックスがコンテナの既存の /proc をバインドマウントするようにしてください。このオプションは、外部コンテナが既に必要な分離境界を提供する場合にのみ使用してください。新しい /proc マウントが隠すサンドボックス化されたコマンドにプロセス情報を公開するためです。
• Linux の Seccomp フィルター：seccomp フィルターは Unix ドメインソケットをブロックするために必要です。/sandbox の Dependencies タブに、それが利用可能かどうかが表示されます。不足している場合は、npm install -g @anthropic-ai/sandbox-runtime を実行してヘルパーをインストールしてください。
• --dangerously-skip-permissions が root として失敗する：このフラグは Linux と macOS で root として実行するか sudo 経由で実行する場合にブロックされます。root アクセスと許可プロンプトなしを組み合わせるとシステム上のあらゆるファイルまたはサービスを変更できるためです。チェックは認識されたサンドボックス内で自動的にスキップされます。コンテナで自律的に実行するには、dev container 設定を使用してください。これは Claude Code を非 root ユーザーとして実行します。

制限事項

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

セキュリティ上の制限

• ネットワークフィルタリング：ネットワークフィルタリングシステムは、プロセスが接続を許可されるドメインを制限することで動作します。組み込みプロキシは発信トラフィックを終了または TLS 検査を実行しないため、暗号化された接続の内容は検査されません。許可リストに含まれるドメインのみが信頼できることを確認する責任があります。

• Unix ソケットを通じた権限昇格：allowUnixSockets 設定は、サンドボックスバイパスにつながる可能性のある強力なシステムサービスへのアクセスを不注意に付与する可能性があります。たとえば、/var/run/docker.sock へのアクセスを許可すると、Docker ソケットを通じてホストシステムへのアクセスが効果的に付与されます。サンドボックスを通じて許可する Unix ソケットを慎重に検討してください。
• ファイルシステム許可昇格：過度に広いファイルシステム書き込み許可は権限昇格攻撃を有効にする可能性があります。$PATH の実行可能ファイルを含むディレクトリ、システム設定ディレクトリ、またはユーザーシェル設定ファイル（.bashrc または .zshrc）への書き込みを許可すると、他のユーザーまたはシステムプロセスがこれらのファイルにアクセスするときに異なるセキュリティコンテキストでコード実行につながる可能性があります。
• Linux サンドボックス強度：Linux 実装は強力なファイルシステムとネットワーク分離を提供しますが、特権のない名前空間なしで Docker 環境内で動作できるようにする enableWeakerNestedSandbox モードが含まれています。このオプションはセキュリティを大幅に弱め、追加の分離が別の方法で実施される場合にのみ使用する必要があります。
• 設定ファイルが保護されている：サンドボックスは自動的に Claude Code の settings.json ファイルのすべてのスコープと管理設定ディレクトリへの書き込みアクセスを拒否するため、サンドボックス化されたコマンドは独自のポリシーを変更できません。

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

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

スコープ

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

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

関連項目

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