> ## Documentation Index
> Fetch the complete documentation index at: https://factory-docs-model-update-cl-824.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックス

> OS レベルのサンドボックスは、カーネルで強制されるポリシーを使って、Droid をファイルシステムとネットワークから分離します（Beta）。

<Note>
  **Beta** — OS レベルのサンドボックスはオプトインであり、活発に開発が進められています。動作、設定、
  プラットフォームサポートはリリースごとに変更される可能性があります。
</Note>

OS レベルのサンドボックスにより、ユーザーは Droid に対してファイルシステムおよびネットワークの境界を設定できます。Beta 版では、Droid が開始するすべてのシェルコマンドが別プロセスで実行され、ユーザーが設定し OS カーネルレベルで強制されるファイルシステムおよびネットワークの境界に制限されます。

## OS レベルの分離の仕組み

サンドボックスは、OS が信頼できないソフトウェアを隔離するために使うのと同じオペレーティングシステムのプリミティブでファイルシステムおよびネットワークの境界を強制します。そのため、ブロックされた読み取り・書き込み・接続は、Droid が自身を取り締まることに頼るのではなく、カーネルによって拒否されます:

* **macOS** -- Seatbelt（macOS 組み込みのサンドボックス）のプロファイルがファイルシステムおよびプロセスへのアクセスを制限します。
* **Linux および WSL2** -- [bubblewrap](https://github.com/containers/bubblewrap) と seccomp フィルターが同等の隔離を提供します。
* **ネットワーク（全プラットフォーム）** -- 送信トラフィックは HTTP/SOCKS フィルタリングプロキシ経由でルーティングされ、許可されたドメインのみを通過させます（Factory 自身のドメインは常に許可されます）。

サンドボックスはこれらのホストのプリミティブに依存するため、それらが利用できない場合は、分離なしで実行するのではなくブロックします。

## 分離モード

`sandbox.mode` 設定は、*何を* OS の境界内に置くかを選択します。どちらのモードも同じデフォルトポリシーと設定を強制し、違いはスコープのみです。

|                           | `per-command`（デフォルト）      | `whole-process` |
| ------------------------- | ------------------------- | --------------- |
| **OS サンドボックス内で実行**        | 各シェルコマンドとその子プロセス          | Droid プロセス全体    |
| **MCP サーバー、フック、サブエージェント** | 呼び出しごとにラップまたはポリシーに対してチェック | プロセス境界内で分離      |
| **メインの Droid プロセス**       | 分離されない                    | 分離される           |
| **分離が利用できない場合**           | 該当するコマンドまたはフックがブロックされる    | Droid が起動を拒否する  |

* **`per-command`** は、Droid が開始する各アクションを個別にサンドボックス経由で実行します。シェルコマンド（およびその子プロセス）は OS レベルで隔離され、その他のツールは各呼び出しの前にポリシーチェックによって仲介されます。メインの Droid プロセス自体は分離されません。
* **`whole-process`** は Droid プロセス全体を OS サンドボックス内で起動するため、メインプロセスとそれが生成するすべて（MCP トランスポート、サブエージェント）も分離されます。Droid 自身のネットワークリクエスト（Execute ツールからのものだけでなく）も `allowedDomains` に対してフィルタリングされ、TUI モードでは対話型のドメインプロンプトが表示されます。起動時にサンドボックスを確立できない場合（非対応プラットフォームまたは分離チェックの失敗）、Droid はサンドボックスなしで実行するのではなく起動を拒否します。

## サンドボックスの有効化と設定

サンドボックスを有効にするには、設定で `sandbox.enabled` を `true` にします:

```jsonc theme={null}
{
  "sandbox": {
    "enabled": true
  }
}
```

有効にすると、以下のデフォルトポリシーがただちに適用されます。開始するために他の設定は必要ありません。設定は階層（組織 > プロジェクト > ユーザー）に沿って解決されるため、自分自身（ユーザー設定）、リポジトリ（プロジェクト設定）、または全員（組織設定）に対してサンドボックスを有効にできます。

### デフォルトのアクセスポリシー

| リソース         | デフォルトポリシー                                                                          | 設定方法                                                           |
| ------------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **ファイル読み取り** | すべて許可。明示的な `denyRead` エントリのみがブロックされます。                                             | `sandbox.filesystem.denyRead`                                  |
| **ファイル書き込み** | **CWD**（カレントワーキングディレクトリ）を除きすべて拒否。追加のパスを許可できます。`denyWrite` は `allowWrite` より優先されます。 | `sandbox.filesystem.allowWrite`、`sandbox.filesystem.denyWrite` |
| **ネットワーク**   | Factory 自身のドメイン（デフォルトで常に許可）を除きすべて拒否。追加のドメインは明示的に許可する必要があります。                       | `sandbox.network.allowedDomains`                               |

### 設定リファレンス（全項目）

```jsonc theme={null}
{
  "sandbox": {
    "enabled": true,
    // 分離のスコープ: "per-command"（デフォルト）または "whole-process"
    "mode": "per-command",
    "filesystem": {
      // CWD（常に書き込み可能）以外に書き込みを許可するパス
      "allowWrite": ["/tmp/build-output", "~/.config"],
      // 親が allowWrite にあっても、特定のサブパスへの書き込みを拒否
      "denyWrite": ["/tmp/build-output/cache/locks", "~/.config/secrets"],
      // 特定のパスへの読み取りをブロック（それ以外はすべて読み取り可能）
      "denyRead": ["~/.aws/credentials", "~/.ssh/id_rsa"]
    },
    "network": {
      // これらのドメインのみ到達可能（Factory 自身のドメインは常に含まれます）
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}
```

設定は階層（組織 > プロジェクト > ユーザー）でマージされます。`denyWrite`／`denyRead` は和集合でマージされ、組織の拒否は下流で削除できません。

### 組織による制御

* 組織レベルの `denyWrite`／`denyRead` 設定は、ユーザーの「常に許可」では上書きできません
* 拒否が組織設定に由来する場合、違反プロンプトには「（組織ポリシー）」と表示されます
* 管理者は **Enterprise Controls** から、サンドボックスの分離モード（`per-command` または `whole-process`）を組織全体に設定できます

## 適用範囲と強制

サンドボックス有効時、ツールが行いうるすべての操作をファイルシステムおよびネットワークのルールに対してチェックできる場合にのみ、そのツールは実行されます。アクションをチェックできないツールはブロックされます。

* **ファイルツール**（Read、Edit、Create、LS、Grep、Glob、ApplyPatch） -- すべての操作の前にチェックされ、読み取りには `denyRead`、書き込みには `allowWrite`／`denyWrite` が強制されます
* **Execute ツール** -- シェルコマンドは OS サンドボックス内で実行され、ネットワークはドメインレベルの制御のためフィルタリングプロキシ経由でルーティングされます
* **FetchUrl** -- ネットワークリクエストは `allowedDomains` に対してチェックされます
* **WebSearch** -- ネットワークリクエストは `allowedDomains` に対してチェックされます
* **MCP ツール** -- ファイルシステムおよびネットワークのリクエストがチェックされます。ローカルで起動されるサーバーは最小限の環境で開始されます（ホストの環境変数は削除され、安全な運用上の許可リストと `mcp.json` で設定したキーのみが保持されます）
* **サブエージェント（Task ツール）** -- 委任されたサブエージェントは親のサンドボックスポリシーを継承します
* **フック** -- フックコマンド（PreToolUse、PostToolUse など）はサンドボックスでラップされ、Execute ツールと同じプロキシ／ランタイム環境で実行されます。サンドボックスを確立できない場合、フックはホスト上で実行される代わりにブロックされます

### ブロックされたとき

**対話型の権限プロンプト（TUI モード）:**

* サンドボックス違反があると、Auto（High）自律レベルでもエージェントループが中断され、TUI プロンプトが表示されます
* 選択肢: **1回だけ許可**、**常に許可**（設定に永続化）、**拒否** -- `denyRead`／`denyWrite` 違反では、「常に許可」の代わりに「拒否リストから削除」が表示されます
* Execute のネットワーク違反では、リアルタイムのドメインプロンプトが表示され、60秒で自動拒否されます

**非対話モード（`droid exec`）:**

* サンドボックス違反はプロンプトなしで自動拒否されます -- ハングせず、ユーザー操作も不要です
* エージェントは拒否メッセージを受け取り、それを出力に報告します

**「常に許可」の永続化:**

* **常に許可** を選択すると、その例外がユーザー設定に保存され（例: ドメインを `allowedDomains` に、パスを `allowWrite` に追加）、次回以降はプロンプトが表示されません
* 変更は現在のセッションにすぐ反映されます

**TUI インジケーター:**

* サンドボックス有効時、フッターに `SANDBOX` ステータスインジケーターが表示されます
* 違反の詳細（パス、ドメイン、理由）を示す「Sandbox Violation」プロンプトが表示されます

## セキュリティ上の制限

サンドボックスはミスやプロンプトインジェクション攻撃の影響を軽減しますが、リスクを完全になくすわけではありません:

* **許可されたネットワーク送信からデータが漏洩する可能性があります。** `allowedDomains` にある各ドメインは、エージェントが読み取れるデータが外部に出ていく経路になり得ます。許可リストはワークフローが許す限り狭く保ってください。
* **書き込み可能なパスは依然として変更され得ます。** サンドボックスは書き込みが *どこに* 行われるかを制限しますが、許可されたパス内で *何が* 書き込まれるかは制限しません -- ワーキングディレクトリ配下の自分のプロジェクトコードも含みます。
* **設定ファイルは保護されます。** サンドボックス化されたツールプロセスは Droid 自身の設定ファイル（例: `settings.json`）に書き込むことができないため、サンドボックスポリシーを密かに変更することはできません。

サンドボックスは、[自律レベル](/jp/cli/user-guides/auto-run) の承認や人によるレビューと並ぶ多層防御の一つとして扱い、信頼できないコードを囲む堅牢な境界とは考えないでください。信頼できないコードを評価するには、Droid をコンテナや専用の仮想マシン内で実行してください。

## 関連

* [自律レベル](/jp/cli/user-guides/auto-run) -- ツールのリスクに対する承認ポリシー。
* [設定](/jp/cli/configuration/settings) -- `sandbox.*` の格納場所。
* [階層的な設定と組織による制御](/jp/enterprise/hierarchical-settings-and-org-control) -- 組織ポリシーとユーザー設定のマージ方法。
* [セキュリティ](/jp/cli/account/security) -- Droid CLI の広範なセキュリティモデル。