前提条件
開始する前に、以下が揃っていることを確認してください。- Owner によってセルフホスト環境が有効化された Claude Team または Enterprise の組織。Anthropic の前提条件を参照してください。
- Claude に接続済みで、ご自身のアカウントからアクセスできる GitHub リポジトリ。まずはテスト用のリポジトリで試してください。GitHub の接続手順については、Claude Code web アプリのドキュメントを参照してください。
SANDBOX_USERアイデンティティとアクセス管理 (IAM) action が付与された CoreWeave API アクセストークン、およびこのセクションで説明するリソースをまかなえるサーバーレスキャパシティ。このレシピでは CoreWeave 認証を明示的に使用します。- Git、Python 3.11 以降、および
uvがインストールされた Linux または macOS のコンピューター
レシピを使ったクイックスタート
Claude 環境を作成してオーケストレーターをデプロイし、ワーカーの出力を確認してからデプロイメントを停止します。Claude 環境を作成する
Anthropic の環境の設定の手順に従います。Cloud environments 管理ページで、Owner が Allow self-hosted environments を有効にし、Self-hosted environments で環境を作成します。 この Claude Code クラウド環境は、Owner が claude.ai の管理設定で作成します。Claude Managed Agents では、Claude Console で作成した別の環境とキーを使用します。 環境キーとそのccpool_... ID を控えておいてください。管理ページにアクセスできない場合は、Owner にこれらを提供するよう依頼してください。ID は環境を識別するもので、キーはオーケストレーターの認証に使用されます。以降のステップでは、レシピによってオーケストレーターとワーカーのインフラストラクチャーがデプロイされます。
レシピをインストールする
レシピをローカルにインストールし、オーケストレーターに必要な認証情報を設定します。.env ファイルを編集し、両方の変数を設定します。
.env ファイルは非公開にし、バージョン管理に含めないでください。代わりに、シークレットマネージャーからこれらの変数を注入することもできます。既存の環境変数は .env ファイルの設定より優先されます。
オーケストレーターをデプロイする
[ENVIRONMENT-ID] をご自身の ccpool_... ID に置き換えます：
Connected を出力します。セットアップには数分かかる場合があります。タイムアウトしても、クリーンアップが行われたとは限りません。再試行する前に status と logs を確認してください。
ローカルの .deployment.json ファイルは削除せずに保持してください。このファイルには、デプロイメントの管理に必要な ID と設定が記録されており、認証情報は含まれていません。以降のコマンドは、レシピのディレクトリから実行してください。
タスクを送信する
Claude Code の Web アプリで、組織、接続済みのリポジトリ、セルフホスト環境を選択します。検証ステップで使用するファイルを作成するため、次のプロンプトを一字一句そのまま送信します。結果を検証する
ターミナルで、デプロイメントの一覧を表示します。Connected: True と、サンドボックス ID を含む Worker: 行が出力されることを確認してください。Claude の処理が終了したら、次のコマンドの [WORKER-ID] をその ID に置き換えます。
CWS_CLOUD_OK です。この手順では、Claude の応答とは別に、Sandboxes SDK を使用してサンドボックス内のファイルを直接確認します。ワーカーがアイドル状態になって停止する前に読み取ってください。別のタスクを送信した場合は、そのタスクが作成したファイルを読み取ってください。
クリーンアップ
結果を保存したら、デプロイメントを停止します:.deployment.json ファイルを削除します。実行中のタスクは中断され、それらのサンドボックスにのみ保存されているファイルは破棄されます。Claude 環境は残るため、後のデプロイメントで引き続き利用できます。
インテグレーションの仕組み
このレシピは 2 つのロールをデプロイします。
ワーカーは、リポジトリへのアクセスに Anthropic git プロキシ を使用します。このレシピは、ローカルの Claude ログイン情報や GitHub トークンをワーカーにコピーしません。ただし、モデルへのリクエスト、プロンプト、応答、ツール結果は引き続き Anthropic を経由します。
フックは Anthropic のオンデマンドランナー規約 に従い、ワークロードを非同期で送信したうえで、使い捨てのワークオーダーを使用して登録します。オーケストレーターのプロセスが再起動した後に重複送信が発生しないよう、このレシピはオーダー ID をオーケストレーターのディスクに記録します。作成の成否が不明な場合はフェイルクローズとなり、再試行する前に状況を確認する必要があります。
ワーカーはプロセスラッパー配下で実行されます。このラッパーは終了コードを記録し、プロセスを再試行することなくサンドボックスを完了させます。起動に失敗した場合はログを確認してください。サンドボックスが完了しただけでは、タスクが成功したとは限りません。
このレシピでは、Claude Code のバージョンを
2.1.284、Sandboxes SDK のバージョンを 1.14.2 に固定しています。各サンドボックスは python:3.12-bookworm から起動し、ブートストラップ時に Git と Claude をインストールします。ワーカーの起動処理には、スケジューリング、インストール、登録、リポジトリのチェックアウトが含まれます。
デプロイメントを設定する
deploy の実行時に、次のオプションを設定できます。
どちらの有効期間オプションも 1～720 時間の範囲で指定できます。アイドルタイムアウトは 10,080 分 (7 日) 以下で、かつワーカーの有効期間から 5 分を引いた値より短くする必要があります。オーケストレーターを 30 日間稼働させるには、デプロイ時に
--orchestrator-hours 720 を追加します。有効期間は作成後に延長できません。
1 つの Claude 環境で実行するレシピのデプロイメントは 1 つだけにしてください。このレシピは、オーケストレーターのサンドボックスを自動で置き換えません。レシピのスーパーバイザーは同じサンドボックス内で Claude Code オーケストレーターのプロセスを再起動するため、ローカルの順序台帳は保持されます。ただし、サンドボックスが失敗したり期限切れになったりすると、その台帳は失われます。デプロイメントを監視し、セッションの結果を保存したうえで、有効期限が切れる前に置き換えを計画してください。計画的に置き換える場合は、実行中の作業を終了し、stop を実行してから再デプロイします。送信が成功したかどうか不明な場合やホスト障害から復旧する際は、事前に保留中のセッションと既存のリソースを確認してください。
ツールチェーンを追加するには、レシピの bootstrap.sh スクリプト内のワーカー用の分岐を編集し、お使いのリポジトリでテストします。ライフサイクルフックとセッションの設定については、セルフホスト環境でセッションをカスタマイズするを参照してください。
セッションを監視する
接続、ワーカー、直近のログを確認します：status は、オーケストレーターの接続状態とおおよその有効期限を表示します。すべてのセッションがアイドル状態になり、アイドルタイムアウトが経過した後は、新しいセッションがキューに追加されていなければワーカー数は 0 になります。キャパシティが利用可能になると、新しいセッションによってワーカーが作成されます。フォローアップは、現在のワーカーが関連付けられている間、そのワーカー上で継続できます。
オーケストレーターの健全性リスナーは、そのサンドボックス内でのみ動作します。これらのコマンドは Sandboxes SDK を使用するため、パブリックエンドポイントは必要ありません。
ワーカーのインストール出力を確認するには、そのワーカーのログコマンドに --bootstrap を追加します。このログには、セットアップ完了後の Anthropic ランナーの出力も含まれます。
ワーカーが停止する前に結果を保存する
Anthropic ランナーは、アイドル状態のセッションを解放して終了します。また、サンドボックスのライフタイムが終了する 5 分前から終了処理を開始します。ただし、実行時間の長いターンは、有効期間の上限に達して強制的に中断される可能性があります。 残しておきたい作業は Claude にコミットしてプッシュするよう依頼し、GitHub でブランチを検証してください。テキストのアーティファクトは、レシピのread コマンドを使用し、その出力をローカルファイルにリダイレクトして保存します。このレシピでは、自動プッシュやスナップショットは設定されていません。解放後のフォローアップは新しいワーカーで実行される場合があるため、プッシュしていないファイルが残っていることを前提にしないでください。
その他のワークフローで使用できる永続化のオプションについては、ファイルシステムスナップショットを参照してください。Anthropic ランナーの解放時の動作については、Anthropic のランナーリファレンスを参照してください。
トラブルシューティング
外向きのトラフィックを制限する場合は、Anthropic ランナーのトラフィックに加え、Debian、PyPI、Claude のダウンロードサービスからのブートストラップ時のダウンロードも考慮してください。このレシピでは外向き通信の許可リストは設定しません。ネットワーク要件とセキュリティ強化については、Anthropic の本番デプロイメントに関するガイダンスを参照してください。
次のステップ
変更内容の検証や、他のインテグレーションの探索には、以下のリソースを使用してください。- レシピを変更した後は、オフラインチェックとライブチェックを実行してください。
- より詳細な診断には、Anthropic のエンドツーエンドテストを使用してください。
- その他のエージェントインテグレーションもご覧ください。