Claude Media
self-hosted environmentsとself-hosted-runnerの違い
Claude Code解説

self-hosted environmentsとself-hosted-runnerの違い

self-hosted-runnerとself-hosted environmentsは別機能でなく同じ仕組みの呼び名です。claude self-hosted-runner --helpとCHANGELOGで、名前の使い分けを見ます。

読了目安 約8分

Claude Codeの公式docsを読んでいると、同じ機能を指すのに「self-hosted environments」というページ名と、claude self-hosted-runnerというコマンド名の両方に出会います。別々の機能が2つあるわけではありません。self-hosted environmentsは製品名、self-hosted-runnerはそれを動かすCLIサブコマンドの名前で、指している実体は同じです。

結論から言うと、名前の使い分けは「誰に向けた文脈か」で決まります。管理画面とdocsの入口は製品名、ターミナルとフラグ説明はRunnerの名前です。APIとメトリクスにはpoolという第三の綴りが残っています。

なぜ2つの名前が併存するのか

CHANGELOGでこの機能が最初に登場したv2.1.224の1行は、両方の語を同じ文に含んでいます。「self-hosted environments」を追加したと書き、それを実現するのがclaude self-hosted-runnerだと続けています。命名が途中で割れたのではなく、最初から役割の異なる2つの名前として置かれていました。

製品名の「environments」が指すのは、Environment・Runner・Sessionという3つの要素からなる仕組み全体です。管理画面でEnvironmentを作り、複数のRunnerをそこにぶら下げ、開発者が始めたSessionをRunnerが拾って実行します。「runner」はその中の1要素、Runnerプロセスを起動するコマンド名です。

名前の地図

同じ仕組みを指す3つの綴り

  • environments(製品名)

    docsのURL・ページ名と、claude.aiの管理画面で使われます。管理画面ではCloud environmentsページの「Self-hosted environments」欄でEnvironmentを作ります。有効化はOwnerが「Allow self-hosted environments」で行います。

  • runner(実行主体)

    claude self-hosted-runnerというCLIサブコマンドと、そのフラグの説明で使われます。CHANGELOGのバグ修正や新フラグの記録も、多くはこの語で書かれています。

  • pool(内部の綴り)

    メトリクス名と一部のAPIフィールドに残っています。EnvironmentのIDはpool_idで、形式はccpool_...です。

手元のclaudeで見る名前の食い違い

v2.1.287のclaude self-hosted-runner --helpは、接続まわりのオプションを次のように出力します(抜粋)。

claude self-hosted-runner --help
  --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.)

フラグ名はenvironmentに統一され、旧名のpoolは非推奨の別名として残っていると、ヘルプ自身が書いています。referenceページも同じ説明で、旧名はいまも動き、stderrに非推奨の通知が出ます。2.1.216より古いプレビュー版のRunnerは旧名しか認識しません。古いブログ記事の--pool-secret-fileを新しいRunnerにそのまま貼っても動きますが、古いRunnerに新名を貼ると認識されない、という非対称があります。

claude self-hosted-runner setupのヘルプは、対話式のウィザードだと説明しています。Environmentの作成、ローカルRunnerの起動、管理画面への表示確認までを順に進め、最後にCHEAT-SHEET.mdを書き出す内容です。ここでも画面側はEnvironment、起動するものはRunnerと呼び分けられています。

--client-labelのヘルプには、Anthropicのコンソールでrunnerの横に表示される観測用のラベルだと書かれています。認可やルーティングには使われず、既定値はホスト名です。ホスト名に意味がないVMやコンテナでは、これで見分けがつくようにします。

環境変数の名前も一つの接頭辞には揃っていません。--client-labelの環境変数はSELF_HOSTED_RUNNER_CLIENT_LABELです。一方、--use-anthropic-git-proxyはCLAUDE_RUNNER_USE_GIT_PROXY=1で指定します。時間のフラグは分や秒で渡しますが、対応する環境変数は常にミリ秒です。--exit-if-unused-min 10はSELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000と同じ意味になります。

変更履歴での使い分け

CHANGELOGのself-hosted関連エントリを通しで見ると、語の選ばれ方に規則があります。Runnerの挙動を直した記述は「self-hosted runner」で書かれ、管理画面やClaude Tagの選択肢に触れる記述は「self-hosted environments」で書かれます。

  • Runner側の例: v2.1.251の「強制停止されたセッションのBashツールプロセスが残る不具合」、v2.1.248の--client-label
  • 管理画面側の例: 「self-hosted environments admin pageのRunner actionsメニューが勝手に閉じる」修正
  • Claude Tag側の例: Environment選択がAnthropic-hostedかself-hostedかを表示するようにした改善

バグ検索の入口を選ぶ手がかりになります。コマンドの不具合ならself-hosted-runner、管理画面の不具合ならself-hosted environmentsで探すほうが当たりやすい構成です。

