セルフホストされた環境は Team および Enterprise プランでパブリックベータ版です。利用可能性と制限事項は有効化パスをカバーしています。このページは最初のセッションを実行します。詳細はセルフホストされた環境を参照し、本番環境へのデプロイについては本番環境へのデプロイを参照してください。
前提条件
組織とロール
claude.ai 側には以下が必要です。- セルフホストされた環境を許可は、Cloud environments 管理ページでオーナーによってオンにされます。新規ボタンはそれがオンになるまで表示されません。ロールを保持していない場合、保持している人が環境を作成してシークレットを渡すことができます。このページのランナーとターミナルのステップには claude.ai ロールは不要です。ステップが管理 UI でステータスをチェックする場合、ランナー自身のログ行が同じシグナルを提供します。
- オーナーによってオンにされた GitHub コネクタと、各開発者自身の GitHub 接続。これにより、開発者はセッションを開始するときに github.com のリポジトリを選択できます。
ホストとネットワーク
ランナーホストには以下が必要です。api.anthropic.com、claude.aiおよび以下のインストールステップ用のダウンロードホストへのアウトバウンド HTTPS、および git ホストへのクローン用の Linux または macOS ホストまたはコンテナ。ネットワーク要件テーブルに完全なリストがあります。Windows はランナーホストとしてサポートされていません。代わりに Linux コンテナでランナーを実行してください。セッションは claude.ai のブラウザから開始されるため、開発者ワークステーションは影響を受けません。- テストセッション用のリポジトリ。公開リポジトリ、またはこのホストが認証情報を求められることなく HTTPS URL で既にクローンできるリポジトリを用意してください。ランナーはリポジトリの
https://URL をクローンするため、SSH キーだけでは不十分です。代わりに SSH 経由でクローンするには、プライベートネットワーク用に git URL を書き換えるを参照してください。 - NTP などで実時間に同期されたクロック。クロックが 5 分以上ずれていると認証が失敗します。トラブルシューティングを参照してください。
ランナーホスト上のソフトウェア
開始する前にホストにインストールしてください。- Claude Code v2.1.224 以降。標準インストール方法のいずれかを使用します。ランナーは標準
claudeバイナリの一部であり、以前のバージョンはself-hosted-runnerサブコマンドを認識しません。ネイティブインストーラーのデフォルトlatestチャネルは各リリースを公開直後に提供します。stableチャネル、Homebrewclaude-codecask、および安定版 apt、dnf、apk リポジトリは約 1 週間遅れます。フロートが実行する正確なバージョンをピンするには、特定のバージョンをインストールを参照してください。コンテナイメージについては、本番環境へのデプロイの Dockerfile を参照してください。 - Git 2.24 以降。デプロイページの一部の git オプションはより新しいバージョンが必要です。git を設定は各フロアを記載しています。
--environment-secret-file などのフラグをリストします。2.1.224 より古いバージョンでは、コマンドは代わりに一般的な claude --help 出力を出力します。claude update でアップグレードするか、latest チャネルから再インストールしてください。
環境とランナーをセットアップする
ガイド付きセットアップまたは手動手順のいずれかを使用します。ガイド付きセットアップは、インタラクティブな Claude Code セッションを開始して残りの手順を案内する単一のコマンドです。インタラクティブセッションが不可能なホストでは、代わりに手動手順を使用してください。Owner ロールを持つユーザーが環境を作成してそのシークレットを渡した場合も、手動手順を使用してください。ガイド付きセットアップには Owner としてのサインインが必要なためです。ガイド付きセットアップを実行する
ガイド付きセットアップは、管理 UI で環境を作成する手順を案内し、保存したシークレットファイルを使用してローカルランナーを起動し、ランナーが登録されたことを確認し、./runner-setup/CHEAT-SHEET.md にチートシートを書き込みます。実行する前に、サインインとバージョンを確認してください。
- サインイン：Owner ロールを持つアカウントを使用して
claude auth loginでサインインしたマシンで実行してください。API キーまたはサードパーティのモデルプロバイダーのみの場合、セッションは開始されますが、組織のチェックに失敗します。 - バージョン：バージョンチェックが成功したことを確認してください。2.1.224 より古いバージョンでは、setup コマンドはガイド付きセットアップではなく、単語をプロンプトとして使用する Claude セッションを開始します。
./runner-setup/CHEAT-SHEET.md に記載されたコマンドを使用してシェルでランナーを再度起動し、セッションを環境にルーティングしてください。
手動でセットアップする
claude.ai で環境を作成し、ホスト上のターミナルからランナーを起動してから、claude.ai に戻ってランナーが表示されることを確認し、セッションをランナーにルーティングします。Owner ロールを持つユーザーが既に環境を作成してそのシークレットを渡している場合は、ステップ 2 から開始してください。1
環境を作成する
管理設定の Cloud environments ページ に移動します。Self-hosted environments の下で、New を選択し、環境に名前を付けて、Create を選択します。ウィザードの 2 番目のステップで、Copy environment key を選択して環境シークレットをコピーします。管理 UI はこれを環境キーとしてラベル付けしています。claude.ai はシークレットを 1 回だけ表示し、後で取得することはできません。シークレットは作成から 365 日後に期限切れになります。環境の
ccpool_... ID は詳細ダイアログに表示されたままになります。これは、トークン検証の aud チェックと、CI からのテストセッションのディスパッチに必要です。シークレットを紛失した場合、またはローテーションが必要な場合は、環境の Configuration タブから新しいシークレットを作成し、新しいシークレットをランナーにロールアウトしてから、古いシークレットを取り消します。取り消されたシークレットを保持しているランナーは、次の認証済みポーリングに失敗して終了し、poll auth failed をログに記録します。オーケストレーターは新しいシークレットでランナーを再起動します。2
ランナーを起動する
シークレットディレクトリを作成します。このコマンドと次のコマンドは 環境シークレットをファイルに書き込みます。以下のコマンドはターミナルから読み取るため、シークレットはシェル履歴から除外されます。コピーした値を貼り付け、Enter キーを押してから Ctrl-D を押します。サブシェルの ベースディレクトリを選択し、以下のランナーコマンドの ランナーは環境に登録されると
/etc/claude を使用するため root が必要です。また、これらのコマンドで作成されるシークレットファイルは、コマンドを実行したユーザーのみが読み取ることができます。ランナーを別のユーザーとして実行する場合、ランナーは error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>') で終了します。その場合は、/etc/claude の代わりにランナーのユーザーが書き込めるディレクトリを使用して両方のコマンドをランナーのユーザーとして実行し、同じパスを --environment-secret-file に渡してください。ランナープロセスが読み取ることができるパスであれば、どのパスでも機能します。umask により、ファイルは所有者のみが読み取ることができます。<writable-dir> を、ランナーが書き込みまたは作成できる絶対パスに置き換えます。ランナーは起動時にディレクトリを作成し、リポジトリをチェックアウトして、その下にセッションごとのディレクトリを作成します。--base-dir がない場合、/workspace を使用します。これは、そのディレクトリが既に存在し、書き込み可能であるか、ランナーを root として起動する場合にのみ機能します。ランナーがベースディレクトリを作成または書き込みできない場合、登録されずに、起動時にそのディレクトリ名を示すエラーで終了します。トラブルシューティングを参照してください。次に、--environment-secret-file と --base-dir を使用してランナーを起動します。Registered: runner_id=<runner-id> をログに記録し、作業のポーリングを開始します。このコマンドで起動した場合、ランナーは設計上、ターンごとではなく 1 つのセッションを処理した後に終了します。さらに多くのセッションを処理するには、ランナーが終了するたびに再度起動してください。これが発生する状況とランナーがログに記録する内容については、ランナーが終了した場合を参照してください。3
ランナーが表示されることを確認する
Cloud environments ページに戻ります。環境のステータスは、ランナーが起動してから数秒以内に No runners deployed から Healthy に変わります。環境を開いて Activity を選択すると、ランナー自体が表示されます。管理ページにアクセスできない場合は、前のステップのランナーのログにある
Registered: runner_id=<runner-id> の行で同じことを確認できます。4
セッションを環境にルーティングする
claude.ai/code でセッションを開始し、環境ピッカーから環境を選択します。セルフホスト環境は Anthropic ホスト環境と並んで表示されます。リポジトリには、前提条件で用意したもの、つまり公開リポジトリ、またはこのホストが認証情報を求められることなく HTTPS URL で既にクローンできるリポジトリを選択してください。次に利用可能なランナーがキューに入ったセッションを取得し、
Picked up session <session-id> をアクティブカウントと容量とともにログに記録します。ランナー自身の出力からどのホストがセッションを取得したかを確認できます。claude.ai/code でセッションの動作を監視し、Claude の返信を読んでください。セッションが動作を開始しない場合は、表示される状況に応じて対処してください。- セッションがキューに入ったままになる：トラブルシューティングを参照してください。
- セッションが git エラーで開始に失敗する：エラーに git の
could not read Username forに続いて git ホストの URL が含まれている場合、ランナーにはそのホストの HTTPS 認証情報がありませんでした。- HTTPS 認証情報を指定する：git を設定するを参照してください
- 代わりに SSH でクローンする：ランナーホストに既に SSH キーがある場合は、プライベートネットワーク向けに git URL を書き換えるを参照してください
ランナーが終了した場合
このクイックスタートの途中でランナーが終了した場合は、再度起動してください。ランナーは自ら終了することがあります。- 実行中のものがなくなった：ログに
[runner:exit] account workload drained — exitingが表示されます。ランナーは、セッションを実行しなくなると設計上終了します。例：- セッションをアーカイブまたは削除した：ランナーを再度起動してください
- セッションの開始に失敗した：原因を修正してから、ランナーを再度起動してください
- 接続の喪失：ログに
runner record gone server-sideまたはpoll auth failedを含む[runner:fatal]の行が表示されます。ホストがスリープするなどしてランナーが Anthropic としばらく接続できなくなった場合、次に Anthropic に接続したときに終了することがあります。
実行中のセッションにフォローアップメッセージを送信する
セッションが環境で実行されたら、claude auth login でログインしているマシンの claude CLI からフォローアップを送信します。コマンドはセッションを開始したマシンから実行する必要はありません。コマンドは 1 つのメッセージを投稿します。
<session-id> については、ベアの session_... または cse_... ID またはセッションの claude.ai/code URL を渡します。成功した送信は Sent to cloud session. をセッション ID とビューリンク付きで出力します。受け入れられた ID フォーム、JSON 出力、およびアカウントとポリシー要件はCLI からフォローアップを送信にあります。コマンドは Anthropic ホストされたセッションに対して同じように機能するためです。
次のステップ
- 本番環境へのデプロイ。デプロイメントを強化し、エグレスを制御し、git 認証情報を設定し、Kubernetes または Compose の下でフロートを実行します。
- セッションをカスタマイズ。ラッパースクリプト、ライフサイクルフック、オンデマンドランナー、MCP サーバー、および権限。
- エンドツーエンドをテスト。セッションをディスパッチして Claude の返信を読む CI スモークテスト。