> ## Documentation Index
> Fetch the complete documentation index at: https://factory-docs-cli-sandbox-mcp-whole-process.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カーネルレベルで強制されるファイルシステムおよびネットワーク境界の範囲内に制限されます。

内部的には、サンドボックスは macOS では Seatbelt プロファイル、Linux では seccomp と組み合わせた bubblewrap、ドメインレベルのネットワークフィルタリングには HTTP/SOCKS プロキシを使用します。Windows は WSL2 経由でサポートされます。

## デフォルトのアクセスポリシー（サンドボックス有効時）

| リソース         | デフォルトポリシー                                                                      | 設定項目                                                            |
| ------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| **ファイル読み取り** | すべて許可。明示的な `denyRead` エントリのみブロックされます。                                          | `sandbox.filesystem.denyRead`                                   |
| **ファイル書き込み** | **CWD**（現在の作業ディレクトリ）以外はすべて拒否。追加のパスは許可できます。`denyWrite` は `allowWrite` より優先されます。 | `sandbox.filesystem.allowWrite`, `sandbox.filesystem.denyWrite` |
| **ネットワーク**   | `*.factory.ai`（デフォルトで常に許可）以外はすべて拒否。追加のドメインは明示的に許可する必要があります。                    | `sandbox.network.allowedDomains`                                |

## サンドボックスモード

`sandbox.mode` 設定で、分離の適用方法を選択します:

* **`per-command`**（デフォルト） -- Droid が開始するシェルコマンドとツール操作のみがサンドボックス化されます。
* **`whole-process`**（Linux のみ） -- Droid プロセス全体が OS サンドボックス内で起動され、メインプロセス、MCP の stdio トランスポート、サブエージェントにまで分離が拡張されます。

## 含まれる機能

**コマンド単位のサンドボックスモード**（`mode: "per-command"`、有効時のデフォルト）:

* **ファイルツール**（Read、Edit、Create、LS、Grep、Glob、ApplyPatch） -- すべての操作の前に `checkFileAccess()` を実行し、読み取りには `denyRead`、書き込みには `allowWrite` / `denyWrite` を適用
* **Execute ツール** -- シェルコマンドを OS サンドボックス（Seatbelt / bubblewrap）でラップし、ネットワークはドメインレベル制御のために SRT のフィルタリングプロキシ経由でルーティング
* **FetchUrl** -- `allowedDomains` に対して `checkNetworkAccess()` を実行
* **MCP ツール** -- サンドボックス有効時は fail closed（拒否）になります。MCP ツールの挙動は不透明で（サーバーがファイルの読み書きやネットワークアクセスなどを行う可能性があります）、プロトコルはツールごとの効果メタデータを公開しないため、強制可能なサンドボックスポリシーにマッピングできず、後述のデフォルト拒否ツールポリシーによってブロックされます。
* **注記** -- このモードではメインのDroidプロセスとサブエージェントは分離されません。これらを分離するには `whole-process` モードを使用してください。

**プロセス全体のサンドボックスモード**（`mode: "whole-process"`、Linux のみ）:

* 起動時に Droid プロセス全体が OS サンドボックス内で再実行されるため、メインプロセス、MCP の stdio トランスポート、サブエージェントのライフサイクルがすべて、設定されたファイルシステムおよびネットワーク境界の範囲内で実行されます
* Droid プロセスが直接行うネットワークリクエスト（Execute ツールからのものだけでなく）も `allowedDomains` に対してフィルタリングされ、TUI モードでは対話型のドメインプロンプトが表示されます
* **Fails closed** -- 起動時にセキュアなランタイムを確立できない場合（非対応プラットフォーム、サンドボックスサポートの欠如、または分離チェックの失敗）、Droid はサンドボックスなしで実行するのではなく起動を拒否します
* デフォルトのアクセスポリシー、ファイルシステムおよびネットワーク設定、「常に許可」の永続化は、コマンド単位モードと同じ挙動です

**ツールポリシー（デフォルト拒否）:**

* 登録されたすべてのツールは、サンドボックスの副作用メタデータ（`filesystem-read`、`filesystem-write`、`network`、`process`、`external-service`、`persistent-settings`）を宣言します
* サンドボックス有効時、宣言されたすべての副作用がサンドボックスポリシーハンドラ（ファイルアクセス、ネットワーク、またはコマンド単位の Execute）にマッピングされる場合にのみ、ツールが許可されます。注釈のない副作用、不明な副作用、または未処理の副作用を持つツールは拒否されます
* ローカルで強制できない効果を持つツール（MCP ツールやコネクタ（`external-service`）など）はハンドラを持たないため、fail closed になります
* ツールポリシーによる拒否は**プロンプト不可**です。ユーザーの承認でポリシーカバレッジの欠如を回避することはできず、これらの拒否は `allowWrite` / `allowedDomains` では設定できません

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

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

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

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

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

* ファイル書き込み違反（CWD外）: ユーザー設定の `sandbox.filesystem.allowWrite` に親ディレクトリを追加
* `denyWrite` 違反: `sandbox.filesystem.denyWrite` から該当エントリを削除
* `denyRead` 違反: `sandbox.filesystem.denyRead` から該当エントリを削除
* ドメイン違反: ドメイン（3つ以上のパートを持つドメインではワイルドカード付き。例: `registry.npmjs.org` -> `*.npmjs.org`）を `sandbox.network.allowedDomains` に追加
* 変更は現在のセッションにすぐ反映されます

**組織管理による強制:**

* 組織レベルの `denyWrite` / `denyRead` 設定は、ユーザーの「常に許可」では上書きできません
* 拒否が組織設定に由来する場合、違反プロンプトには「（組織ポリシー）」と表示されます

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

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

## 設定構成

```jsonc theme={null}
{
  "sandbox": {
    "enabled": true,
    // 分離のスコープ: "per-command"（デフォルト）または "whole-process"（Linux のみ）
    "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.ai は常に含まれる）
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}
```

設定は階層全体（組織 > プロジェクト > ユーザー）でマージされます。`denyWrite` / `denyRead` は和集合マージを使用するため、組織による拒否は下位レイヤーで削除できません。

## 関連

* [自律レベル](/jp/cli/user-guides/auto-run) -- ツールリスクに対する承認ポリシー。
* [設定](/jp/cli/configuration/settings) -- `sandbox.*` の定義場所。
* [階層設定と組織管理](/jp/enterprise/hierarchical-settings-and-org-control) -- 組織ポリシーがユーザー設定とどのようにマージされるか。
* [セキュリティ](/jp/cli/account/security) -- Droid CLI のより広いセキュリティモデル。