Claude Codeのサンドボックスベストプラクティスは、1つのルールから始まります。Claude Codeが各ステップを人間が承認することなくファイルの編集やコマンド実行を行える場合、それはノートパソコンや共有CIランナー上ではなく、隔離されたワークスペース内で実行されるべきです。これはヘッドレスモードではさらに重要です。なぜなら、ヘッドレス実行の要点は、エージェントが人間が「allow」をクリックするのを待つことなく、ファイル編集、シェルコマンド、依存関係インストールを続行できることだからです。NovitaのClaude Codeサンドボックスガイドは、正確なテンプレートコマンドとフラグの信頼できる情報源です。この記事では、チームが次に必要とする部分に焦点を当てます：そもそもなぜClaude Codeをサンドボックス化するのか、そうしない場合に何が問題になるのか、実際のワークフローに組み込む前にテンプレートに追加すべき本番環境の制御とは何か。
なぜClaude Codeはヘッドレスモードでサンドボックスが必要なのか
Claude Codeが有用なのは、コードをドラフトするだけではないからです。ファイルを読み取り、ファイルを編集し、シェルコマンドを実行し、テスト出力を確認した後に反復処理を行います。その同じ能力こそが、インタラクティブな開発者セッションから無人自動化に移行する際に、サンドボックスが必要となる理由です。
ローカルターミナルでは、人間は通常、悪いアイデアを早期に発見します。開いたリポジトリが見えます。コマンドが間違ったディレクトリを参照していることに気づきます。怪しいインストールを停止できます。ヘッドレスワークフローでは、これらの自然なチェックポイントが消えます。エージェントは、あなたが与えた指示と環境だけを見ます。
そのため、正しい比較は「Claude Code vs. 非Claude Code」ではありません。「実機上のClaude Code」と「隔離された実行境界内の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を書き込んで、Claude Codeがenvブロックを介してAPIトークン、ベースURL、モデル設定を受け取るようにします。このパターンは2つの理由で重要です。
第一に、ランタイムを自己完結型に保ちます。サンドボックスは、開発者のマシンに存在するものを継承するのではなく、タスクが必要とする正確なClaude向け設定で起動できます。
第二に、明示的な環境制御をサポートします。ワークフローがカスタムバックエンドでClaude Codeを使用する場合、サンドボックス設定は、非表示の個人用シェル状態ではなく、レビューされたセットアップの一部になります。
3. スコープ指定された認証情報による実際のリポジトリクローン
ドキュメントでは、sandbox.git.clone(...)がターゲットパス、浅いクローン深度、プライベートリポジトリ用のGitHubトークンを示しています。これは小さな便利機能ではありません。再現可能なタスクワークスペースと、あいまいなディレクトリで作業するエージェントとの違いです。
本番使用では、より安全なパターンは以下の通りです：
- タスクに必要なリポジトリのみをクローンする。
- ワークフローが再現性を必要とする場合、開始refまたはコミットを固定する。
- エージェントの変更にはタスクブランチを使用する。
- タスクが必要とするものだけを読み取りまたは書き込みできる、スコープ指定されたGit認証情報を渡す。
リポジトリがまだ書き込みアクセスを必要としない場合、エージェントが最終的にPRを開くかもしれないという理由だけで書き込みアクセスを与えないでください。
4. マルチステップ作業のための構造化出力とsession_id
ドキュメントは2つ目の便利なパターンを示しています。Claude Codeを--output-format jsonで起動し、返されたsession_idを解析し、--resume <session_id>で続行します。これにより、ワンショットのコード編集が、プログラムで管理できるマルチステップワークフローに変わります。
これは次のようなタスクに適しています：
- ステップ 1：リポジトリを調査し、リファクタリング計画を作成する
- ステップ 2：同じセッションを再開し、1つのスライスを実装する
- ステップ 3：再度再開してフォローアップの検証またはクリーンアップを実行する
重要なベストプラクティスは「常にresumeを使用する」ではありません。「意図的にresumeする」です。ワークフローが継続性の恩恵を受ける場合は、同じサンドボックスで同じセッションを再開します。タスクを独立してレビュー可能にする必要がある場合は、暗黙的に状態を引き継ぐのではなく、新しいサンドボックスを起動します。
5. タスク後にワークスペースを強制終了する
Novitaのドキュメントは、サンドボックスを強制終了して例を終了しています。これはまさに本番環境で身につけたい習慣です。ヘッドレスコーディングエージェントは、古いワークスペース、バックグラウンドプロセス、残存する認証情報を静かに蓄積すべきではありません。使い捨て環境は、履歴のある謎のマシンよりも推論が容易です。
そのランタイムモデルに関するより大きなアーキテクチャ全体像が必要な場合は、Building a Coding Agent with Novita’s Agent Sandbox が適切な関連記事です。
Claude Codeサンドボックスベストプラクティスチェックリスト
以下のチェックリストは、ドキュメントのワークフローの本番バージョンです。Novitaテンプレートの正確な仕組みを維持し、自動パイプラインが通常必要とする制御を追加しています。
- 1タスクにつき1サンドボックス： 複数の無関係なタスクを1つの長期稼働Claude Code環境に向けないでください。新しいワークスペースは、開始リポジトリ状態を明確にし、後片付けを容易にします。
- スコープ指定されたGitアクセス： Claude Codeがリポジトリのクローンと調査のみを必要とする場合は、読み取り専用トークンを使用します。ブランチをプッシュする必要がある場合は、そのリポジトリとワークフローにスコープ指定されたトークンを使用します。継承された個人認証情報は避けてください。
- サンドボックス化されたパッケージインストール： Claude Codeは、失敗したビルドやテストを再現するために依存関係を必要とすることがよくあります。それは問題ありませんが、インストールはオペレーターのマシンではなく、ログとポリシーを持つサンドボックス内で行われるべきです。ロックファイルの変更は、他のコード変更と同様にレビューしてください。
- シェル出力を証拠として扱う： 標準出力、標準エラー出力、終了コード、実際に実行されたコマンドをキャプチャします。エージェントからの最終サマリーは有用ですが、それだけではレビューに十分ではありません。
- デフォルトの本番シークレットはなし： 短命またはステージング専用の認証情報を優先します。リポジトリを読み取り、コマンドを実行できるコーディングエージェントは、デフォルトで広範囲のクラウド管理者トークンや本番データベース認証情報を必要としません。
- 結果だけでなく差分をレビューする： ヘッドレスの成功は、Claude Codeが与えられたループを終了したことを意味するだけです。変更が正しい、または出荷準備ができていることを意味するわけではありません。触れたファイル、依存関係の変更、コマンド出力、生成されたアーティファクトをレビューしてください。
--dangerously-skip-permissionsをサンドボックスローカルに保つ： これはセットアップにおける最も重要な運用ルールです。このフラグは、隔離された使い捨てワークスペース内に属します。実際のマシンに対して無人Claude Codeを実行するためのショートカットであってはなりません。- 実行とリリースを分離する： Claude Codeは、パッチの調査、編集、テスト、準備を許可される場合があります。それは、マージ、公開、デプロイメントの決定も所有すべきという意味ではありません。これらのアクションは人間または明示的なポリシーゲートの後ろに置いてください。
- 意図的にresumeする： タスクが継続性から真に利益を得る場合に
--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出力、セッション再開）には十分です。本番展開には、そのランタイムに関する独自のレビュー、認証情報、ポリシー決定が依然として必要です。
