セルフホスト環境リファレンス

セルフホストランナーとオーケストレーターの完全なリファレンス：CLI フラグ、環境変数、Prometheus メトリクス。

[!NOTE]

セルフホスト環境は Team および Enterprise プランでパブリックベータ版です。Owner が Cloud environments 管理ページ で Allow self-hosted environments をオンにすることで有効になります。このページはフラグとメトリクスのリファレンスです。セットアップについては クイックスタート を、フリート構成については 本番環境へのデプロイ をご覧ください。

このページは、セルフホスト環境 で実行する 2 つのプロセスのリファレンスです。ランナーはホスト上で Claude Code クラウドセッション を実行し、オプションのオートスケーリングオーケストレーターはセッションがキューに入ると同時にランナーを起動します。それぞれ独自のフラグテーブルを持っています。どちらも Linux または macOS ホスト上で実行され、/workspace や ~/.claude などのデフォルトを想定しています。インストール済みバージョンの権限あるリストについては、claude self-hosted-runner --help を実行してください。

メトリクスシリーズと一部の API フィールドは、これらのページが環境と呼ぶものに対して pool を使用しています。どちらの用語も同じものを指しています。環境 ID は pool_id フィールドで、形式は ccpool_... です。これらのページが pool 識別子を示す場所では、環境を指しています。CLI フラグと環境変数では environment と表記されます。例えば --environment-secret-file のように。非推奨の pool 表記はまだ機能します。--environment-secret-file 行 で説明されているとおりです。

ランナーの CLI フラグ

ほとんどのフラグには対応する環境変数があります。両方が設定されている場合は、フラグが優先されます。期間を指定するフラグは CLI では分または秒で指定しますが、対応する環境変数は常にミリ秒単位で、これは _MS サフィックスで示されます。また、「デフォルト」列にはフラグの単位で値を示しています。たとえば、--exit-if-unused-min 10 は SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000 と同等であり、SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" のような Helm の値は、デフォルトの 15 分ではなく 15 ミリ秒を意味します。

ほとんどの期間フラグには最大値があり、各タイムアウトがランタイムの 32 ビットタイマーの上限である約 24.85 日に収まるように選ばれています。--*-min フラグの上限は 10080 分（7 日）、--drain-grace-sec は 604800 秒（同じく 7 日）、--drain-wait-sec は 86400 秒（24 時間）です。--session-stop-grace-sec と --post-session-hook-timeout-sec には上限がありません。上限を超えた場合の動作は、指定方法によって異なります。

• フラグ：エラーで起動に失敗します。
• 環境変数：ランナーは値を拒否せず、タイマーの上限に切り詰めます。

セッション起動タイムアウト

/code-review などのターンの途中でセッションがスロットを失った場合は、ランナーと子バイナリを v2.1.309 以降に更新してください。v2.1.299 から v2.1.308 までは、user または assistant メッセージがないまま起動タイムアウトが経過すると、ランナーはターンの途中であってもセッションを解放していました。

--startup-timeout-min <n> を指定すると、クローン後 <n> 分以内に子プロセスが初期化されない場合、ランナーはセッションのスロットを解放します。子プロセスの初期化前に始まったターンの間は、子プロセスのアクティビティチャネルに行が出力されないまま <n> 分が経過するまで、セッションはスロットを保持します。子プロセスが初期化されると、ランナーはその計測をリセットし、以降の解放は --release-idle-session-min によって制御されます。子プロセスは動作しているもののスタックしているセッションを制限するには、--kill-session-after-min を設定してください。

auto モードのルールリスト

--server-auto-mode-lists を使用すると、ランナーの外部から届く auto モードの分類器ルールのうち、どれをランナー上のセッションに届けるかを決められます。Anthropic のコントロールプレーンは、セッションとともにルールリストを送信し、それらを適用するようランナーに要求できます。一部のエントリは、組織の管理者が作成したルールである場合があります。リストは environment、soft_deny、allow の 3 つです。

• environment：エントリによって、分類器が許可する範囲を広げることも狭めることもできます。
• soft_deny：ユーザーが明示的に要求した場合や allow の例外が適用される場合を除き、エントリはアクションをブロックします。
• allow：soft_deny のエントリに対する例外です。

フラグの値によって、ランナーが適用するリストが決まります。

