Skip to main content
--sandbox フラグを指定すると、CLI が OS レベルで分離された状態で実行され、書き込み可能なパスと deny ルールがオペレーティングシステム レベルで適用されます。必要に応じて、ネットワークトラフィックを制限することもできます。

​
サンドボックスの仕組み

サンドボックスがアクティブな場合:
  • 書き込み可能なパスは、付与された Write(...) の権限スコープ と workspace directory から決まり、それ以外はすべて読み取り専用です
  • 読み取り可能なパスは、deny リスト内の Read(...) ルールの対象となるパスを除くすべてのパスです。これらのパスはサンドボックス化された command から完全に隠されます
  • セッションの途中で付与された Write(...) scope によって、以降の command に対するサンドボックスの範囲が動的に広がります。セッション途中の Read(...) 承認は agent 自身の tools にのみ影響し、Read(...) の deny ルールによって隠されたパスを表示することはできません。このパスはセッション全体で隠されたままです
サンドボックスの解決に失敗した場合 (たとえば、ユーザーのプラットフォームでサンドボックス化ツールを利用できない場合) 、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 がアクティブで、ドメインフィルタリングが設定されている場合、管理対象のネットワークプロキシがループバック上で起動し、サンドボックスはすべての子プロセスの通信をこのプロキシ経由に制限します。 ドメインパターンの構文: 例:
ドメインフィルタリングは、サンドボックスがアクティブな場合 (--sandbox) に適用されます。--sandbox を指定しない場合、サンドボックスのセクションは無視されます。

​
除外するコマンド

場合によっては、特定のコマンドをサンドボックスの外で実行する必要があります。たとえば、認証情報へのアクセスが必要な git コマンドや、サンドボックスでブロックされるフックなどです。sandbox.excluded 設定セクションでは、permissions と同じ Exec(...) ルール構文を使って、マッチングするコマンドをサンドボックスによる分離の対象外にできます。 例:
ルールの解決: 各コマンドでは、ソース内でマッチした最も具体的なルールが適用されます (たとえば、Exec(git push *) は Exec(git *) より優先されます) 。また、ユーザー設定とチーム設定の両方がマッチする場合は、より制限の厳しい判定が優先されます (deny > ask > allow) 。マッチするルールがないコマンドは、sandbox.excluded がまったく設定されていない場合も含め、常にサンドボックス内で実行されます。
  • sandbox.excluded でサポートされるのは Exec(...) ルールのみです。その他のルール種別 (たとえば Read(...)、Write(...)) は、警告を出して無視されます。
  • 除外はフェイルクローズです。コマンドを安全に判定できない場合 (たとえば解析できない場合) は、サンドボックス内にとどまります。
  • 除外は、コマンドごとのデフォルトの exec パスに適用されます。永続的な PTY シェルを通じて実行されるコマンド (対話型セッション、または pty_for_noninteractive_exec が有効な場合) は、常にサンドボックス内にとどまります。

​
Enterprise レベルの適用

Enterprise 管理者は、チーム設定 で組織全体のサンドボックスの動作を制御できます。

​
サンドボックス強制モード

組織全体で --sandbox フラグの強制レベルを設定します。
  • Optional (default) — --sandbox を渡すかどうかはユーザーが選択できます。強制はありません。
  • Required — --sandbox フラグは、コマンドラインで指定しない場合でも、すべてのユーザーに対して強制的に有効になります。すべての CLI セッションは、書き込み可能なパスと Read(...) の拒否ルールを適用する OS レベルのファイルシステムサンドボックスで実行されます。
将来的には Strict モードが追加され、サンドボックス構成が完全に固定されて、ユーザーがサンドボックス設定を変更できなくなる可能性があります。
組織全体でサンドボックス強制モードを Required に設定する前に、すべての対象マシンのプロビジョニングが完了していることを確認してください。Windows を利用しているユーザーがいる場合、Windows で OS レベルのサンドボックスがサポートされるか、ポリシーが Optional に緩和されるまで、そのユーザーは CLI を実行できません。

​
Enterprise ドメインフィルタリング

管理者は、組織全体のドメイン許可リストと拒否リストを設定することもできます。
  • ドメイン許可リスト — 設定すると、このリスト内のドメインのみがサンドボックスのネットワークプロキシ経由でアクセス可能になります。このリストが優先され、ユーザーが設定した allowed_domains は完全に置き換えられます。ユーザーは、管理者の制限を回避するために追加のドメインを加えることはできません。
  • ドメイン拒否リスト — 常にブロックされるドメインです。Enterprise の拒否ドメインは追加式です。つまり、ユーザーのローカル denied_domains とマージされ、結合後のリストはより制限が厳しくなります。
Enterprise とユーザーのドメインリストの相互作用:
ユーザーのローカル denied_domains は保持され、追加式でマージされるため、Enterprise の許可リストに含まれるドメインをユーザーが拒否できる場合があります。これは意図された動作です。結合後の結果は常により制限が厳しくなり、緩くなることはありません。これによってアクセスの問題が発生する場合は、ローカル設定から競合するエントリを削除してください。

​
Enterprise での除外コマンド

管理者は、チーム設定で組織全体に適用される除外コマンドルールを設定することもできます。
  • Excluded allow / ask — 組織全体で、コマンドをサンドボックスの外で自動実行する、または確認後に実行することを許可する Exec(...) ルール。
  • Excluded deny — コマンドをサンドボックスの外で決して実行させない Exec(...) ルール。チームの deny は、マッチングするコマンドに対するユーザーレベルの allow または ask より優先されるため、ユーザーは管理者が禁止したコマンドを除外できません。
チームとユーザーのルールはまとめて解決されます。各ソース内では最も具体的にマッチしたルールが優先され、ソース間ではより制限の厳しい判定が優先されます (deny > ask > allow) 。 例: gh 以外のすべての除外を禁止する。 ワイルドカード deny に、例外として allow を切り出して追加すると、ユーザーがローカルで何を設定していても、gh を除くすべてのコマンドはサンドボックス内に留まります。これらの値は、チーム設定の excluded-commands 構成に記述します (ユーザー設定ファイルではないため、sandbox キーで囲む必要はありません) 。
より具体的な Exec(gh *) ルールはワイルドカードの Exec(**) より優先されるため、gh コマンドはサンドボックスの外で実行され、それ以外はすべてサンドボックス内にとどまります。また、チームレベルのワイルドカード deny は、他のコマンドに対するユーザーレベルの allow や ask ルールよりも優先されます。

​
参考資料

  • チーム設定 — Enterpriseのサンドボックス強制とドメインフィルタリング
  • 設定ファイル リファレンス — ユーザーレベルの sandbox 設定セクション
  • 権限 — サンドボックスの書き込み可能なパスと拒否ルールを制御する権限スコープ