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は「クラウドセッション」の一種です。これとは別に、Desktopアプリでマシンが起動している間だけ動くローカルの定期実行タスクもあります。いずれもAnthropicのインフラ上で走ります。この仕組みは追加のインフラが要らない分、パブリックインターネットに公開していない社内サービスやプライベートなパッケージレジストリには手が届きません。

セルフホスト環境は、このクラウドセッションの実行場所だけを自社側に移します。開発者から見た操作感は変わりません。claude.ai/codeでセッションを始め、返信を読み、フォローアップを送るという流れはAnthropicホスト環境とほぼ同じです。違うのは、動く場所とデータの残り方です。

なお「self-hosted-runner」と「self-hosted environments」は別機能ではなく同じ仕組みの呼び名の違いで、self-hosted environmentsとself-hosted-runnerの違いで名称がどこで置き換わったかを整理しています。

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

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

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

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

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

導入前に確認すること

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

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

GitLabでリポジトリを管理している場合はこのセルフホスト機能の対象外です。glab CLIとMRを紐付けるClaude Code GitLab連携ガイドを代わりに参照してください。

ホスト側の要件も別にあります。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 '<書き込み可能なディレクトリ>'

v2.1.225以降のRunnerは、指定したパスを起動時に作ります。作成も書き込みもできなければ cannot create or write to base directory を出して終了します。--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.285の --help で見えるフラグと、記事の手順に出てこない設定

実機のv2.1.285で claude self-hosted-runner --help を実行すると、フラグは Connection: Runtime: Debug: などの見出しごとに並びます。冒頭は次のとおりです(出力の一部)。

Usage: claude self-hosted-runner [options]
 