• no-allow：デフォルトです。environment と soft_deny を適用し、allow は適用しません。environment のエントリによって分類器が許可する範囲が広がる可能性は残るため、デフォルトではあらゆる緩和を排除できるわけではありません。
• all：3 つのリストすべてを適用します。
• none：いずれのリストも適用しません。これらのリストによるあらゆる緩和を排除するには、none を選択してください。この場合、soft_deny による制限も適用されなくなります。

コントロールプレーンがランナーにリストの適用を要求するようにするランナー設定はありません。要求がない場合、設定にかかわらず、セッションはリストを受け取りません。どちらになったかを確認するには、--log-level debug を指定してランナーを起動します。すると、ランナーはセッションごとに、the server asked this runner to apply を含む行、または the server did not ask this runner to apply the auto mode lists it sends を含む行をログに記録します。

オーケストレーター CLI フラグ

オンデマンドランナーを起動する self-hosted-runner orchestrator サブコマンドは、--api-url、--environment-secret-file、--hooks-dir、--health-port、--log-level を受け付けます。これらのデフォルト値はランナーと同じで、ランナーのフラグに環境変数がある場合は同じ環境変数も使用できます。ただし、--hooks-dir は必須であり、spawn-runner フックを含んでいる必要があります。また、オーケストレーター独自のフラグも受け付けます。

SCM コネクタフラグ

SCM コネクタは利用できないため、このセクションのフラグは設定しないでください。--scm-connector-host を設定しても接続は確立されず、オーケストレーターは接続の再試行を続けます。セッションがキューに入ると、ランナーは引き続き起動します。

コネクタは、オーケストレーターから Anthropic のコントロールプレーンへの常時接続の WebSocket 接続です。リポジトリピッカーやブランチまたは ref のリゾルバーなど、ホストされたセッション前のフローが、ネットワーク内部からのみルーティング可能な GitHub Enterprise Server ホストに到達できるように設計されています。これらのフローに必要なものについては、GitHub Enterprise Server のページのネットワーク要件を参照してください。

接続を試行するたびに、オーケストレーターは既存の環境シークレットを送信し、指数バックオフ（上限は 30 秒にジッターを加えた値）で自動的に再試行します。

環境変数のみの設定

これらのランナー設定は環境からのみ読み取られ、ほとんどのデプロイメントがデフォルトのままにしておく動作をカバーしています。

テレメトリ

セッション子は、オフにしない限り、運用テレメトリを Anthropic に送信します。コードまたはリポジトリコンテンツは送信されません。ランナープロセスでテレメトリ変数を設定します。ランナーはサーバー提供の環境変数を適用した後、それらを再アサートするため、オペレーターの設定は常に優先されます。

1 つのコントロールはセルフホスト環境に固有です。CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 は Datadog 運用メトリクスにオプトインします。これはセルフホスト環境ではデフォルトでオフです。一般的な Claude Code テレメトリコントロール DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_ERROR_REPORTING、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC は 環境変数リファレンス に記載されているようにセッション子に適用されます。DISABLE_GROWTHBOOK は関連していますが異なります。DISABLE_GROWTHBOOK=1 を設定するとフィーチャーフラグフェッチが無効になり、DISABLE_TELEMETRY も設定されない限りテレメトリはオンのままです。

CLAUDE_CODE_ENABLE_TELEMETRY は無関係です。これは 監視 で説明されているように、独自のコレクターへの OpenTelemetry エクスポートを有効にし、Anthropic のアナリティクスを制御しません。

ヘルスエンドポイント

ランナーは設定されたヘルスポートで GET /healthz を提供します。レスポンスは、プロセスが生存している限り、ポーリングループがどの状態にあるかに関係なく 200 OK です。したがって、このエンドポイントの HTTP プローブはデッドプロセスのみを検出します。JSON ボディは現在の状態を説明します。

{
  "status": "ok",
  "runner_id": "ccrunner_...",
  "active_sessions": 2,
  "last_poll_at": "2026-03-31T18:04:11.220Z",
  "last_poll_age_ms": 842
}

