このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。 英語版

サンドボックスモード

ステータス: 現行 対象範囲: 現在の状態 最終確認: 2026-08-23 所有者: ax-code runtime

AX Code には、AI エージェントがシステム上でできることを制限できる、組み込みの実行サンドボックスがあります。既定では、AX Code はサンドボックスをオフにした フルアクセス で開始するため、ファイルシステムの書き込みとネットワークアクセスは制限されません。信頼できないリポジトリを扱う前、または無人タスクを実行する前に、workspace-write または read-only を有効にしてください。

セキュリティ上の警告: full-access はセキュリティ境界ではありません。エージェントはワークスペースの外のファイルを変更し、.git/ と .ax-code/ を書き、制限のないシェルコマンドを実行し、ネットワークへアクセスできます。

クイックスタート

TUI からサンドボックスを切り替えます。

• プロンプトで /sandbox と入力する、または
• Ctrl+P を押して “sandbox” を検索する

ステータスバーは現在の状態を示します。

• サンドボックス オン（緑）— エージェントはワークスペースに閉じ込められる
• サンドボックス オフ（赤）— 制限なし

設定は ax-code.json に保存され、セッションをまたいで残ります。

何が変わるか

設定

信頼できる情報源

このページは、利用者から見える挙動を要約します。挙動が変わったときは、次と照合して文書を確認してください。

• packages/ax-code/src/isolation/index.ts は、モードの解決、保護パス、ネットワーク検査、書き込み検査、bash 検査、および IsolationDeniedError を扱います。
• 設定の形、既定、説明については packages/ax-code/src/config/schema.ts。
• ランタイムの切り替え挙動と永続化については packages/ax-code/src/server/routes/isolation.ts。
• 期待される強制の挙動については packages/ax-code/test/isolation/isolation.test.ts と packages/ax-code/test/tool/bash.test.ts。

ルートの README に重複する主張は短く保ち、詳細はここへリンクしてください。

TUI から切り替える

/sandbox、またはコマンドパレット（Ctrl+P → 「サンドボックスのオン/オフ」）を使います。変更は直ちに効き、プロジェクトの ax-code.json に保存されます。

CLI フラグ

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

環境変数

AX_CODE_ISOLATION_MODE=workspace-write ax-code

設定ファイル

ax-code.json の中:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

優先順位

CLI フラグ > 環境変数 > 設定ファイル > 既定（full-access）

CLI または環境の上書きが有効なとき、TUI はその実効モードを報告します。/sandbox の切り替えはプロジェクトの設定を保存できますが、より優先度の高い上書きは、取り除かれるまで（通常は再起動時）有効なままです。

隔離モード

保護されたパス

workspace-write モードでは、次のパスは常に書き込み保護されます。

• .git/ — 誤って git の状態を壊すことを防ぎます
• .ax-code/ — 設定やプラグインの改ざんを防ぎます

設定で、独自の保護パスを追加します。

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

ネットワークアクセス

ネットワークは、workspace-write と read-only のモードでは既定で無効です。影響を受けるツールは次のとおりです。

• webfetch — 遮断
• websearch — 遮断
• codesearch — 遮断
• bash — ネットワーク専用クライアント（curl、wget、nc/ncat/netcat、telnet、ftp、tftp、scp、sftp、dig、nslookup、host）は遮断されます

限界: bash でのネットワーク遮断はアプリケーション層であり、上に挙げた専用ネットワーククライアントを対象とします。オフラインでも動く両用ツール（git、npm/pnpm/yarn、pip、go、python/node のような言語インタプリタ）は傍受しません。オフライン呼び出しを静的に区別できず、遮断すると一般的な作業が壊れるためです。真に網羅的なネットワーク隔離には OS レベルの制御が必要ですが、このサンドボックスはそれを提供しません。拒否されたクライアントに当たると、エージェントは 1 回限りの昇格を求めます。

書き込み制限を保ったままネットワークを許すには、次のようにします。

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

隔離バックエンド（アプリと OS）

macOS: sandbox-exec による Seatbelt プロファイル（書き込みはワークスペースと worktree に限定、network: false のときネットワークは拒否）。
Linux: インストールされているときの bubblewrap（bwrap）（ネットワーク無効時は --unshare-net、ワークスペースは読み書きでバインドマウント）。
Windows: 現時点ではアプリ層のみ。

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

脅威モデルは SECURITY.md を参照してください。

リポジトリが制御する権限とフック

プロジェクトファイルは既定で信頼されません。ax-code.json、.ax-code/policy.json、およびプロジェクトのエージェントまたはモード定義にある権限規則は、deny でアクセスを厳しくできますが、リポジトリが制御する allow/ask の許可は無視されます。プロジェクトのコマンドはシェル展開を有効にできません。.ax-code/hooks.json、.ax-code/plugin/、およびプロジェクトが設定したプラグインは実行されません。

信頼されないプロジェクト設定は、カスタムシェル、実行可能な LSP やフォーマッタ、プロバイダーパッケージや API エンドポイント、プロバイダー認証情報の環境変数、外部スキルのソース、worktree の外にある指示パスも選べません。安全な相対指示パスと、実行可能でない組み込みの上書きは引き続き使えます。MCP サーバーは、MCP 連携 で説明する、別の指紋付き承認フローを使います。

リポジトリが制御する設定を確認したあと、利用者はリポジトリの外で、現在のプロセスについてオプトインできます。

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

環境変数だけの切り替えは、チェックアウトが自らを信頼済みと宣言することを防ぎます。

強制がどう働くか

サンドボックスの強制は 常に アプリケーション層で、各ツール呼び出しのときに検査されます。backend が os または auto で、プラットフォームが対応しているとき、bash はさらにカーネルサンドボックスで包まれます。

ツールが隔離に違反すると、何が遮断されたかとその理由を説明する明確なメッセージ付きで IsolationDeniedError を投げます。