Claude Code self-hosted-runnerとは — 自社マシンでクラウドセッションを動かす

Claude Codeのクラウドセッションは、既定ではAnthropicが管理する仮想マシン上で動きます。v2.1.224で加わったセルフホスト環境(self-hosted environments)は、この実行場所を自社のマシンやコンテナに置き換える機能です。実行を担うプロセスは self-hosted-runner というサブコマンドで起動します。TeamとEnterpriseプランのパブリックベータとして提供され、社内ネットワークのデータベースやレジストリにセッションから直接アクセスできるようになります。

self-hosted-runnerが解決する課題

Claude Code on the webやモバイル・デスクトップアプリ、ターミナルの claude --cloud、定期実行のRoutinesは「クラウドセッション」の一種です。いずれもAnthropicのインフラ上で走ります。この仕組みは追加のインフラが要らない分、パブリックインターネットに公開していない社内サービスやプライベートなパッケージレジストリには手が届きません。

セルフホスト環境は、このクラウドセッションの実行場所だけを自社側に移します。開発者から見た操作感は変わりません。claude.ai/codeでセッションを始め、返信を読み、フォローアップを送るという流れはAnthropicホスト環境とほぼ同じです。違うのは、コードのチェックアウトやビルド成果物が自社が用意したマシンに残る点です。会話そのもの(プロンプト・応答・ツール結果)はモデル推論のためにAnthropicのAPIへ送られ、セッションの記録もAnthropic側に保存されます。どの端末からでもセッションを再開できるようにするための設計です。

3つの構成要素 — Environment・Runner・Session

セルフホスト環境は3つの要素で構成されます。

• Environment: セッションの送信先になる名前付きの単位。claude.aiの管理画面で作成し、複数のRunnerをまとめます
• Runner: 自社ネットワーク内のホストで動く常駐プロセス。セッションを受け取り、リポジトリをクローンして子プロセスを起動します
• Session: 開発者が1件始めるタスク本体。Runnerが起動する子プロセスとして実行されます

開発者がセッションを開始すると、Anthropicのコントロールプレーンがそのセッションを選んだEnvironmentのキューに置きます。空き容量のあるRunnerがそれを拾い、リポジトリをクローンして子プロセスを起動、イベントをHTTPS経由のストリーミングで返します。Runnerのポーリングはキューの確認とハートビートを兼ねており、約60秒止まると別のRunnerに再割り当てされます。

呼び方には注意点があります。APIのフィールドやメトリクス名、トークンのクレームでは、Environmentは pool という語で表記されます。IDの形式は ccpool_... です。管理画面とCLIのフラグでは environment に統一されていますが、--pool-secret-file のような古い名前のフラグも動作します(非推奨の警告付き)。ドキュメントを横断して読むときは同じものだと意識しておく必要があります。

Runnerは同時に1人のユーザーしか担当しません。最初に受け取ったセッションのアカウントにロックされ、以降は --capacity で指定した数まで同じアカウントのセッションだけを並行実行します。したがって、最小構成のRunner台数は、同時にアクティブになりうる利用者数と一致します。

導入前に確認すること

導入を検討する前に、次の制限を満たすか確認します。

利用料金は追加になりません。セルフホスト環境のセッションも、Anthropicホスト環境と同じ使用量として組織のClaude Code利用枠を消費します。増えるのは自社インフラの運用コストだけです。

ホスト側の要件も別にあります。RunnerはLinuxかmacOSのホストまたはコンテナで動かします。Windowsはホストとして未対応です。動かしたい場合はLinuxコンテナの中でRunnerを起動します。開発者のワークステーション自体は影響を受けません。セッションはブラウザやアプリから始まるためです。ホストの時刻もNTP等で同期しておく必要があります。認証は時刻が5分以上ずれると失敗します。

ソフトウェア面では、Runnerを動かすホストにClaude Code v2.1.224以降とGit 2.24以降を入れておきます。Runnerは claude バイナリの一部として配布されており、古いバージョンでは self-hosted-runner サブコマンド自体を認識しません。

セットアップの手順

最小構成では、1台のRunnerが1台のホストで動き、1件のテストセッションを処理します。対話セッションが使えるホストでは、次のガイド付きセットアップが使えます。

claude self-hosted-runner setup

Owner・管理者ロールを持つアカウントで claude auth login を済ませたホストで実行します。Environment作成、保存した秘密ファイルでのローカルRunner起動、登録確認までを対話形式のClaude Codeセッションが順に案内します。最後に ./runner-setup/CHEAT-SHEET.md へチートシートを書き出します。APIキーやサードパーティのモデルプロバイダーでは使えません。対話セッションが使えないホストでは、手動の手順に進みます。