バージョン変更内容
v2.1.224変更内容self-hosted environmentsを追加。実行を担うのはclaude self-hosted-runner
v2.1.229変更内容Windowsでの起動に--base-dirの明示を必須化。GCM(Git Credential Manager)のプロンプトでハングする不具合を修正
v2.1.229変更内容サーバー側から配信するhookをセルフホストランナーのセッションでもサポート
v2.1.238変更内容--defer-shutdown-max-minと--proxy-authorization-commandなどのフラグを追加。ポーリング遅延だけでランナーがサーバーから除外される不具合を修正
v2.1.248変更内容--client-label(またはSELF_HOSTED_RUNNER_CLIENT_LABEL)でランナーの登録名を上書きできるように
v2.1.251変更内容強制停止されたセッションのBashツールプロセスが残り続ける不具合を修正
v2.1.287変更内容GitHub CLIが入っていないmacOS・Linuxで、Anthropic管理のgitを使うセッション向けに組み込みのgh api(RESTのみ)を追加

v2.1.224の項目は、自社のマシンやコンテナを、Claude Codeのweb・モバイル・デスクトップのセッションの実行場所にする機能として書かれています。

混同しやすい2つの隣接語

ひとつはGitHub Actionsの「self-hosted runner」です。公式docsのRunnerの説明は、CIのself-hosted runnerと同じ発想だと書いています。設計の発想は共通ですが、実行するものが違います。docsはRunnerを、セッションを実行する担い手として説明しています。

くらべる

2つのself-hosted runner

CI/CDの文脈

GitHub Actions

ワークフローのジョブを実行します。GitHubのdocsは、自分で配備・管理してGitHub Actionsのジョブを実行するシステムと定義しています。検索結果にGitHub側の解説が混ざったら、こちらです。

クラウドセッションの文脈

Claude Code

Claude Codeのクラウドセッション用プロセスを実行します。自社ネットワーク内でリポジトリをクローンします。Anthropicへはapi.anthropic.comへの外向きHTTPSだけで接続し、Anthropic側から入ってくる接続はありません。gitホストへは、自社で設定した認証情報で認証します。セッションが到達できる追加のホストは、短い一覧にまとまっています。

もうひとつは「Claudeモデル自体を自社インフラで動かす」話との混線です。self-hosted environmentsが自社側に持ってくるのはコードのチェックアウトとビルドの実行環境で、モデル推論は変わらずAnthropicのAPIに送られます。公式docsはAmazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry、LLM gatewayのいずれでも推論を経由できないと書いています。

導入面の条件も、名前とは別に押さえておく点です。この機能はTeamとEnterpriseのpublic betaで、既定では無効です。Zero Data Retentionが有効な組織では使えません。

Remote Controlや通常のクラウドセッションとどう違うか

self-hosted environmentsが対象にするのは、claude.ai/codeやモバイル・デスクトップアプリ、ターミナルの--cloud、スケジュール実行のroutinesから始める「クラウドセッション」の実行場所です。これらは既定でAnthropicのインフラ上を動きますが、self-hosted environmentsを有効にした組織では、自社のマシンやコンテナに実行場所を差し替えられます。

常時稼働している自分のマシンを別デバイスから操作したいだけなら、対象は別の機能です。Pro・Maxプランでも使えるRemote Controlが目的に合います。対象プラン・要件を並べた早見表と導入手順は、Claude Code self-hosted-runnerとはにあります。

どの名前で調べればよいか

手順

目的別の調べ方

  1. 1

    導入できるか知りたい

    self-hosted environmentsでdocsのトップページへ。対応プラン、ZDRとの非互換、推論経路の制約はここにあります。

  2. 2

    フラグやエラーを調べたい

    self-hosted-runnerの名前で、claude self-hosted-runner --helpとreferenceページを当たります。--capacityや--retire-at、--drain-grace-secはここです。runnerは最初のセッションを受け取ると、そのOwnerに固定されます。この挙動に関わる--lock-to-accountもrunner側の名前です。

  3. 3

    監視指標を組みたい

    メトリクス名はclaude_code_self_hosted_runner_capacityのようにrunner系です。キューの待ち件数はclaude_code_self_hosted_orchestrator_pool_pending_sessionsのようにpoolが入ります。--client-labelの値はclaude_code_self_hosted_runner_infoのclient_labelラベルにも出るので、ダッシュボード上でホストを見分けられます。referenceでは「pool」と「environment」は同じものとして扱われています。

よくある質問

古いブログ記事でself-hosted runnerとだけ書かれているのは間違いですか

間違いではありません。CHANGELOGの多くのエントリがこの表記で、Runnerの挙動を説明する文脈ではむしろ実態に合っています。管理画面の操作を説明する記事なら、environmentsの語で読み替えます。

まとめ

検索の入口を決める軸は、プランや導入可否なら製品名のenvironments、フラグやエラーならrunner、メトリクスならpoolです。同じ仕組みに3つの綴りがあるだけなので、古い記事の表記が違っても読み替えれば足ります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →