サンドボックス - Claude Code Docs

概要

Claude Code はネイティブサンドボックス機能を備えており、エージェント実行のためのより安全な環境を提供しながら、継続的な許可プロンプトの必要性を軽減します。各 bash コマンドの実行許可を求める代わりに、サンドボックス化により事前に定義された境界が作成され、Claude Code はリスクを軽減しながらより自由に動作できます。サンドボックス化された bash ツールは OS レベルのプリミティブを使用して、ファイルシステムとネットワークの両方の分離を実施します。

サンドボックス化が重要な理由

従来の許可ベースのセキュリティでは、bash コマンドごとに継続的なユーザー承認が必要です。これは制御を提供しますが、以下の問題につながる可能性があります。

承認疲れ：「承認」を繰り返しクリックすると、ユーザーが承認内容に注意を払わなくなる可能性があります
生産性の低下：継続的な中断により開発ワークフローが遅くなります
自律性の制限：Claude Code は承認を待つ際に効率的に動作できません

サンドボックス化はこれらの課題に以下の方法で対処します。

明確な境界を定義：Claude Code がアクセスできるディレクトリとネットワークホストを正確に指定します
許可プロンプトを削減：サンドボックス内の安全なコマンドは承認を必要としません
セキュリティを維持：サンドボックス外のリソースへのアクセス試行は即座に通知をトリガーします
自律性を有効化：Claude Code は定義された制限内でより独立して実行できます

効果的なサンドボックス化には、ファイルシステムとネットワークの両方の分離が必要です。ネットワーク分離がない場合、侵害されたエージェントは SSH キーなどの機密ファイルを流出させる可能性があります。ファイルシステム分離がない場合、侵害されたエージェントはシステムリソースにバックドアを仕掛けてネットワークアクセスを取得する可能性があります。サンドボックス化を設定する際は、設定がこれらのシステムのバイパスを作成しないことを確認することが重要です。

仕組み

ファイルシステム分離

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

デフォルトの書き込み動作：現在の作業ディレクトリとそのサブディレクトリへの読み取りおよび書き込みアクセス
デフォルトの読み取り動作：特定の拒否ディレクトリを除く、コンピュータ全体への読み取りアクセス
ブロックされたアクセス：明示的な許可なしに現在の作業ディレクトリ外のファイルを変更できません
設定可能：設定を通じてカスタム許可パスと拒否パスを定義します

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

ネットワーク分離

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

ドメイン制限：承認されたドメインのみにアクセスできます
ユーザー確認：新しいドメインリクエストは許可プロンプトをトリガーします（allowManagedDomainsOnly が有効な場合を除き、許可されていないドメインを自動的にブロックします）
カスタムプロキシサポート：高度なユーザーは発信トラフィックにカスタムルールを実装できます
包括的なカバレッジ：制限はすべてのスクリプト、プログラム、およびコマンドによって生成されるサブプロセスに適用されます

OS レベルの実施

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

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

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

開始方法

前提条件

macOS では、サンドボックス化は組み込みの Seatbelt フレームワークを使用してすぐに動作します。 Linux と WSL2 では、まず必要なパッケージをインストールします。

Ubuntu/Debian
Fedora

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

サンドボックス化を有効化

/sandbox コマンドを実行してサンドボックス化を有効化できます。

/sandbox

これはサンドボックスモードを選択できるメニューを開きます。必要な依存関係（Linux の bubblewrap や socat など）が不足している場合、メニューはプラットフォームのインストール手順を表示します。デフォルトでは、サンドボックスが起動できない場合（依存関係の不足、サポートされていないプラットフォーム、またはプラットフォーム制限）、Claude Code は警告を表示してサンドボックス化なしでコマンドを実行します。これをハード失敗にするには、sandbox.failIfUnavailable を true に設定します。これは、セキュリティゲートとしてサンドボックス化を必要とする管理デプロイメント向けです。

サンドボックスモード

Claude Code は 2 つのサンドボックスモードを提供します。 自動許可モード：Bash コマンドはサンドボックス内で実行を試みられ、許可なしに自動的に許可されます。サンドボックス化できないコマンド（許可されていないホストへのネットワークアクセスが必要なコマンドなど）は通常の許可フローにフォールバックします。明示的な拒否ルールは常に尊重されます。Ask ルールは通常の許可フローにフォールバックするコマンドにのみ適用されます。 通常の許可モード：すべての bash コマンドは、サンドボックス化されている場合でも標準的な許可フローを通じます。これはより多くの制御を提供しますが、より多くの承認が必要です。両方のモードで、サンドボックスは同じファイルシステムとネットワーク制限を実施します。違いは、サンドボックス化されたコマンドが自動承認されるか明示的な許可が必要かだけです。

自動許可モードは許可モード設定とは独立して動作します。「編集を受け入れる」モードでない場合でも、自動許可が有効な場合、サンドボックス化された bash コマンドは自動的に実行されます。これは、ファイル編集ツールが通常は承認を必要とする場合でも、サンドボックス境界内のファイルを変更する bash コマンドはプロンプトなしに実行されることを意味します。

サンドボックス化を設定

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

特定のパスへのサブプロセス書き込みアクセスの付与

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

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

これらのパスは OS レベルで実施されるため、サンドボックス内で実行されるすべてのコマンド（その子プロセスを含む）がそれらを尊重します。これは、excludedCommands でツールをサンドボックスから除外するのではなく、ツールが特定の場所への書き込みアクセスを必要とする場合の推奨アプローチです。 allowWrite（または denyWrite/denyRead/allowRead）が複数の設定スコープで定義されている場合、配列はマージされます。つまり、すべてのスコープからのパスが結合され、置き換えられません。たとえば、管理設定が /opt/company-tools への書き込みを許可し、ユーザーが個人設定で ~/.kube を追加する場合、両方のパスが最終的なサンドボックス設定に含まれます。これは、ユーザーとプロジェクトが、より高い優先度のスコープで設定されたパスを複製または上書きすることなく、リストを拡張できることを意味します。パスプレフィックスはパスの解決方法を制御します。

プレフィックス	意味	例
`/`	ファイルシステムルートからの絶対パス	`/tmp/build` は `/tmp/build` のままです
`~/`	ホームディレクトリからの相対パス	`~/.kube` は `$HOME/.kube` になります
`./` またはプレフィックスなし	プロジェクト設定の場合はプロジェクトルートからの相対パス、または `~/.claude` のユーザー設定からの相対パス	`.claude/settings.json` の `./output` は `<project-root>/output` に解決されます

古い //path プレフィックスは絶対パスの場合でも機能します。以前に単一スラッシュ /path を使用してプロジェクト相対解決を期待していた場合は、./path に切り替えてください。この構文は Read と Edit 許可ルールとは異なります。これらは絶対パスに //path を使用し、プロジェクト相対に /path を使用します。サンドボックスファイルシステムパスは標準的な規則を使用します。/tmp/build は絶対パスです。 sandbox.filesystem.denyWrite と sandbox.filesystem.denyRead を使用して書き込みまたは読み取りアクセスを拒否することもできます。これらは Edit(...) と Read(...) 許可ルールからのパスとマージされます。拒否された領域内の特定のパスの読み取りを再度許可するには、sandbox.filesystem.allowRead を使用します。これは denyRead より優先されます。管理設定で allowManagedReadPathsOnly が有効な場合、管理 allowRead エントリのみが尊重されます。ユーザー、プロジェクト、ローカルの allowRead エントリは無視されます。denyRead はすべてのソースからマージされます。たとえば、ホームディレクトリ全体からの読み取りをブロックしながら、現在のプロジェクトからの読み取りを許可するには、プロジェクトの .claude/settings.json に以下を追加します。

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

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

すべてのコマンドがサンドボックス化と互換性があるわけではありません。サンドボックスを最大限に活用するのに役立つ可能性のあるいくつかのメモ：