ステップ1: Environmentを作る

管理画面の「Cloud environments」ページで、Self-hosted environments欄から新規作成し、名前を付けます。作成ウィザードの2番目の画面で環境キー(environment secret)をコピーします。このキーは一度しか表示されません。作成から365日で失効するので、失うか失効した場合は新しいキーを作り、Runnerに配布してから古いキーを無効化します。Environment自体のID(ccpool_... 形式)は詳細ダイアログにいつでも表示されます。

ステップ2: Runnerを起動する

秘密ファイルを保存するディレクトリを作り、コピーしたキーを書き込みます。

mkdir -p /etc/claude
(umask 077 && cat > /etc/claude/environment-secret)

ターミナルから貼り付けてEnterのあとCtrl-Dで確定すると、所有者だけが読めるパーミッションでファイルが作られます。次にRunnerがリポジトリをチェックアウトする作業ディレクトリを用意し、Runnerを起動します。

mkdir -p '<書き込み可能なディレクトリ>'
claude self-hosted-runner \
  --environment-secret-file '/etc/claude/environment-secret' \
  --base-dir '<書き込み可能なディレクトリ>'

--base-dir を省略すると既定値の /workspace が使われます。ただし起動できるのは、このディレクトリが事前に存在して書き込み可能な場合か、Runnerがroot権限で動いている場合に限られます。

ステップ3: 登録を確認しセッションを流す

管理画面に戻ると、Environmentのステータスが「No runners deployed」から「Healthy」に数秒で変わります。ActivityタブにはRunner自体も表示されます。claude.ai/codeで新しいセッションを始め、環境ピッカーで作成したEnvironmentを選びます。空き容量のあるRunnerがそれを拾い、「Picked up session」というログを出します。Runnerは手元にあるgitの認証情報でクローンします。最初に選ぶのは、そのホストが既にクローンできるリポジトリか公開リポジトリです。

CLIからフォローアップを送る

セッションが動き始めたら、ログイン済みの別のマシンからでもメッセージを送れます。

claude -p "your message" --cloud <session-id>

セッションIDは session_... や cse_... の形、またはclaude.ai/codeのURLをそのまま渡せます。成功すると「Sent to cloud session.」と表示され、閲覧用のリンクも出ます。

Runnerは設計上、担当していたセッションが終わると同時に終了します(--drain-grace-sec の既定値は 0)。本番運用では、Kubernetesなどのオーケストレーターの下でRunnerを動かし、終了のたびに新しいディスクで再起動させる構成が前提です。ホストが決まった時刻に強制終了される環境では --retire-at にepoch秒を渡すと、その時刻にRunnerが新規受付を止め、進行中のセッションを解放してから終了します。

よくあるつまずき

• バージョンが古くてもエラーにならない罠があります。v2.1.224より前のバージョンで claude self-hosted-runner --help を叩くと、一般の claude --help が表示されます。claude self-hosted-runner setup に至っては、その文字列をプロンプトにした通常のClaudeセッションが始まってしまいます。導入前に必ず --help の出力に --environment-secret-file などのフラグが並ぶか確認します
• --base-dir を省略した状態でrootでないユーザーとして起動すると、既定の /workspace が書き込み不可でRunnerが立ち上がりません
• 同じEnvironmentに属するRunner間で --base-dir や --capacity の値が揃っていないと、Environment全体の挙動が読みにくくなります
• 環境キーは作成時の一度しか画面に出ません。控え忘れると、キーを再発行してRunnerに配り直す作業が発生します
• NTP同期をしていないホストでは、5分を超えるズレで認証が失敗します。エラーメッセージからは原因が分かりにくい部類です

セルフホスト環境とRemote Controlの使い分け

名前が似ているぶん、選択肢は実行場所の違いで見分けます。

Claude Code on the webは無料プランでは使えず、Enterpriseもpremium seatまたはChat + Claude Code seatを持つユーザーに限られます。既定でオフのベータ機能である以上、大半のチームにとって最初の選択肢は変わらずAnthropicホスト環境です。自社ネットワークのデータベースやレジストリに直接アクセスしたいチーム、社内ツールを組み込んだイメージでセッションを動かしたいチームだけが、Runnerを自前で運用する価値を持ちます。