Connection:
  --api-url <url>             API base URL (default: https://api.anthropic.com)
  --environment-secret-file <path>
                              Path to environment secret file (or set SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET)
                              (--pool-secret-file / SELF_HOSTED_RUNNER_POOL_SECRET are deprecated aliases.)
  --lock-to-account <id>      Lock runner to a single account at registration (webhook-driven on-demand
                              spawn). Only that account's sessions are assigned.
 
Runtime:
  --capacity <n>              Max concurrent sessions (default: 1)
  --base-dir <path>           Base directory for repo checkouts (default: /workspace;
                              required on Windows, which has no default)

ここまでの手順で使う --environment-secret-file --capacity --base-dir は、ヘルプの先頭近くにあります。手順に出てこないもので、実運用に効きそうな設定を7つ挙げます(前半4つの説明はヘルプの記述、後半3つは公式リファレンスの記述です)。

• --lock-to-account <id>: 登録時にRunnerを特定のアカウントに固定します。ヘルプには「webhook-driven on-demand spawn」(Webhook起点のオンデマンド起動)向けと書かれています。最初に受け取ったセッションで固定される通常の挙動とは別に、登録の時点で対象を決める指定です
• --client-label <label>: 管理画面のRunnerの横に出る表示名です。既定はホスト名で、認可やルーティングには使われません。コンテナのホスト名が意味を持たない環境では、VMやコンテナの名前を入れておくと見分けやすくなります
• --exit-if-unused-min <n>: N分間一度も仕事が割り当てられなかったRunnerを終了させます。ヘルプには「autoscaler scale-down」向けと書かれています
• --kill-session-after-min <n>: セッションの子プロセスの寿命に上限を設けます。ヘルプでは「runaway backstop」(暴走の歯止め)と説明されています
• --defer-shutdown-max-min <n>: 最初の SIGTERM / SIGINT を受けても、すでに接続しているセッションをすぐには解放せず、そのまま動かし続けます。N分後に残っているセッションを解放して終了します。既定の 0 は無効です。設定する前に、ホスト側の停止タイムアウトを延ばしておく必要があります。Claude Code v2.1.238以降が前提です
• --drain-marker-file <path>: ホストが正常なドレイン(順次停止)を知らせるためのマーカーファイルです。SIGTERM を送る前にホストがこのファイルを作っておくと、Runnerは終了の理由を、ただのシャットダウンシグナルではなくホスト起因のドレインとしてAnthropicに報告します。ドレインそのものの動きは変わりません。セッションから書き込めないローカルファイルシステム上のパスを指定します。v2.1.271以降が前提です
• --host-config-snapshot <mode>: 各セッションの初期設定に使う、ホストの設定ディレクトリの起動時スナップショットの置き場所です。既定の disk は --base-dir の下のRunner専用ディレクトリに写し、セッション開始のたびにファイルを照合します。写しが書き換えられていると、そのセッションは失敗し、Runnerを再起動するまで新しいセッションを受け付けません。memory はスナップショットをヒープに保持し、上限は64 MiBです。上限を超えると、ホスト設定なしでセッションが始まり、その旨の通知が出ます。v2.1.271以降が前提です

v2.1.271以降は、self-hosted runnerで動くセッションでもfast modeが使えます。ホスト側のfast mode設定か、セッション内で入力した/fastが、組織が許可している範囲で適用されます。

egressプロキシが Proxy-Authorization ヘッダを要求する環境向けに、--proxy-authorization-command と --proxy-authorization-file もあります。コマンドの標準出力をヘッダ値として接続のたびに実行する形で、値はログに出ません。

誤入力の挙動も実機で確かめられます。v2.1.285で未知の引数を渡すと、通常のセッションは始まらず、エラーで止まります。

claude self-hosted-runner nonexist

error: unexpected argument 'nonexist' — this command takes no positional arguments
Run 'claude self-hosted-runner --help' for usage.

v2.1.224より前のバージョンでは、この種の入力が止まらず、通常のセッションが始まることがあります(次節の1つ目)。

claude --help にも関連する行が2つあります。--cloud [description|session_id|url] は、説明文からクラウドセッションを作るか、既存のセッションIDやclaude.ai/codeのURLに接続します。--environment <environment_id> は、指定したセルフホスト環境(ccpool_...)で動く新しいクラウドセッションを作ります。

よくあるつまずき

• バージョンが古くてもエラーにならない罠があります。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 の値が揃っていないと、再割り当て後にセッションの作業ディレクトリが変わります。エージェントが先に記録した絶対パスが、新しいRunnerでは使えなくなります
• 環境キーは作成時の一度しか画面に出ません。控え忘れると、キーを再発行してRunnerに配り直す作業が発生します
• NTP同期をしていないホストでは、5分を超えるズレで認証が失敗します。エラーメッセージからは原因が分かりにくい部類です
• 古いカーネルのホストでは、エラーが出ないままセッションがCPUを使い続けることがあります。症状と切り分けはCentOS 7のDockerでCPUが張り付く問題にあります

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

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

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

社内MCPサーバーをセルフホスト環境の全セッションに届けたい場合、Runnerイメージへの同梱・managed settingsでの一括配布・claude.aiコネクタ経由という3つの経路があります。それぞれの適用範囲とclaude.aiコネクタが自動では届かない理由はClaude Codeセルフホスト環境にMCPサーバーを届ける3つの経路にまとめています。

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

RunnerのCLIフラグやPrometheusメトリクスは種類が多く、公式リファレンスはアルファベット順の一覧です。「今どのフラグを調整すべきか」から目的別に逆引きできる形に並べ替えたリファレンスはClaude Codeセルフホスト環境のCLIフラグ・メトリクスリファレンスにまとめました。

スモークテストをさらにCI上で自動化したい場合、Stop hookでの応答読み戻し・--environmentディスパッチ・CI認証の2方式を組み合わせた検証手順が要ります。具体的な組み方はClaude Codeセルフホスト環境をCIでE2Eテストするで扱っています。

よくある質問

Runnerが満杯のとき、新しいセッションはどうなりますか

拾えるRunnerが無い間、セッションはキューに残ります。空き容量があっても、別のownerにロックされた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からで、GitHub Enterprise Serverも対象です。ただしリポジトリピッカーなど、セッション開始前の処理はAnthropic側で動きます。そのためGHESのホストには、Anthropicのインフラから到達できる必要があります。社内からしか届かないGHESへ中継するSCM connectorは設計上ありますが、現在は提供されていません。--scm-connector-host は未設定のままにします。設定すると接続が開かず、オーケストレーターが再試行を続けます。

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

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

まとめ

自社ネットワーク内のリソースにセッションから触れる必要がなければ、Anthropicホスト環境のままで足ります。必要があり、かつ制限表の条件(ゼロデータ保持なし・Bedrock等を経由しない・GitHub利用)を満たすなら、まず claude self-hosted-runner setup で1台分を試し、本番の設計(git認証・外向き通信・複数Runner)はその後に進めます。

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