セルフホストされた環境のクイックスタート
セルフホストされた環境を初めてセットアップします。Claude Code をインストールし、環境を作成し、ランナーを起動し、セッションをルーティングします。
セルフホストされた環境は、Claude Code のクラウドセッションを、組織が運用するインフラストラクチャ上で実行し、デプロイするランナープロセスによって実行されます。このクイックスタートは最初のセットアップを行います。最小限の構成は、単一ホスト上の 1 つのランナーで 1 つのテストセッションを実行することです。2 つのステップがあります。環境とランナーを作成し、セッションをルーティングする、その後実行中のセッションにターミナルからメッセージを送信する。2 つのサーフェス間を移動します。claude.ai は環境の作成、ステータスの確認、セッションのルーティング用で、ホスト上のターミナルはランナーが行うすべてのことに使用します。
終了時には、Cloud environments 管理ページに環境があり、ランナーが仕事をポーリングしており、セッションがホスト上で実行されています。実際のリポジトリまたは内部システムを接続する前に、本番環境へのデプロイを実行してください。これはセキュリティ体制、エグレス制御、git 認証情報、およびオーケストレーションをカバーしています。
前提条件
組織とロール
claude.ai 側には以下が必要です。
- セルフホストされた環境を許可は、Cloud environments 管理ページでオーナーによってオンにされます。新規ボタンはそれがオンになるまで表示されません。ロールを保持していない場合、保持している人が環境を作成してシークレットを渡すことができます。このページのランナーとターミナルのステップには claude.ai ロールは不要です。ステップが管理 UI でステータスをチェックする場合、ランナー自身のログ行が同じシグナルを提供します。
- 組織のGitHub 接続。開発者がセッションを開始するときにリポジトリを選択できるようにします。
ホストとネットワーク
ランナーホストには以下が必要です。
api.anthropic.com、claude.aiおよび以下のインストールステップ用のダウンロードホストへのアウトバウンド HTTPS、および git ホストへのクローン用の Linux または macOS ホストまたはコンテナ。ネットワーク要件テーブルに完全なリストがあります。Windows はランナーホストとしてサポートされていません。代わりに Linux コンテナでランナーを実行してください。セッションは claude.ai のブラウザから開始されるため、開発者ワークステーションは影響を受けません。- 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 を設定は各フロアを記載しています。
ホストの準備ができていることを確認します。
claude self-hosted-runner --help
準備ができたホストはランナーの使用テキストを出力し、--environment-secret-file などのフラグをリストします。2.1.224 より古いバージョンでは、コマンドは代わりに一般的な claude --help 出力を出力します。claude update でアップグレードするか、latest チャネルから再インストールしてください。
環境とランナーをセットアップする
Claude Code には、ガイド付きセットアップが含まれています。これは、管理 UI で環境を作成する手順を案内するインタラクティブな Claude Code セッションで、保存したシークレットファイルを使用してローカルランナーを起動し、ランナーが登録されたことを確認し、./runner-setup/CHEAT-SHEET.md にチートシートを書き込みます。claude auth login でサインインしたマシンで実行してください。このとき、Owner ロールを持つアカウントを使用する必要があります。API キーまたはサードパーティのモデルプロバイダーでは利用できません。インタラクティブセッションが不可能なホストでは、代わりに以下の手動手順を使用してください。まず、バージョンチェックが成功したことを確認してください。2.1.224 より古いバージョンでは、このコマンドはガイド付きセットアップではなく、単語をプロンプトとして使用する通常の Claude セッションを開始します。ガイド付きセットアップを開始するには、setup サブコマンドを実行してプロンプトに従ってください。
claude self-hosted-runner setup
代わりに手動でセットアップするには、以下の手順に従ってください。
環境を作成する
管理設定の Cloud environments ページ に移動します。Self-hosted environments の下で、New を選択し、環境に名前を付けて、Create を選択します。ウィザードの 2 番目のステップで、Copy environment key を選択して環境シークレットをコピーします。管理 UI はこれを環境キーとしてラベル付けしています。claude.ai はシークレットを 1 回だけ表示し、後で取得することはできません。シークレットは作成から 365 日後に期限切れになります。環境の ccpool_... ID は詳細ダイアログに表示されたままになります。これは、トークン検証の aud チェックと、CI からのテストセッションのディスパッチに必要です。
シークレットを紛失した場合、またはローテーションが必要な場合は、環境の Configuration タブから新しいシークレットを作成し、新しいシークレットをランナーにロールアウトしてから、古いシークレットを取り消します。取り消されたシークレットを保持しているランナーは、次の認証済みポーリングに失敗して終了し、poll auth failed をログに記録します。オーケストレーターは新しいシークレットでランナーを再起動します。
ランナーを起動する
シークレットディレクトリを作成します。このステップと次のステップは /etc/claude パスに root が必要です。ランナープロセスが読み取ることができるパスであれば、どのパスでも機能するため、異なるパスを使用する場合は、両方のコマンドと --environment-secret-file 値を一緒に調整してください。
mkdir -p /etc/claude
環境シークレットをファイルに書き込みます。以下のコマンドはターミナルから読み取るため、シークレットはシェル履歴から除外されます。コピーした値を貼り付け、Enter キーを押してから Ctrl-D を押します。サブシェルの umask により、ファイルは所有者のみが読み取ることができます。
(umask 077 && cat > /etc/claude/environment-secret)
ベースディレクトリを選択し、以下のランナーコマンドの <writable-dir> を、ランナーが書き込みまたは作成できる絶対パスに置き換えます。ランナーは起動時にディレクトリを作成し、リポジトリをチェックアウトして、その下にセッションごとのディレクトリを作成します。--base-dir がない場合、/workspace を使用します。これは、そのディレクトリが既に存在し、書き込み可能であるか、ランナーを root として起動する場合にのみ機能します。
ランナーがパスを作成または書き込みできない場合、起動時にディレクトリを名前として指定するエラーで終了し、登録されません。トラブルシューティングを参照してください。
次に、--environment-secret-file と --base-dir を使用してランナーを起動します。ランナーは環境に登録され、作業のポーリングを開始します。ランナーが終了した場合は、手動で再起動してください。本番環境のデプロイメントは、終了したランナーを再起動するオーケストレーターの下でランナーを実行します。通常、再起動ごとに新しいファイルシステムを使用します。事前にウォームアップされたチェックアウトを再利用するは、サポートされている永続ディスクセットアップについて説明しています。
claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
ランナーが表示されることを確認する
Cloud environments ページに戻ります。環境のステータスは、ランナーが起動してから数秒以内に No runners deployed から Healthy に変わります。環境を開いて Activity を選択すると、ランナー自体が表示されます。
セッションを環境にルーティングする
claude.ai/code でセッションを開始し、環境ピッカーから環境を選択します。セルフホスト環境は Anthropic ホスト環境と並んで表示されます。ランナーは、ホストが既に持っている git 認証情報を使用してクローンを作成するため、このホストが既にクローンできるリポジトリ、または公開リポジトリを選択してください。本番環境のプライベートリポジトリの認証情報オプションは、git を設定するに記載されています。次に利用可能なランナーがキューに入ったセッションを取得し、Picked up session <session-id> をアクティブカウントと容量とともにログに記録します。ランナー自身の出力からどのホストがセッションを取得したかを確認できます。claude.ai/code でセッションの動作を監視し、Claude の返信を読んでください。セッションがキューに入ったままの場合は、トラブルシューティングを参照してください。
ランナーは設計上、アクティブセッションが終了すると終了します。ランナーのライフサイクルを参照してください。本番環境では、終了時にランナーを再起動し、ランナーが起動直後に終了し続ける場合は再起動間の待機時間を長くするオーケストレーターの下にデプロイしてください。本番環境へのデプロイとランナーが終了する場合を参照してください。
実行中のセッションにフォローアップメッセージを送信する
セッションが環境で実行されたら、claude auth login でログインしているマシンの claude CLI からフォローアップを送信します。コマンドはセッションを開始したマシンから実行する必要はありません。コマンドは 1 つのメッセージを投稿します。
claude -p "your message" --cloud <session-id>
<session-id> については、ベアの session_... または cse_... ID またはセッションの claude.ai/code URL を渡します。成功した送信は Sent to cloud session. をセッション ID とビューリンク付きで出力します。受け入れられた ID フォーム、JSON 出力、アカウントとポリシー要件、およびエラーリファレンスはCLI からフォローアップを送信にあります。コマンドは Anthropic ホストされたセッションに対して同じように機能するためです。
次のステップ
- 本番環境へのデプロイ。デプロイメントを強化し、エグレスを制御し、git 認証情報を設定し、Kubernetes または Compose の下でフロートを実行します。
- セッションをカスタマイズ。ラッパースクリプト、ライフサイクルフック、オンデマンドランナー、MCP サーバー、および権限。
- エンドツーエンドをテスト。セッションをディスパッチして Claude の返信を読む CI スモークテスト。