本番運用に進む場合は、git認証の設計・ネットワークの外向き通信(egress)の許可リスト・Kubernetesでの複数Runnerのオーケストレーションといった追加設定が必要です。Runnerは /healthz と /metrics をポート8080(既定)で公開しており、稼働状況やアクティブセッション数はPrometheus形式で取得できます。新しいRunnerイメージを本番に出す前には、スモークテストを組めます。--environment フラグでセッションを作成し、Hooksの仕組みにあるStop hookで最終応答をファイルに書き出させ、それを読み戻して確認します。

よくある質問

Bedrock・Google Cloud経由でモデル推論できますか

できません。セルフホスト環境のセッションは、Anthropic発行のセッション専用OAuthトークンで直接Anthropic APIに接続します。BedrockやGoogle CloudのAgent Platform、Microsoft Foundry、LLMゲートウェイを経由する構成はサポート対象外です。

AnthropicからRunnerへ接続してくることはありますか

ありません。Runnerとセッションのすべての通信はRunner側からの発信(outbound HTTPS)のみで成立します。Anthropicが自社ネットワークの内側に接続してくる経路はありません。

必要なRunner台数はどう見積もりますか

Runnerは最初に受け取ったセッションのアカウントに固定され、--capacity は同じアカウント内の同時セッション数を広げるだけです。別の利用者のセッションは受け付けないため、最小構成では同時にアクティブになりうる利用者の人数だけRunnerを用意します。全Runnerの空き容量が埋まっている間に届いた新しいセッションは、いずれかが空くまでキューで待機します。

--retire-atを設定すると、Runnerはどんな順序で終了しますか

--retire-at は、ホストが合図なしに決まった時刻へ強制終了される環境向けのフラグです。指定した時刻になると、Runnerはまず新規セッションの受け付けを止め、進行中のセッションを --release-idle-session-min と同じ経路で解放してから終了します。ターン実行中のセッションはそのターンが終わり次第解放され、ターンは終わっていてもバックグラウンドタスクが残っているセッションは最大60秒待ってから解放されます。解放されたセッションは、利用者が次のメッセージを送った時点で別のRunnerに引き継がれます。既定値が 0 の --drain-grace-sec は、セッション終了後にRunnerが同じアカウントのキューをどれだけ待ち受けるかを決める別の設定です(SIGTERM受信時に進行中のターンをどれだけ待つかは --drain-wait-sec が担います)。

GitHub Enterprise Serverのリポジトリにも対応していますか

チェックアウト自体はGitHubからのみです。ただしオンデマンドRunnerを起動するオーケストレーターには --scm-connector-host で設定するSCM connectorがあり、社内ネットワークからしか到達できないGitHub Enterprise Serverのホストに対して、リポジトリピッカーやブランチ解決といったクラウド側の処理を届けられます。connector IDはAnthropicのアカウントチームへの申請が必要です。

再キューされたセッションの作業内容は引き継がれますか

Runnerのポーリングが止まって約60秒が過ぎると、セッションは別のRunnerに再割り当てされ、新しいRunnerがリポジトリを改めてクローンします。元のRunnerのディスクに残っていた作業のうち、アイドル解放や再起動時のドレインのようにRunnerが自分でセッションを手放す場合は、コミット済みで未pushのブランチを --push-outcome-on-release がベストエフォートでpushするため引き継げます。ポーリング途絶による強制的な再割り当てでは、この解放処理自体が走りません。コミット前の変更(作業ツリーの差分)は、いずれの場合も引き継がれません。

まとめ

self-hosted-runnerは、Claude Codeのクラウドセッションの実行場所を自社のマシンやコンテナに移す、Team・Enterprise向けのパブリックベータです。構成要素はEnvironment・Runner・Sessionの3つです。Runnerは同時に1ユーザーだけを担当し、--capacity まで並行実行します。

既定はオフで、Owner・管理者が管理画面から有効化するところから始まります。ゼロデータ保持を選んでいる組織や、Bedrock・Google CloudのAgent Platform・Microsoft Foundry経由でモデル推論をしている組織は対象外です。GitHub以外のリポジトリや、Claude Tag・Claude Security・Code Reviewのセッションもまだ対応していません。

最小構成はガイド付きの claude self-hosted-runner setup か、環境キーを使った手動のRunner起動で試せます。本番投入には、git認証・ネットワークの外向き通信・複数Runnerのオーケストレーションといった追加の設計が要ります。実行場所を自社に置く理由が明確なチームから検討する機能です。

Claude Code全体の中での位置づけはClaude Code(クロードコード)とは、web・モバイルからのクラウドセッションの基本はClaude Code Web版とはから辿れます。定期実行のRoutinesとの組み合わせはClaude Code Routines完全ガイド、この機能が加わったリリース全体はClaude Code v2.1.224にまとめています。