sandbox (サンドボックス)

コマンドがアクセスできるファイルとネットワークのドメインを利用者が設定し、その制限は Bash・PowerShell・Monitor のコマンドと、それらが起動するプロセスに適用されます。対象はシェルコマンドだけで、サンドボックスは既定ではオフです。

sandbox は、Claude が実行するシェルコマンドに対して、OS が強制する境界を設ける機能です。対象はシェルコマンドだけで、既定ではオフです。親セッションでサンドボックスが有効な場合、サブエージェント内の Bash コマンドもサンドボックス化されます。

モードは 2 つあり、どちらもファイルシステムとネットワークに同じ制限をかけます。違いは承認の扱いだけです。

• auto-allow:サンドボックス内で実行されるコマンドを、確認なしで自動承認します。
• regular permissions:サンドボックス化されていても、すべての Bash コマンドが通常の許可フローを通ります。

プラットフォームがサンドボックスに対応していない場合や、起動時の依存関係チェックが失敗した場合、既定ではサンドボックスなしでコマンドを実行します。

ファイル

• 既定では、サンドボックス化されたコマンドは一部の拒否されたディレクトリを除き、コンピューター全体を読み取れます。
• 書き込み可能なディレクトリの中でも、Claude Code が設定やコードを読み込むファイルへの書き込みは拒否します。
• kubectl・terraform・npm などが既定の書き込み可能ディレクトリの外に書き込む必要があるときは、sandbox.filesystem.allowWrite で特定のパスへのアクセスを与えます。
• sandbox.filesystem.disabled を true にすると、ネットワークの分離を残したままファイルシステムの分離を省略します。

ネットワーク

Claude Code はサンドボックスのプロキシをマシン上のサンドボックス外で動かし、HTTP_PROXY・HTTPS_PROXY・ALL_PROXY などの環境変数でコマンドをそこへ向けます。sandbox.network.deniedDomains を使うと、より広い allowedDomains のワイルドカードで許可される場合でも特定のドメインをブロックできます。

サンドボックス外での実行

• sandbox.excludedCommands に挙げたパターンに一致するコマンドは、ファイルシステムの制限もネットワークプロキシも無いサンドボックス外で実行されます。
• サンドボックス内でコマンドが失敗すると、Claude が失敗を分析し、dangerouslyDisableSandbox パラメーター付きで再実行する場合があります。サンドボックス設定で "allowUnsandboxedCommands": false にするとこの再実行を無効にでき、Claude Code は dangerouslyDisableSandbox パラメーターを無視します。
• ! の bash モードで入力したコマンドは、strict sandbox mode (sandbox.allowUnsandboxedCommands: false) が有効でも、自分のターミナルに入力したときと同じくサンドボックス外で実行されます。

sandbox.credentials は、サンドボックス化されたコマンドから守る認証情報ファイルと環境変数を宣言する設定です。環境変数をマスクすると、コマンドとそのログは実際の認証情報を持たず、リクエストの認証は通ります。

• Linux と WSL では、認証情報ファイルに mode: "mask" を指定できます。コマンドは代わりの値を入れた写し (ファイル全体、または extract の正規表現で取り出した部分) を読み、送信時にサンドボックスのプロキシが実際の値に置き換えます。macOS では、ファイルのマスキングは deny にフォールバックします。
• 構造化された環境変数向けの extract と onExtractNoMatch、JWT を考慮したマスキング (decode: "jwt" と maskClaims)、AWS SigV4 の再署名 (awsPairs/sigv4) のオプションがあります。これらは network.tlsTerminate が必要で、user・managed・--settings の設定からのみ有効です。

対象プランについては、公式のリリースノートには記載がありません。

Ubuntu/Debian では sudo apt-get install bubblewrap socat で依存パッケージを入れます。依存関係のチェックは起動時に行われるため、インストール後に Claude Code を再起動すると /sandbox が検出します。Linux/WSL では、管理設定 sandbox.bwrapPath と sandbox.socatPath で bubblewrap と socat のバイナリの場所を指定できます。VS Code では、パネルメニューまたは /sandbox で Sandbox (サンドボックス) ダイアログを開き、サンドボックスモード・非サンドボックスのフォールバック・除外コマンドを扱えます。

組織で導入する際の確認点は次のとおりです。

• 管理者は、全ユーザーにサンドボックスを必須にし、開発者がポリシーを広げるのを防ぎ、サンドボックスの通信を社内プロキシ経由にできます。
• 自社のツールで通信を検査・フィルタ・記録するために、組み込みのプロキシを同じマシン上で動かす独自のプロキシに置き換えられます。
• プロジェクト設定では、管理者が必須とするサンドボックスを広げたり無効にしたりできず、管理された拒否リストの背後のプロキシの置き換え、strict allowlist の拡張、管理された読み取り拒否の再開放もできません。
• sandbox.ripgrep は user・managed・--settings の設定からのみ有効で、プロジェクト設定からサンドボックスの ripgrep バイナリを上書きできません。
• サンドボックスの TLS の終端、独自プロキシ経由のルーティング、認証情報の注入、分離の弱化を行うサーバー管理設定は、適用前に承認が必要です。
• sandbox.allowNestedUserNamespaces は Linux でコマンドがユーザー名前空間を作れるようにする設定で、有効にするとコマンドがサンドボックスのファイル保護を回避できる状態になります。

以下は、セッションでサンドボックスを有効にして使う基本の流れです。

1. Claude Code のセッションを開始し、/sandbox コマンドを実行します。
2. Mode (モード) タブで、auto-allow か regular permissions のどちらかを選びます。
3. ビルドやテストスイートなど、コマンドの実行を Claude に依頼します。