多くの CLI ツールは特定のホストへのアクセスを必要とします。これらのツールを使用すると、特定のホストへのアクセス許可をリクエストします。許可を付与すると、これらのホストに今後アクセスでき、サンドボックス内で安全に実行できるようになります。
watchman はサンドボックス内での実行と互換性がありません。jest を実行している場合は、jest --no-watchman の使用を検討してください
docker はサンドボックス内での実行と互換性がありません。excludedCommands で docker * を指定して、サンドボックス外で実行するように強制することを検討してください。

Claude Code には、必要に応じてコマンドをサンドボックス外で実行できるようにする意図的なエスケープハッチメカニズムが含まれています。コマンドがサンドボックス制限（ネットワーク接続の問題や互換性のないツールなど）により失敗した場合、Claude は失敗を分析するよう促され、dangerouslyDisableSandbox パラメータでコマンドを再試行する可能性があります。このパラメータを使用するコマンドは、実行するユーザー許可を必要とする通常の Claude Code 許可フローを通じます。これにより、Claude Code は特定のツールまたはネットワーク操作がサンドボックス制約内で機能できないエッジケースを処理できます。このエスケープハッチは、サンドボックス設定で "allowUnsandboxedCommands": false を設定することで無効化できます。無効化されると、dangerouslyDisableSandbox パラメータは完全に無視され、すべてのコマンドはサンドボックス化されるか、excludedCommands に明示的にリストされている必要があります。

セキュリティ上の利点

プロンプトインジェクションからの保護

攻撃者がプロンプトインジェクションを通じて Claude Code の動作を正常に操作した場合でも、サンドボックスはシステムのセキュリティを確保します。 ファイルシステム保護：

~/.bashrc などの重要な設定ファイルを変更できません
/bin/ のシステムレベルファイルを変更できません
Claude 許可設定で拒否されたファイルを読み取ることができません

ネットワーク保護：

攻撃者が制御するサーバーへのデータ流出はできません
許可されていないドメインから悪意のあるスクリプトをダウンロードできません
承認されていないサービスへの予期しない API 呼び出しを行うことができません
明示的に許可されていないドメインに連絡することはできません

監視と制御：

サンドボックス外のすべてのアクセス試行は OS レベルでブロックされます
境界がテストされるときに即座に通知を受け取ります
リクエストを拒否、1 回だけ許可、または設定を永続的に更新することを選択できます

攻撃面の削減

サンドボックス化は以下からの潜在的な損害を制限します。

悪意のある依存関係：有害なコードを含む NPM パッケージまたは他の依存関係
侵害されたスクリプト：セキュリティ脆弱性を持つビルドスクリプトまたはツール
ソーシャルエンジニアリング：ユーザーに危険なコマンドを実行させるための攻撃
プロンプトインジェクション：Claude に危険なコマンドを実行させるための攻撃

透過的な操作

Claude Code がサンドボックス外のネットワークリソースにアクセスしようとする場合：

操作は OS レベルでブロックされます
即座に通知を受け取ります
以下を選択できます。
- リクエストを拒否する
- 1 回だけ許可する
- サンドボックス設定を永続的に更新して許可する

セキュリティ上の制限

ネットワークサンドボックス化の制限：ネットワークフィルタリングシステムは、プロセスが接続を許可されるドメインを制限することで動作します。プロキシを通じて渡されるトラフィックを検査することはなく、ユーザーはポリシーで許可されたドメインが信頼できるドメインのみであることを確認する責任があります。

ユーザーは、データ流出を許可する可能性のある github.com などの広いドメインを許可することに伴う潜在的なリスクに注意する必要があります。また、場合によってはドメインフロンティングを通じてネットワークフィルタリングをバイパスすることが可能な場合があります。

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

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

サンドボックス化と許可は、一緒に動作する補完的なセキュリティレイヤーです。

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

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

