--sandbox フラグを指定すると、CLI が OS レベルで分離された状態で実行され、アクティブな Read / Write 権限スコープがオペレーティングシステム レベルで適用されます。必要に応じて、ネットワークトラフィックを制限することもできます。
サンドボックスがアクティブな場合:
- 書き込み可能なパスは、付与された
Write(...) の権限スコープ と workspace directory から決まります
- 読み取り可能なパスは、付与された
Read(...) scope から決まります (/usr/bin などのプラットフォームのデフォルトパスは常に読み取り可能です)
- セッションの途中で付与された scope によって、以降の command に対するサンドボックスの範囲が動的に広がります
サンドボックスの解決に失敗した場合 (たとえば、ユーザーのプラットフォームでサンドボックス化ツールを利用できない場合) 、CLI はサンドボックスなしで実行されるのではなく、起動を拒否します。このフェイルクローズの動作は、サンドボックスが team setting によって有効になっている場合でも、ユーザーが --sandbox を直接指定した場合でも適用され、セキュリティ上の意図が黙って迂回されないようにします。サンドボックスの解決に失敗する一般的な原因:
- Windows: Windows は現在、OS レベルのサンドボックス化をサポートしていません。Windows 上のセッションでは、
--sandbox を指定した場合、またはサンドボックス強制が Required の場合、CLI が IDE 内で ACP server として実行されるケース (たとえば Devin Desktop) を含め、必ず失敗します。
- Linux: サンドボックス化には
bubblewrap (bwrap) と socat のインストールが必要です。これらがない場合、セッションはインストール手順を表示して必ず失敗します。
- Permission scope errors: 解決できない無効なパスが権限スコープ に含まれている。
サンドボックスのネットワークフィルタリングは現在不安定です。この機能が必要な場合は、安定性向上の見込み時期についてアカウント担当者にお問い合わせください。
sandbox セクション (ユーザー設定のみ) で設定します。--sandbox がアクティブで、ドメインフィルタリングが設定されている場合、管理対象のネットワークプロキシがループバック上で起動し、サンドボックスはすべての子プロセスの通信をこのプロキシ経由に制限します。
| Option | Type | Default | Description |
|---|
allowed_domains | string[] | [] | プロキシ経由を許可するドメインパターン。空でない場合、マッチングしたドメインのみが許可されます (許可リストモード) |
denied_domains | string[] | [] | 常にブロックされるドメインパターン。拒否ルールは許可ルールより優先されます |
network_mode | string | "full" | "full" はすべての HTTP メソッドを許可します。"limited" は GET/HEAD/OPTIONS のみを許可します |
| Pattern | Matches |
|---|
example.com | 完全一致のみ |
*.example.com | 任意のサブドメイン (apex は除く) |
**.example.com | apex ドメインと任意のサブドメイン |
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
ドメインフィルタリングは、サンドボックスがアクティブな場合 (--sandbox) に適用されます。--sandbox を指定しない場合、サンドボックスのセクションは無視されます。
git コマンドや、サンドボックスでブロックされるフックなどです。sandbox.excluded 設定セクションでは、permissions と同じ Exec(...) ルール構文を使って、マッチングするコマンドをサンドボックスによる分離の対象外にできます。
| オプション | 型 | 説明 |
|---|
excluded.allow | string[] | マッチングするコマンドは自動的にサンドボックスの外で実行されます |
excluded.ask | string[] | マッチングするコマンドは、ユーザーが確認プロンプトで承認した後にサンドボックスの外で実行されます |
excluded.deny | string[] | マッチングするコマンドは除外されず、常にサンドボックス内で実行されます |
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
Exec(git push *) は Exec(git *) より優先されます) 。また、ユーザー設定とチーム設定の両方がマッチする場合は、より制限の厳しい判定が優先されます (deny > ask > allow) 。マッチするルールがないコマンドは、sandbox.excluded がまったく設定されていない場合も含め、常にサンドボックス内で実行されます。
sandbox.excluded でサポートされるのは Exec(...) ルールのみです。その他のルール種別 (たとえば Read(...)、Write(...)) は、警告を出して無視されます。- 除外はフェイルクローズです。コマンドを安全に判定できない場合 (たとえば解析できない場合) は、サンドボックス内にとどまります。
- 除外は、コマンドごとのデフォルトの exec パスに適用されます。永続的な PTY シェルを通じて実行されるコマンド (対話型セッション、または
pty_for_noninteractive_exec が有効な場合) は、常にサンドボックス内にとどまります。
--sandbox フラグの強制レベルを設定します。
- Optional (default) —
--sandbox を渡すかどうかはユーザーが選択できます。強制はありません。
- Required —
--sandbox フラグは、コマンドラインで指定しない場合でも、すべてのユーザーに対して強制的に有効になります。すべての CLI セッションは、Read/Write 権限スコープを適用する OS レベルのファイルシステムサンドボックスで実行されます。
将来的には Strict モードが追加され、サンドボックス構成が完全に固定されて、ユーザーがサンドボックス設定を変更できなくなる可能性があります。
組織全体でサンドボックス強制モードを Required に設定する前に、すべての対象マシンのプロビジョニングが完了していることを確認してください。Windows を利用しているユーザーがいる場合、Windows で OS レベルのサンドボックスがサポートされるか、ポリシーが Optional に緩和されるまで、そのユーザーは CLI を実行できません。
- ドメイン許可リスト — 設定すると、このリスト内のドメインのみがサンドボックスのネットワークプロキシ経由でアクセス可能になります。このリストが優先され、ユーザーが設定した
allowed_domains は完全に置き換えられます。ユーザーは、管理者の制限を回避するために追加のドメインを加えることはできません。
- ドメイン拒否リスト — 常にブロックされるドメインです。Enterprise の拒否ドメインは追加式です。つまり、ユーザーのローカル
denied_domains とマージされ、結合後のリストはより制限が厳しくなります。
Enterprise とユーザーのドメインリストの相互作用:
| シナリオ | Enterprise 設定 | ユーザー設定 | 実際の結果 |
|---|
| 管理者が許可リストを設定 | allowed_domains: ["github.com"] | allowed_domains: ["npmjs.org"] | github.com のみが許可されます (Enterprise がユーザーリストを置き換えます) |
| 管理者が拒否リストを設定 | denied_domains: ["evil.com"] | denied_domains: ["risky.io"] | evil.com と risky.io の両方がブロックされます (マージされるため) |
| 管理者の許可リストなし | allowed_domains: [] | allowed_domains: ["github.com"] | ユーザーの許可リストが利用されます |
ユーザーのローカル denied_domains は保持され、追加式でマージされるため、Enterprise の許可リストに含まれるドメインをユーザーが拒否できる場合があります。これは意図された動作です。結合後の結果は常により制限が厳しくなり、緩くなることはありません。これによってアクセスの問題が発生する場合は、ローカル設定から競合するエントリを削除してください。
- Excluded allow / ask — 組織全体で、コマンドをサンドボックスの外で自動実行する、または確認後に実行することを許可する
Exec(...) ルール。
- Excluded deny — コマンドをサンドボックスの外で決して実行させない
Exec(...) ルール。チームの deny は、マッチングするコマンドに対するユーザーレベルの allow または ask より優先されるため、ユーザーは管理者が禁止したコマンドを除外できません。
チームとユーザーのルールはまとめて解決されます。各ソース内では最も具体的にマッチしたルールが優先され、ソース間ではより制限の厳しい判定が優先されます (deny > ask > allow) 。
例: gh 以外のすべての除外を禁止する。 ワイルドカード deny に、例外として allow を切り出して追加すると、ユーザーがローカルで何を設定していても、gh を除くすべてのコマンドはサンドボックス内に留まります。これらの値は、チーム設定の excluded-commands 構成に記述します (ユーザー設定ファイルではないため、sandbox キーで囲む必要はありません) 。
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
Exec(gh *) ルールはワイルドカードの Exec(**) より優先されるため、gh コマンドはサンドボックスの外で実行され、それ以外はすべてサンドボックス内にとどまります。また、チームレベルのワイルドカード deny は、他のコマンドに対するユーザーレベルの allow や ask ルールよりも優先されます。
- チーム設定 — Enterpriseのサンドボックス強制とドメインフィルタリング
- 設定ファイル リファレンス — ユーザーレベルの
sandbox 設定セクション
- 権限 — サンドボックスパスの解決に影響する権限スコープ
