Claude Code スタイルのコーディングエージェントや管理されたコーディングエージェントをサンドボックスで実行するには、各エージェントにスコープ付きのワークスペース、明示的なファイル権限、制御されたシェル実行、ネットワークとパッケージポリシー、明確なシークレット境界、永続的なログ、キャプチャされたアーティファクト、そして変更がマージまたは出荷される前に人間によるレビューを提供します。エージェントはコードの読み取り、ファイルの編集、依存関係のインストール、テストの実行、パッチの生成を引き続き行うことができますが、その周囲の環境が、何に触れられるか、何を取得できるか、どの資格情報を参照できるか、そしていつ人間が次のステップを承認する必要があるかを決定します。
何を隔離する必要があるか
コーディングエージェントは、リポジトリに接続された単なるチャットボットではありません。ファイルを編集し、コマンドを実行できるようになると、言語モデルによる推論を処理に含むジュニアビルドワーカーのように見えてきます。そのワーカーは npm test を実行したり、生成されたファイルを検査したり、開発サーバーを起動したり、エラーメッセージが示唆するためにパッケージインストールを試みたりするかもしれません。ワークスペースがあなたのラップトップ、共有の CI ランナー、または長期稼働する本番環境に近い VM である場合、爆発半径が広すぎます。
隔離の対象は、エージェントの作業ループ全体です。
- エージェントが読み取りまたは変更できるリポジトリのチェックアウトとブランチ。
- エージェントが書き込めるファイルシステムパス。
- 自動的に実行できるコマンド。
- 承認が必要なコマンド。
- エージェントが到達できるパッケージレジストリ、ドメイン、API。
- セッションに公開される資格情報。
- レビューのために保存されるログ、差分、テスト出力、スクリーンショット、アーティファクト。
- 成功、失敗、またはタイムアウト後のクリーンアップ動作。
Claude Code やその他の管理されたコーディングエージェント製品には、独自の権限システムが含まれている場合があります。Anthropic の Claude Code ドキュメントでは、たとえば、許可および拒否されたツールの権限設定、承認動作、ローカル使用のためのサンドボックスガイダンスについて説明しています。これらのコントロールを、全体の境界ではなく、1 つのレイヤーとして扱ってください。より強力な設計では、エージェントを隔離されたランタイム内に配置し、そのランタイム内でツールの権限を適用します。
リファレンスアーキテクチャ
実用的なサンドボックス化されたエージェントワークフローには、4 つのレイヤーがあります。
| レイヤー | 目的 | 典型的な制御 |
|---|---|---|
| エージェントコントローラ | タスク計画とツール呼び出しを決定する | モデル/ツールの権限、承認モード、タスクプロンプト |
| サンドボックスランタイム | コマンドが実行されるワークスペースをホストする | 隔離されたファイルシステム、プロセス制限、ライフサイクル制御 |
| ポリシーゲートウェイ | 許可されるアクションを決定する | コマンドルール、ネットワーク出力ルール、パッケージポリシー、シークレットスコープ |
| レビューサーフェス | 人間が結果を検査できるようにする | 差分、ログ、テスト結果、アーティファクト、プルリクエスト |
これらのレイヤーは分離しておいてください。エージェントコントローラがプロンプトインジェクションによって侵害された場合でも、サンドボックスランタイムとポリシーゲートウェイによって、何が起こるかが制限されるべきです。パッケージインストールが予期しないコードを取得した場合、ネットワークとアーティファクトログによってそれが可視化されるべきです。エージェントがもっともらしいパッチを生成した場合でも、レビューサーフェスは、正確に何が変更され、どのテストが実行されたかを示すべきです。
概念的なポリシーオブジェクトは次のようになります。
workspace:
mode: ephemeral
repo_ref: pull-request-branch
writable_paths:
- /workspace/project
readonly_paths:
- /workspace/reference
commands:
auto_allow:
- git status
- npm test
- npm run lint
- pytest
require_approval:
- npm install
- pip install
- docker build
- git push
deny:
- rm -rf /
- curl ... | sh
network:
default: deny
allow:
- registry.npmjs.org
- pypi.org
- files.pythonhosted.org
secrets:
expose:
- READ_ONLY_PACKAGE_TOKEN
deny:
- PRODUCTION_DATABASE_URL
- CLOUD_ADMIN_TOKEN
artifacts:
capture:
- git diff
- test-results/
- screenshots/
- command-log.jsonl
これは意図的に SDK の例ではありません。正確なポリシーフォーマットは、使用するエージェントフレームワークとサンドボックスプロバイダーによって異なります。重要な点は、権限はモデルの自由形式の推論の外部で表現され、ランタイムまたはオーケストレーションレイヤーによって強制されるべきであるということです。
ワークスペースとリポジトリのセットアップ
すべてのエージェント実行をクリーンなワークスペースから開始します。管理されたエージェントは、意図的な理由がない限り、開発者のシェル履歴、SSH エージェント、ドットファイル、クラウド CLI ログイン、または追跡されていないローカルファイルを継承すべきではありません。
リポジトリ作業の場合は、専用のチェックアウトを使用します。
- タスクに必要なリポジトリのみをクローンまたはマウントする。
- デフォルトブランチを編集する代わりに、新しいタスクブランチをチェックアウトする。
- ベースコミットを固定して、レビューが開始点を再現できるようにする。
- 依存関係キャッシュを書き込み可能なソースパスから分離する。
- 生成されたアーティファクトは、意図された差分の一部でない限り、ソースツリーの外部に保存する。
ブランチの分離は重要です。なぜなら、コーディングエージェントはしばしば決着する前にいくつかのアプローチを試すからです。クリーンなタスクブランチは、レビュアーに一時的な実験が混在したワークスペースではなく、通常のプルリクエスト差分を提供します。エージェントが参照実装と比較する必要がある場合は、その参照を読み取り専用でマウントします。
長期稼働する管理エージェントの場合は、サンドボックスがエフェメラル、一時停止、またはスナップショットのいずれであるかを決定します。エフェメラルワークスペースは推論が容易です。スナップショットと一時停止/再開は、長時間のジョブ、ブラウザセッション、および高コストなセットアップ手順に役立ちますが、明確な監査証跡（スナップショットが作成された日時、存在していたファイル、利用可能だった資格情報）を保持する必要があります。
ファイルシステムの権限
ファイルシステムのスコープは、「エージェントがマシン全体を読み取れる」よりも狭くする必要があります。ほとんどのコーディングタスクには以下が必要です。
- リポジトリワークスペースへの読み取り/書き込みアクセス。
- 選択されたタスクコンテキスト、フィクスチャ、またはドキュメントへの読み取り専用アクセス。
- ビルド出力とスクラッチファイル用の一時ディレクトリ。
- ホームディレクトリ、無関係なリポジトリ、クラウド資格情報、ブラウザプロファイル、本番データダンプへのアクセスは不可。
書き込み権限は特別な注意が必要です。リポジトリを編集できるコーディングエージェントは、スクリプト、テスト、ロックファイル、CI 設定、デプロイファイルも編集できます。これはまさにタスクに必要なことかもしれませんが、レビューで可視化されるべきです。機密性の高いパス（.github/workflows/、デプロイマニフェスト、パッケージ公開設定など）については、より強力な承認ステップまたは人間が所有する最終レビューを要求します。
タスクが限定されている場合は、ファイルの許可リストを使用します。たとえば、ドキュメントエージェントは docs/ と生成されたプレビューディレクトリのみを必要とする場合があります。依存関係アップグレードエージェントは package.json、ロックファイル、テストスナップショットを必要とする場合があります。広範なリファクタリングにはより広いアクセスが必要ですが、その場合、レビューはより大きな差分とより完全なテストを期待する必要があります。
シェル実行ポリシー
シェルアクセスは、コーディングエージェントが有用かつリスクを伴うものになるポイントです。テストの実行、コードのフォーマット、ビルドエラーの調査、修正の検証にはコマンド実行が必要です。しかし、一時停止なしですべてのコマンドを制限なく実行する権限は必要ありません。
適切なシェルポリシーには 3 つのバケットがあります。
| バケット | 例 | なぜ重要なのか |
|---|---|---|
| 自動許可 | git status、npm test、pytest、go test ./...、npm run lint |
通常の編集-テストループを高速に保つ |
| 承認が必要 | パッケージインストール、マイグレーション、長時間実行サービス、外部 CLI、git push |
状態、コスト、またはネットワークリスクが変化する場合に摩擦を追加する |
| 拒否 | 破壊的なホストコマンド、資格情報のダンプ、安全でないシェルパイプ、ワークスペース外への書き込み | 委任すべきでないアクションをブロックする |
コマンドテキストのマッチングだけに依存しないでください。エージェントは、スクリプト、パッケージマネージャーフック、またはネストされたシェルを介してコマンドを実行できます。リスクの高い環境では、コマンドポリシーをランタイムレベルのファイルシステム境界、リソース制限、ネットワーク制御と組み合わせます。
長時間実行コマンドにはタイムアウト動作が必要です。テストサーバー、ブラウザ自動化実行、またはビルドウォッチャーは、エージェントが先に進んだ後も生き続ける可能性があります。プロセス ID、標準出力、標準エラー、終了ステータス、実行時間、終了理由をキャプチャします。コマンドがプレビューポートを開く場合は、ポートマッピングを記録し、クリーンアップ中にシャットダウンします。
パッケージインストールとネットワーク出力
パッケージインストールは、エージェントワークスペースの最も有用な機能の 1 つであり、リスクが侵入する最も簡単な場所の 1 つです。コーディングエージェントは、Stack Overflow の回答、README、またはモデルが生成した計画が提案したためにパッケージをインストールする可能性があります。これにより、依存関係グラフが変更され、インストールスクリプトが実行され、外部レジストリに到達する可能性があります。
実装ガイドと本番ワークフローでは、デフォルト拒否のネットワーク姿勢から開始し、タスクに必要なものを許可します。
- npm や PyPI などのパッケージレジストリ。できればレジストリミラーまたはキャッシュを経由して。
- リポジトリとサブモジュールに必要なソースホスト。
- タスクに必要なドキュメントドメイン。
- サンドボックスが適切なデータ分類を持っている場合のみ、内部 API。
デフォルトですべてのエージェントに広範なアウトバウンドインターネットを許可しないでください。調査やブラウザ自動化のために広範なアクセスが必要な場合は、その実行をコード変更実行から分離し、アーティファクトに適切にラベルを付けます。
パッケージインストールについては、以下を記録します。
- パッケージマネージャーコマンド。
- レジストリホスト。
- ロックファイルの変更。
- ダウンロードされたパッケージ名とバージョン（利用可能な場合）。
- 実行されたインストールスクリプト。
- 人間がインストールを承認したかどうか。
これにより、任意のパッケージが安全になるわけではありません。変更がレビュー可能になるだけです。
シークレット境界
シークレットは、タスクにスコープされ、短命であり、デフォルトでは存在しないようにする必要があります。最も安全なサンドボックスは、モデルが決してシークレットを明かさないことを約束するものではなく、タスクが本当に必要としない限りシークレットが存在しないものです。
以下のデフォルトを使用します。
- エージェントワークスペースには本番データベースの資格情報なし。
- クラウド管理者トークンなし。
- 個人の SSH 鍵や開発者マシンの資格情報なし。
- 可能な場合は読み取り専用の資格情報。
- パッケージ読み取り、テストフィクスチャ、またはステージング専用 API 用の個別のトークン。
- アーティファクトが共有される前にログを編集。
エージェントが外部サービスを呼び出す必要がある場合は、狭いトークンを提供し、どのツールまたはコマンドがそれを使用したかを記録します。エージェントが編集できるファイルに広範な資格情報を配置しないでください。環境変数は便利ですが、コマンドによって出力されたり、ログに含まれたり、生成されたファイルにコピーされたりする可能性があります。それらはエージェントプロセスに公開されているものとして扱います。
ログ、アーティファクト、監査証跡
人間のレビューは、レビュアーが何が起こったかを見ることができる場合にのみ役立ちます。サンドボックス化されたコーディングエージェントの実行では、最終的なパッチ以上のものを保存する必要があります。
少なくとも以下をキャプチャします。
- タスクプロンプトまたは指示の要約。
- ベースコミットとブランチ。
- ツールが記録できる場合は、読み取られ、書き込まれたファイル。
- タイムスタンプ、作業ディレクトリ、終了ステータス、標準出力、標準エラーを含む実行されたコマンド。
- パッケージインストールとネットワークアクセスの要約。
- テストとビルドの結果。
- 生成されたファイル、スクリーンショット、レポート、またはプレビューリンク。
- 最終的な差分。
サンドボックスよりも長持ちするレビューサーフェスにログを保存します。実行直後にサンドボックスが破棄される場合でも、証拠はプルリクエスト、CI アーティファクトストア、またはエージェントプラットフォームレコードで引き続き利用可能である必要があります。
管理エージェントを使用するチームにとって、この監査証跡はエージェントのパフォーマンスを比較するのにも役立ちます。失敗が、依存関係の欠落、拒否されたコマンド、不明瞭なプロンプト、不安定なテスト、または実際のコードの問題のいずれに起因するかを確認できます。
クリーンアップとリセット
サンドボックスのクリーンアップは、セキュリティとコスト管理であり、単なるハウスキーピングではありません。実行の終了時には：
- バックグラウンドプロセスを停止する。
- 公開されたポートを閉じる。
- タスクスコープのトークンを無効にする。
- 必要なアーティファクトをエクスポートする。
- レビューの一部ではない一時ファイルを削除する。
- 実行タイプに応じて、サンドボックスを破棄、一時停止、またはスナップショットする。
信頼できない作業や探索的な作業には、エフェメラルリセットが最もクリーンなデフォルトです。長期稼働エージェントの場合は、既知の良好なセットアップステップの後でのみスナップショットを作成し、エージェントの任意のアクティビティの後には作成しないでください。失敗した実行の調査が必要な場合は、サンドボックスまたはスナップショットを明確な有効期限とともに保持します。
Novita Agent Sandbox の位置付け
Novita Agent Sandbox は、コードが開発者のラップトップや共有ホスト上ではなく、隔離されたクラウドワークスペース内で実行される AI エージェント実行ワークフロー向けに設計されています。Novita の Sandbox ドキュメントでは、このガイドのパターンに対応するコアプリミティブ（サンドボックスのライフサイクル管理、ファイルシステム操作、コマンド実行、テンプレート、エージェントワークロードのランタイム管理）について説明しています。
これにより、Novita は、モデル API とともに実行環境を必要とするコーディングエージェント、データ分析、ブラウザエージェント、評価、または長期稼働エージェントワークフローを構築するチームに適しています。ただし、境界は明確にしておいてください。この記事は、Claude Code スタイルおよび管理されたコーディングエージェントのための一般的な実装パターンです。公式の Claude Code 統合、パートナーシップ、またはすべての管理エージェント製品との普遍的な互換性を主張するものではありません。
Novita ベースのワークフローを設計している場合は、製品ドキュメントを使用して正確なリリース済み API サーフェスを確認し、ポリシーレイヤーを明示的にしてください。サンドボックスは隔離された実行ワークスペースを提供できますが、アプリケーションはコマンド承認、ネットワークポリシー、シークレットスコープ、アーティファクト保持、人間によるレビューゲートを決定する必要があります。
セキュリティレビューチェックリスト
コーディングエージェントがおもちゃのリポジトリを超えて実行されることを許可する前に、このチェックリストを使用してください。
| 質問 | 確認すべき点 |
|---|---|
| 隔離境界は何か？ | 専用ワークスペース、プロセス制限、ファイルシステム分離、明確なプロバイダードキュメント |
| エージェントは何を読み取れるか？ | デフォルトではリポジトリのみ、ホームディレクトリなし、無関係なリポジトリなし |
| エージェントは何を書き込めるか？ | 書き込み可能なソースパスが明示的である。機密性の高い設定パスは追加レビューが必要 |
| どのコマンドが自動的に実行されるか？ | テストおよびフォーマットコマンドは許可。状態を変更するコマンドは承認が必要 |
| どのようなネットワークアクセスが存在するか？ | デフォルト拒否またはスコープ付き出力。パッケージレジストリとドキュメントドメインは意図的 |
| パッケージインストールはどのように処理されるか？ | ロックファイルの変更、レジストリホスト、インストールスクリプトが記録される |
| どのシークレットが存在するか？ | タスクスコープ、短命、最小権限の資格情報のみ |
| ログはどうなるか？ | コマンド、出力、差分、アーティファクトはサンドボックスクリーンアップ後も存続する |
| クリーンアップはどのように強制されるか？ | バックグラウンドプロセス、ポート、トークン、一時ファイルは閉じられるか無効化される |
| マージまたは出荷の承認者は誰か？ | 人間のレビュアーがコード、テスト、セキュリティ関連ファイル、生成されたアーティファクトをチェックする |
最も重要なルールは単純です。「エージェントが許可を求めた」ことと「システムが境界を強制した」ことを混同しないでください。モデルはエージェントが何をしたいかを説明するのに役立ちます。ランタイムとポリシーレイヤーは、何が許可されるかを決定するべきです。
FAQ
Claude Code をサンドボックスで実行できますか？
はい、セットアップが Claude Code スタイルのエージェントをスコープ付きワークスペース内に配置し、その周囲にファイルシステム、シェル、ネットワーク、シークレット、ログ、レビューポリシーを適用する場合に可能です。本番環境や機密性の高いリポジトリでは、ローカルの権限プロンプトだけで十分であると想定しないでください。
コーディングエージェントの隔離にはコンテナで十分ですか？
場合によりますが、答えは脅威モデルに依存します。コンテナは再現可能なビルドと依存関係の分離に役立ちますが、セキュリティ重視のワークロードでは、コンテナを完全なサンドボックス境界として扱う前に、カーネル境界、ホストマウント、ネットワークデフォルト、ランタイム特権、プロバイダードキュメントを評価する必要があります。
エージェントにパッケージのインストールを許可すべきですか？
許可することは可能ですが、パッケージインストールは制御されたサプライチェーンイベントとして扱うべきです。レジストリの許可リストまたはミラー、ロックファイルのレビュー、インストールスクリプトのログ記録、および新しい依存関係やリモートコードを取得して実行するコマンドに対する承認を優先してください。
マージ前に人間のレビュアーは何をチェックすべきですか？
最終的な差分、実行されたコマンド、実行されたテスト、パッケージとロックファイルの変更、触れた CI/デプロイメントファイル、生成されたアーティファクト、および拒否されたアクションや承認が必要なアクションをレビューします。セキュリティ重視のリポジトリでは、変更の一部としてサンドボックスポリシー自体もレビューします。
Novita Agent Sandbox は Claude Code と公式に統合されていますか？
この記事はそのような主張をしていません。Novita Agent Sandbox はエージェントワークフロー向けの隔離された実行プリミティブを提供し、Claude Code および管理エージェント製品には独自の製品固有のインターフェースと権限モデルがあります。実行可能なコマンドを公開する前に、現在の製品ドキュメントに対して正確な統合パスを検証してください。