sandbox.filesystem.allowWrite を使用して、作業ディレクトリ外のパスへのサブプロセス書き込みアクセスを付与します
sandbox.filesystem.denyWrite と sandbox.filesystem.denyRead を使用して、特定のパスへのサブプロセスアクセスをブロックします
sandbox.filesystem.allowRead を使用して、denyRead 領域内の特定のパスの読み取りを再度許可します
Read と Edit 拒否ルールを使用して、特定のファイルまたはディレクトリへのアクセスをブロックします
WebFetch 許可/拒否ルールを使用してドメインアクセスを制御します
サンドボックス allowedDomains を使用して、Bash コマンドが到達できるドメインを制御します
サンドボックス deniedDomains を使用して、より広い allowedDomains ワイルドカードが許可する場合でも、特定のドメインをブロックします

sandbox.filesystem 設定と許可ルールからのパスは、最終的なサンドボックス設定にマージされます。このリポジトリには、一般的なデプロイメントシナリオ（サンドボックス固有の例を含む）のスターター設定が含まれています。これらを出発点として使用し、ニーズに合わせて調整してください。

高度な使用方法

カスタムプロキシ設定

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

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

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

既存のセキュリティツールとの統合

サンドボックス化された bash ツールは以下と連携します。

許可ルール：許可設定と組み合わせて多層防御を実現します
開発コンテナ：devcontainers と共に使用して追加の分離を実現します
エンタープライズポリシー：管理設定を通じてサンドボックス設定を実施します

ベストプラクティス

制限的に開始：最小限の許可で開始し、必要に応じて拡張します
ログを監視：サンドボックス違反の試みを確認して、Claude Code のニーズを理解します
環境固有の設定を使用：開発環境と本番環境で異なるサンドボックスルールを使用します
許可と組み合わせる：包括的なセキュリティのためにサンドボックス化を IAM ポリシーと共に使用します
設定をテスト：サンドボックス設定が正当なワークフローをブロックしないことを確認します

オープンソース

サンドボックスランタイムは、独自のエージェントプロジェクトで使用するためのオープンソース npm パッケージとして利用可能です。これにより、より広い AI エージェントコミュニティがより安全で安全な自律システムを構築できます。これは、サンドボックス化したい他のプログラムをサンドボックス化するためにも使用できます。たとえば、MCP サーバーをサンドボックス化するには、以下を実行できます。

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

実装の詳細とソースコードについては、GitHub リポジトリを参照してください。

制限事項

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

サンドボックス化がカバーしていないもの

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

組み込みファイルツール：Read、Edit、Write はサンドボックスを通じて実行するのではなく、許可システムを直接使用します。許可を参照してください。
コンピュータ使用：Claude が macOS でアプリを開いてスクリーンを制御する場合、分離された環境ではなく実際のデスクトップで実行されます。アプリごとの許可プロンプトが各アプリケーションをゲートします。CLI でのコンピュータ使用または Desktop でのコンピュータ使用を参照してください。

設定

​概要

​サンドボックス化が重要な理由

​仕組み

​ファイルシステム分離

​ネットワーク分離

​OS レベルの実施

​開始方法

​前提条件

​サンドボックス化を有効化

​サンドボックスモード

​サンドボックス化を設定

​特定のパスへのサブプロセス書き込みアクセスの付与

​セキュリティ上の利点

​プロンプトインジェクションからの保護

​攻撃面の削減

​透過的な操作

​セキュリティ上の制限

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

​高度な使用方法

​カスタムプロキシ設定

​既存のセキュリティツールとの統合

​ベストプラクティス

​オープンソース

​制限事項

​サンドボックス化がカバーしていないもの

​関連項目

概要

サンドボックス化が重要な理由

仕組み

ファイルシステム分離

ネットワーク分離

OS レベルの実施

開始方法

前提条件

サンドボックス化を有効化

サンドボックスモード

サンドボックス化を設定

特定のパスへのサブプロセス書き込みアクセスの付与

セキュリティ上の利点

プロンプトインジェクションからの保護

攻撃面の削減

透過的な操作

セキュリティ上の制限

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

高度な使用方法

カスタムプロキシ設定

既存のセキュリティツールとの統合

ベストプラクティス

オープンソース

制限事項

サンドボックス化がカバーしていないもの

関連項目