Claude Code サンドボックスのベストプラクティスは、次の1つのルールから始まります。Claude Code が、各ステップを人間が承認することなくファイルの編集やコマンドの実行をできる場合、それはラップトップや共有 CI ランナーではなく、隔離されたワークスペース内で実行されるべきです。これはヘッドレスモードではさらに重要です。ヘッドレス実行の目的は、エージェントが「許可」をクリックするのを待つことなく、ファイル編集、シェルコマンド、依存関係のインストールを進められることだからです。Novita の Claude Code サンドボックスガイド は、正確なテンプレートコマンドとフラグに関する信頼できる情報源です。この記事では、チームが通常次に必要とする点、つまり、そもそもなぜ Claude Code をサンドボックス化するのか、そうしない場合に何が問題になるのか、そしてテンプレートを実際のワークフローに組み込む前に追加すべき本番環境向けの制御について焦点を当てます。
なぜ Claude Code にヘッドレスモードでのサンドボックスが必要なのか
Claude Code が有用なのは、コードをドラフトする以上のことを行うからです。ファイルを読み、ファイルを編集し、シェルコマンドを実行し、テスト出力を確認した後に反復処理を行います。同じ能力こそが、インタラクティブな開発者セッションから無人自動処理に移行する際に、サンドボックスを必要とする理由です。
ローカルターミナルでは、人間が通常、不適切なアイデアを早期に察知します。開いたリポジトリを確認できます。コマンドが誤ったディレクトリにアクセスしようとするのに気づきます。疑わしいインストールを止めることができます。ヘッドレスワークフローでは、これらの自然なチェックポイントが消失します。エージェントは、与えられた指示と環境のみを認識します。
だからこそ、適切な比較は「Claude Code を使う vs. 使わない」ではありません。「実マシン上の Claude Code」vs.「隔離された実行境界内の Claude Code」です。エージェントが自律的に行動できるようになると、ワークスペース自体が安全モデルの一部になります。
リスク領域はかなり具体的です：
| リスク領域 | サンドボックスなしで起こりうること | サンドボックスによる変化 |
|---|---|---|
| リポジトリのスコープ | エージェントが誤ったリポジトリ、ブランチ、または追跡されていないローカルファイルを編集する | 各タスクにスコープ指定されたチェックアウト、既知のベースコミット、使い捨てブランチが与えられる |
| シェル実行 | コマンドがホストマシンまたは共有ランナーに対して実行される | コマンドは隔離されたファイルシステムとプロセス境界内に留まる |
| 依存関係のインストール | npm、pip、その他のパッケージインストールがホスト上で任意のスクリプトを実行する |
パッケージインストールはポリシーとログ付きの使い捨て環境で行われる |
| シークレット | エージェントから見える環境変数に、広範な開発者認証情報や本番認証情報が含まれる可能性がある | タスクスコープのシークレットをサンドボックスセッションに限定できる |
| レビュー | 唯一の記録はチャット要約またはターミナル転記のみ | 差分、ログ、標準出力、標準エラー出力、成果物をレビュー用に取得できる |
Claude 固有ではないより広範なサンドボックス設計チェックリストについては、Coding Agent Sandbox: How to Run Agent-Generated Code Safely および Run Claude Code or Managed Agents in an Isolated Sandbox をお読みください。ここでの違いは、Claude Code にはすでに具体的な CLI ワークフローがあるため、インフラストラクチャの問題がより具体的になることです。つまり、ループ内に人間がいない場合、その CLI をどのように安全に実行するか、という問題です。
--dangerously-skip-permissions を使用すると何が変わるのか
このフラグは、多くのチームがサンドボックスについて疑問を持ち始める理由です。通常の対話型使用では、Claude Code はファイルの編集やツールの実行前に確認を求めることができます。無人自動処理では、承認プロンプトがフローを中断するため、Novita のドキュメントでは、claude-code テンプレート内で claude --dangerously-skip-permissions -p "<prompt>" を使用したヘッドレスパターンを示しています。
これは、そのフラグが定義上安全ではないという意味ではありません。安全レイヤーが移動したという意味です。
--dangerously-skip-permissions を使用する場合、次のことを想定すべきです：
- Claude Code がファイルを即時に編集する可能性がある。
- Claude Code がコマンドを即時に実行する可能性がある。
- Claude Code がレビューのために一時停止することなく、マルチステップタスクを続行する可能性がある。
正しい対応は、実際のワークステーションでこのフラグを使用して最善を期待することではありません。正しい対応は、ワークスペース、リポジトリ、コマンド、シークレット、ネットワーク範囲がすでに制約されているサンドボックス内でのみ使用することです。サンドボックス境界が、爆発半径を縮小する場所になります。
そのため、この設定を文書化する際には、表現を正確に保つ必要があります。--dangerously-skip-permissions は、ローカルマシンの利便性のための推奨事項ではありません。ヘッドレス自動化のためのサンドボックス限定の運用パターンです。ワークフローが依然として Claude Code を開発者のラップトップ、共有バスション、または本番環境に近いランナーに向けているならば、人間による承認プロンプを削除しただけで、それを置き換えるべきインフラ制御を追加していないことになります。
その環境でパッケージインストールを信頼するかどうかをチームがまだ決定している場合は、この記事を How to Safely Allow Package Installs in AI Agent Sandboxes および AI Agent Sandbox Isolation Boundary Checklist と併せてお読みください。
Novita の claude-code テンプレートを本番ワークフローにマッピングする方法
Novita のドキュメントの有用な点は、抽象的で終わらないことです。本番ワークフローに必要な実際の仕組みを示しています。
1. ヘッドレス -p モードと --print モード
ドキュメントでは、Claude Code を非対話型の -p モードで使用して、実行がプロンプトを受け入れ、結果を出力し、終了できるようにしています。これは、ヘッドレス自動化にクリーンなプログラム上の契約が必要であるため重要です。人間のセッションに接続された長時間稼働する対話型ターミナルは望ましくなく、開始、観察、破棄可能なタスク指向の実行が望ましいのです。
これは、Claude Code CLI Documentation で説明されているのと同じ区分です。対話型 Claude Code は人間のドライバー向けであり、-p と構造化出力を組み合わせたものが、スクリプトやエージェントパイプラインで CLI を有用にするものです。
2. ~/.claude/settings.json によるカスタムモデルルーティング
Novita のドキュメントは、多くのチームが見逃しがちな実用的な詳細も示しています。それは、サンドボックス内に ~/.claude/settings.json を書き込み、env ブロックを介して Claude Code が API トークン、ベース URL、モデル設定を受け取るようにする方法です。このパターンが重要な理由は2つあります。
第一に、ランタイムを自己完結型に保ちます。サンドボックスは、タスクに必要な正確な Claude 向け設定で起動でき、開発者のマシンに存在する設定を継承する必要がありませ。
第二に、明示的な環境制御をサポートします。ワークフローが Claude Code をカスタムバックエンドで使用する場合、サンドボックス設定は、隠された個人のシェル状態ではく、レビューされた設の一部になりま。
3. スコープ設定された認証情報による実際のリポジトリクローン
ドキュメントは、ターゲットパス、浅いクローン深さ、プライベートリポジトリ用の GitHub トークンを指定した sandbox.git.clone(...) を示しています。これはマイナーな便利機能ではありません。再現可能なタスクワークスペースと、あいまいなディレクトリで作業するエージェントとの違いです。
本番環境で使用する場合、より安全なパターンは次のとおりです：
- タスクに必要なリポジトリのみをクローンする。
- ワークフローに再現性が必要な場合、開始参照またはコミットを固定する。
- エージェントの変更にはタスクブランチを使用する。
- タスクに必要なものだけを読み取りまたは書き込みできる、スコープ設定された Git 認証情報を渡す。
リポジトリにまだ書き込みアクセスが必要ないのであれば、エージェントが最終的に PR を開く可能性があるという理由だけで、書き込みアクセスを与えてはいけません。
4. マルチステップ作業のための構造化出力と session_id
ドキュメントは、もう1つの有用なパターンを示しています。--output-format json で Claude Code を起動し、返された session_id をパースし、--resume <session_id> で続行する方法です。これにより、ワンショットのコード編集が、プログラムで管理可能なマルチステップワークフローに変わりま。
これは、次のようなタスクに適しています：
- ステップ 1：リポジトリを検査し、リファクタリング計画を作成する
- ステップ 2：同じセッションを再開し、一部を実装する
- ステップ3：再開して、追跡検証またはクリーンアップを実行する
重要なベストプラクティスは「常に resume を使用する」ことではありません。「意図的に resume する」ことです。ワークフローが連続性の恩恵を受ける場合は、同じサンドボックスで同じセッションを再開します。タスクが独立してレビュー可能であるべき場合は、状態を暗黙的に引き継ぐ代わりに、新しいサンドボックスを開始します。
5. タスク終了後にワークスペースを強制終了する
Novita のドキュメントは、サンドボックスを強制終了して例を終えています。これはまさに本番環境で望ましい習慣です。ヘッドレスコーディングエージェントは、古いワークスペース、バックグラウンドプロセス、または残存する認証情報を静かに蓄積すべきではありません。使い捨て環境は、履歴のある謎のマシンよりも推論が容易です。
そのランタイムモデルのより大きなアーキテクチャ全体像については、Building a Coding Agent with Novita’s Agent Sandbox が適切な関連記事です。
Claude Code サンドボックスのベストプラクティスチェックリスト
以下のチェックリストは、ドキュメントのワクフローの本番環境版です。Novita のテンプレートの仕組みを維持しつつ、自動パイプラインが通必要とする制御を追加しています。
- タスクごとに1つのサンドボックス： 複数の無関係なタスクを1つの長期稼働 Claude Code 環境にポイントしないでください。新しいワークスペースにより、開始リポジトリの状態が明確になり、後片付けが容易になります。
- スコープ設定された Git アクセス： Claude Code がリポジトリのクローンと検査のみを必要とする場合は、読み取り専用トークンを使用します。ブランチをプッシュする必要がある場合は、そのリポジトリとワークフローにスコープ設定されたトークンを使用します。継承された個人認証情報は避けてください。
- サンドボックス化されたパッケージインストール： Claude Code は、失敗するビルドやテストを再現するために依存関係を必要とすることがよくあります。それは問題ありませんが、イストールはサンドボックス内で、ログとポリシーとともに行われるべきであり、オペレータのマシン上ではありません。ロックファイルの変更は、他のコード変更と同様にレビューしてください。
- シェル出力を証拠として扱う： 標準出力、標準エラー出力、終了コード、および実際に実行されたコマンドをキャプチャします。エージェントからの最終サマリは有用ですが、それだけではレビューには十分ではありません。
- デフォルトで本番シークレットなし： 短命またはステージングのみの認証情報を優先します。リポジトリを読み取り、コマンドを実行できるコーディングエージェントは、デフォルトで広範なクラウド管理トークンや本番データベース認証情報を必要としません。
- 結果だけでなく差分をレビューする： ヘッドレスでの成功は、Claude Code が与えられたループを完了したことのみを意味します。変更が正しい、または出荷準備ができていることを意味するわけではありません。変更されたファイル、依存関係の変更、コマンド出力、および生成された成果物をレビューしてください。
--dangerously-skip-permissionsはサンドボックスローカルに保つ： これはセットアップにおいて最も重要な運用ルールです。このフラグは、隔離された使い捨てワークスペース内に属します。実際のマシンに対して無人で Claude Code を実行するためのショートカットとして使用すべきではありません。- 実行とリリースを分離する： Claude Code がパッチの検査、編集、テスト、準備を行うことは許可されても構いません。しかし、それがマージ、公開、デプロイの決定を所有するべきではありません。それらのアクションは、人間または明示的なポリシーゲートの背後に保ってください。
- 意図的に再開する： タスクが連続性の恩恵を本当に受ける場合に
--resume <session_id>を使用します。再現性のクリーンテストが必要な場合、または1つのタスクが別のタスクの状態を継承すべきでない場合は、サンドボックスをリセットします。 - プロバイダ全体の表を比較する： このワクフローをホスティングする場所を選んでいるならば、環境が Claude Code を起動できるかどうかだけを見るのではなく、セッションライフサイクル、リポジトリの使いやすさ、ログ、一時停止と再開の動作、運用上のトレードオフを比較してください。その観点では、E2B vs. Daytona: AI Agent Sandbox Comparison および Novita Sandbox: A Cost-Effective Alternative to E2B Pro with Seamless Compatibility が関連する比較記事です。
避けるべき一般的な間違い
最も一般的な Claude Code サンドボックスの間違いは、概念的なものではなく、運用上のものです。
間違い1：ドキュメントの例を完全な本番運用ポリシーとして扱う
ドキュメントは、claude-code テンプレートを正しく起動する方法を示しています。それらがあなたの完全なレビュー、ネットワーク、またはシークレット管理ポリシーになろうとしているわけではありません。構文とランタイムの仕組みにはそれらを使用し、その後、独自のリポジトリと承認の境界を追加してください。
間違い2：開発者のワークステーションを「サンドボックス」として再利用する
ラップトップのターミナルから Claude Code を実行することは、有効な開発者ワークフローです。それは、無人自動化のための使い捨てで隔離されたランタイムとは同じではありません。
間違い3：セッション状態を暗黙的に残す
--resume を使用する場合、どのような状態を前方に運んでいるのか、そしてその理由を知ってください。答えが「よくわからないが、便利だったから」である場合、より困難なレビュー問題を生していま。
間違い4：実際のシークレットと探的コード作業を混ぜる
サンドボックスは、爆半半径を減らすためにありま。ワクスベースが依然として広範な認証情報で本番システムにアクセスできる場合、最も要な境を弱めているこになりま。
間違い5：成功した実を証拠よりも信頼する
エージェントはタスクを完了しても、誤った変更を加えたり、誤ったファイルに触れたり、望まない依存関係を追加したりする可能性があります。ナラティブサマリだけでなく、差分とログをレビューしてください。
FAQ
--dangerously-skip-permissions は Claude Code に全く安全性がないことを味しますか？
それは、Claude Code がセッション内でインタラクティブな承認を待たなくなることを意味します。ヘッドレスワークフローにおける意図された安全レイヤーは、セッションを取り巻くサンドボックス境界です。つまり、隔離されたリポジトリ、制限された認証情報、サンドボックス内でのコマンド実行、キャプチャされたログ、およびマージ前の人間によるレビューです。
すべての Claude Code 自動処理は新しいサンドボックスで実行すべきですか？
新しいサンドボックスは、独立したタスクにとって最もクリーンなデフォルトです。再開ベースのワークフローは、同じマルチステップタスクが連続性を必要とする場合に有用ですが、状態は意図的でレビュー可能であるべきであり、偶発的であってはなりません。
Claude Code はサンドボックス内でパッケージを安全にインストールできますか？
より安全にすることは可能ですが、自動的に安全になるわけではありません。パッケージポリシー、ロックファイルレビュー、スコープ設定されたネットワークアクセス、および監査ログを使用してください。パッケージインストールは、無人コーディングワークフローにおいて最もリスクの高いステップの1つです。
Novita のドキュメントページはワークフローを実装するのに十分ですか？
リリースされたテンプレート構文とサポートされている Claude Code の仕組み（ヘッドレス実行、settings.json 設定、sandbox.git.clone、JSON 出力、セッション再開）には十分です。本番展開には、そのランタイムに関する独自のレビュー、認証情報、およびポリシー決定が依然として必要です。