last_poll_age_ms に対してアラートを設定しますが、ライブネスプローブには使用しないでください。ライブネスプローブは HTTP ステータスコードに基づくようにしてください。この値は最後に成功したポーリングからの経過時間であるため、ランナーが Anthropic に到達できない間も増加します。last_poll_at と last_poll_age_ms の両方は、最初のポーリングが成功するまで null です。最初から失敗しているポーリングを検出するには、Prometheus メトリクスに記載されている claude_code_self_hosted_runner_poll_errors_total に対してもアラートを設定してください。

オーケストレーター自身の /healthz は、そのヘルスポート上で常に 200 を返します。ボディには、最新のポーリングが成功したかどうかを報告する connected フィールドと、queue_counts 内の状態ごとのスポーンキュー数が含まれます。connected が false である理由を確認するには、トップレベルの last_error フィールドを参照してください。このフィールドはポーリングが成功するたびに null にリセットされます。ステータスコードではなく connected でレディネスとアラートをゲートします。

SCM コネクタ が設定されている場合、オーケストレーターの /healthz ボディは scm_connector_connected と、connected、last_connected_at、last_error、reconnects、requests_forwarded を持つ scm_connector オブジェクトも持ちます。--scm-connector-host が設定されていない場合、両方のフィールドは null です。

Prometheus メトリクス

各ランナーは /healthz と同じポートで GET /metrics で Prometheus メトリクスを提供します。主要なシリーズ：

オーケストレーターは /healthz と同じポートで GET /metrics で独自のシリーズを提供します。

オートスケーリングの場合、スケーリングスタイルに一致するシリーズを選択し、スケーラーに供給する前にゲートします。

• キュー深度スケーリング：queue_pending_sessions ではなく claude_code_self_hosted_orchestrator_pool_pending_sessions を HPA または KEDA スケーラーに供給します。
• 容量スケーリング：ランナーの active_sessions と capacity の比率でスケーリングします。
• connected でゲート：インスタンスごとに claude_code_self_hosted_orchestrator_connected == 1 でクエリをフィルタリングします。切断されたレプリカの古い値がスケーラーに供給されないようにします。

完全なポーリング停止中、すべてのレプリカが切断されると、ゲートされたクエリはデータを返しません。HPA は欠落メトリクスで現在のレプリカ数を保持しますが、KEDA の Prometheus スケーラーはデフォルト ignoreNullValues: "true" で空の結果をゼロとして読み取り、スケールインします。ScaledObject で ignoreNullValues: "false" を設定し、オプションで fallback レプリカフロアを設定します。

次の Prometheus Operator PodMonitor は両方のプロセスをカバーしています。app.kubernetes.io/part-of: claude-code-self-hosted-runner ラベルと、Kubernetes レシピ が設定する名前付き health ポートでポッドを選択します。デプロイメントに合わせて名前空間を調整します。

# Claude Code セルフホストランナー + オーケストレーター用の Prometheus Operator PodMonitor の例。
# 名前空間とラベルセレクターをデプロイメントに合わせて調整します。
# ランナーとオーケストレーターの両方は、その --health-port（デフォルト 8080）で /metrics を提供します。
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Kubernetes レシピからのランナー Deployment、および同じ方法でラベル付けされた
      # オンデマンドランナー Job とオーケストレーターポッド、および名前付き 'health' containerPort を持つものと一致します。
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

サンプルアラートルール

これらのサンプルアラートルールは出発点です。フリートサイズのしきい値を調整します。

# Claude Code セルフホストランナー + オーケストレーター用の Prometheus アラートルールの例。
# フリートサイズと SLO のしきい値を調整します。
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "ランナー {{ $labels.pod }} は 60 秒以上ポーリングしていません"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "ランナーは混合バージョンを実行しています"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_init_errors_total[10m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "セッションが初期化前に失敗しています（チェックアウトフック / git / トークン / 初期化前クラッシュ）"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "ランナー {{ $labels.pod }}：PollWork が失敗しています（5 分間に {{ $value | humanize }}/s）"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "SessionStart フックが失敗しています"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "オーケストレーター {{ $labels.pod }} は Anthropic コントロールプレーンに到達できません"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "オーケストレーター {{ $labels.pod }} は 90 秒以上ポーリングしていません（ポーリングループはフック実行で待機）"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: max by (namespace) (claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions and on (instance) max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1) > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "スポーンがブロックされているセッション：{{ $value }}。Activity タブで各セッションのエラーを確認し、原因を修正してから Retry を選択してください"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "オーケストレーター {{ $labels.pod }}：PollSpawnHints が失敗しています（5 分間に {{ $value | humanize }}/s）"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "オーケストレーター {{ $labels.pod }}：5 分間に 3 回以上の spawn-runner フック失敗"

ランナーの喪失と待機中のセッションでアラートする

ランナーが失われたとき、セッションが待機しているとき、またはオーケストレーターが停止しているときにアラートを受け取るには、サンプルアラートルール と併せて次の Prometheus アラートルールを読み込みます。

• 固定フリート：ClaudeRunnersBelowFloor
• オンデマンドランナー：ClaudeOrchestratorSessionsWaiting、ClaudeOrchestratorQueueWaitHigh、ClaudeOrchestratorAbsent

固定フリートがランナーを失ったときにアラートする

ClaudeRunnersBelowFloor は、登録済みかつスクレイプ済みのランナー数がフロアを下回る状態が 10 分間続いたときに発火します。

groups:
  # 固定フリートのみ。オンデマンドランナーではランナー数が需要に従うため、
  # ClaudeRunnersBelowFloor は需要が低いときに常に発火してしまいます。
  - name: claude-code-self-hosted-fixed-fleet-capacity
    rules:
      - alert: ClaudeRunnersBelowFloor
        expr: (count(claude_code_self_hosted_runner_info{namespace="claude-runners"}) or vector(0)) < 2
        for: 10m
        labels: {severity: critical, namespace: claude-runners}
        annotations:
          summary: "登録済みかつスクレイプ済みのランナー：{{ $value }}、フロアを下回っています。まずランナーのワークロードを確認し、すべて実行中であればスクレイプターゲットを確認してください。"

• フロア：expr 内の 2 を、レプリカ数の約半分（切り上げ）に設定します。レプリカが 3 つの場合は 2 のままにすると、ランナーが 1 つ以下になったときにアラートが発火します。
• 名前空間：matcher と labels 内の claude-runners を置き換え、追加の名前空間ごとにアラートをコピーします。ターゲットに namespace ラベルがない場合は、matcher とラベルを削除してください。そうしないと、アラートは 0 を読み取って発火します。
• ClaudeRunnerPollStale と ClaudeRunnerPollErrors：サンプルアラートルール から読み込んだままにしておきます。ClaudeRunnersBelowFloor はポーリングできないランナーもカウントするためです

オンデマンドランナーをセッションが待機しているときにアラートする

ClaudeOrchestratorSessionsWaiting は、ランナーを待機しているセッション数が 10 分間 0 を超えたままのときに発火します。ClaudeOrchestratorQueueWaitHigh は、直近 10 分間のキュー待機の 1% 超が 160 秒を超え、その状態が 5 分間続いたときに発火します。

groups:
  # オンデマンドランナーのみ。名前空間に合わせた編集は不要です。
  - name: claude-code-self-hosted-on-demand-capacity
    rules:
      - alert: ClaudeOrchestratorSessionsWaiting
        expr: |
          max by (namespace) (
            claude_code_self_hosted_orchestrator_pool_pending_sessions
            and on (instance)
            max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1
          ) > 0
        for: 10m
        labels: {severity: warning}
        annotations:
          summary: "ランナーを待機しているセッション：{{ $value }}、10 分間しきい値を超えています。result 別の claude_code_self_hosted_orchestrator_spawn_hooks_total を確認し、次に起動しないランナーのワークロードを確認してください。"
      - alert: ClaudeOrchestratorQueueWaitHigh
        expr: |
          histogram_quantile(0.99, sum by (namespace, le) (
            rate(claude_code_self_hosted_orchestrator_session_queue_wait_seconds_bucket[10m])
          )) > 160
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "直近 10 分間のキュー待機の 1% 超が 160 秒を超えました。ClaudeOrchestratorDisconnected が発火しているかを確認し、次に result 別の claude_code_self_hosted_orchestrator_spawn_hooks_total と claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds を確認してください。"

• しきい値：常に何らかのセッションが待機している場合は、ClaudeOrchestratorSessionsWaiting の > 0 を、通常見られる数より大きい値に引き上げます
• ClaudeOrchestratorDisconnected：サンプルアラートルール から読み込んだままにしておきます。ClaudeOrchestratorSessionsWaiting は、名前空間内の最後のオーケストレーターが切断されてから約 2 分後に発火を停止するためです

オーケストレーターが停止したときにアラートする

オーケストレーター 自体が停止していることを把握するには、ClaudeOrchestratorAbsent を読み込みます。このアラートは、名前空間内のどのオーケストレーターも 5 分間スクレイプされていないときに発火します。

groups:
  # オンデマンドランナーのみ。claude-runners をオーケストレーターの名前空間に置き換えます。
  - name: claude-code-self-hosted-on-demand-orchestrator
    rules:
      - alert: ClaudeOrchestratorAbsent
        expr: absent(claude_code_self_hosted_orchestrator_connected{namespace="claude-runners"})
        for: 5m
        labels: {severity: critical}
        annotations:
          summary: "5 分間オーケストレーターがスクレイプされていません。オーケストレーターが停止している場合、オンデマンドランナーは起動せず、セッションは待機します。まずオーケストレーターのワークロードを確認し、実行中であればそのスクレイプターゲットを確認してください。"

• 名前空間：claude-runners をオーケストレーターの名前空間に置き換え、オーケストレーターを実行する追加の名前空間ごとにアラートをコピーします。ターゲットに namespace ラベルがない場合は、matcher を削除してください。そうしないと、アラートは 5 分後に発火し、発火したままになります。
• オーケストレーターをスクレイプしない Prometheus サーバー：そのようなサーバーではアラートが 5 分後に発火し、発火したままになるため、それらのサーバーのルールファイルにはこのアラートを含めないでください
• オーケストレーターの他のアラートに頼らない：それらはオーケストレーター自身が提供するメトリクスを読み取ります。ClaudeOrchestratorSessionsWaiting、ClaudeOrchestratorQueueWaitHigh、およびオーケストレーターの サンプルアラートルール はすべて、オーケストレーターが停止してから約 10 分以内に発火を停止します。

セッション子メトリクスをパススルーする

各セッションは独自の子プロセスで実行され、独自の OpenTelemetry メトリクスを持ちます。--capacity が 1 を超える場合、ランナーはそれらの子メトリクスの公開方法を書き換えます。ランナーホストで OTEL_METRICS_EXPORTER=prometheus を設定し、セッションの環境で CLAUDE_CODE_ENABLE_TELEMETRY=1 を設定します。例えば、ラッパースクリプト またはセッションが継承するランナー独自の環境から、各子のカウンターとゲージ計器をランナー独自の /metrics エンドポイントで再公開します。ランナーのシリーズと並んで。ランナーは子のエクスポーターを書き換えて、ヘルスポートのループバックのみのレシーバーに OTLP 経由でプッシュし、各シリーズに session_id および client_platform ラベルでタグ付けし、セッションが終了するとセッションのシリーズを削除します。ヒストグラムはパススルーしません。ランナー独自のプレフィックスと衝突する子メトリクスの名前は削除されます。

デフォルトの --capacity 1 では、書き換えは適用されません。セッションの子は通常どおりポート 9464 で独自の Prometheus エンドポイントをバインドします。

セッションのメトリクスをランナーのメトリクスと結合する

アイドル状態のセッションにかかったコストを確認するには、ランナーの claude_code_self_hosted_runner_session_idle_seconds を Claude Code のコストメトリクスと ccr_session_id で結合します。ランナーのメトリクスはこのラベルを持たないため、次のクエリのように label_replace でラベルを付与します。

sum by (ccr_session_id) (claude_code_cost_usage_total)
and on (ccr_session_id)
label_replace(
  claude_code_self_hosted_runner_session_idle_seconds > 600,
  "ccr_session_id", "cse_$1", "session_id", "session_(.*)"
)

このクエリは、10 分を超えてアイドル状態のセッションごとに 1 つの結果を返します。結果は、そのセッションの Claude Code プロセスがこれまでに計上したコスト（米ドル）です。別の Claude Code メトリクスを結合するには、クエリ内の claude_code_cost_usage_total を置き換えます。このクエリは任意の --capacity で機能します。

• session_id：ポート 9464 では、Claude Code メトリクスのこのラベルには Claude Code 独自の session.id が入っており、どのランナーシリーズとも一致しません。このラベルで結合しても何も返されないため、ccr_session_id で結合してください。
• Claude Code メトリクスに ccr_session_id がない場合：OTEL_METRICS_INCLUDE_SESSION_ID が false に設定されていないことを確認してください

セッションライフサイクルカウンターセマンティクス

sessions_started_total、sessions_completed_total、sessions_failed_total、sessions_interrupted_total カウンターは、各セッションがどのように終了したかで分類します。スポーンされたすべてのセッション子はスポーン時に sessions_started_total をインクリメントし、終了時に他の 3 つのうち正確に 1 つをインクリメントします。したがって、sessions_started_total から他の 3 つの合計を引いたものは、現在実行中のセッション子の数に等しくなります。

• completed：セッションはクリーンに終了しました。これは子がコード 0 で独自に終了する場合、セッションが子がまだ接続されている間にアーカイブまたは削除される場合、およびランナーがスロットをクリーンハンドオフとしてリリースする場合をカバーします。アイドルタイムアウト、リタイア時間、または --kill-session-after-min 制限でのリリース、スタートアップタイムアウト、またはポーリングループが子が終了する前に気付いたサーバー側の割り当て解除。sessions_completed_total をインクリメントします。
• failed：子がゼロ以外のコードで独自に終了しました。クラッシュまたはスポーン後のセットアップ失敗のいずれか。sessions_failed_total をインクリメントします。
• interrupted：ランナーがセッション成功またはランナー障害のいずれでもない運用上の理由で子を終了しました。たとえばドレインや、--kill-session-after-min 制限後の SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS グレースウィンドウが終了した時点でまだランナー上にあったセッションの終了などです。Kubernetes ローリング再起動が SIGTERM を送信することは、ドレインの一例です。sessions_interrupted_total をインクリメントします。

v2.1.260 より前では、ランナーは --kill-session-after-min 制限に達したすべてのセッションを終了し、sessions_interrupted_total でカウントしました。

post-session フック の CLAUDE_RUNNER_EXIT_REASON はクリーンハンドオフを異なる方法で分類します。フックは、ランナーが子を停止したため、リリース、スタートアップタイムアウト、サーバー割り当て解除、およびポーリングが先に気付いたアーカイブまたは削除を interrupted として報告します。これらのカウンターは、スロットがクリーンに返されたため、completed として同じイベントを記録します。

フック受信を sessions_completed_total に対して直接調整する場合、完了をアンダーカウントします。セッションごとの保証にはフックを使用し、集計レートにはカウンターを使用します。

ワンショット環境では、--capacity 1 とデフォルト --drain-grace-sec 0 で、各ランナープロセスは 1 つのセッションが終了した直後に終了します。sessions_completed_total、sessions_failed_total、sessions_interrupted_total はセッション終了時にのみインクリメントされます。その終了の直前に、Prometheus スクレイプが 15 ～ 60 秒ごとの場合、ランナーのシリーズが消える前にインクリメントをキャッチすることはめったにありません。これら 3 つのセッション終了カウンターは、このセクションの残りが参照するターミナルカウンターです。sessions_started_total はスポーン時にインクリメントされ、セッションの生存期間中は表示されたままなので、確実に表示されます。ただし、ワンショット環境では、累積カウントよりも「現在実行中のセッション」に近く読み取られます。

対応する目標の代わりにこのテーブルのシリーズを使用します。

orchestrator_* 行は オンデマンドオーケストレーター を実行している環境にのみ存在します。セッションを超えて生存するランナーを持つ固定フリートで、--drain-grace-sec が 0 を超える場合、スループットに sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) を使用します。ワンショットフリートではそのシリーズは他のターミナルカウンターと同じスクレイプウィンドウ問題を持つため、キューに入ったセッション数に依存します。バックログを環境の Activity タブで確認します。Cloud environments 管理ページ：ランナーはキュー深度シリーズをエクスポートしません。

セッションごとの結果報告については、代わりに post-session フック を使用してください。VM プリエンプションなどの突然のランナー終了を除き、子プロセスがスポーンされたすべてのセッション終了で発火します。フック独自の契約 に従って。

次のステップ

• セルフホスト環境：環境、ランナー、セッションモデル。クイックスタート と 本番環境へのデプロイ はセットアップと運用を保持しています。
• セッションをカスタマイズする：ラッパースクリプト、ライフサイクルフック、オンデマンドランナー。
• セッション ID を検証する：セッショントークン、そのクレーム、検証方法。