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

セルフホストランナーとオーケストレーターの完全なリファレンス：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 は 環境変数リファレンス に記載されているようにセッション子に適用されます。CLAUDE_CODE_DISABLE_FEATURE_FLAGS は関連していますが異なります。CLAUDE_CODE_DISABLE_FEATURE_FLAGS=1 を設定するとフィーチャーフラグフェッチが無効になり、DISABLE_TELEMETRY も設定されない限りテレメトリはオンのままです。CLAUDE_CODE_DISABLE_FEATURE_FLAGS には Claude Code v2.1.319 以降が必要です。

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 ポートによって Pod を選択します。デプロイに合わせて名前空間を調整してください。

# 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 に加え、同じ方法でラベル付けし、
      # 名前付きの 'health' containerPort を指定したオンデマンドランナーの Job や
      # オーケストレーター Pod に一致します。
      - 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: "Runner {{ $labels.pod }} has not polled in >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runners are running mixed versions"
      - 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: "Sessions are failing before init (checkout hook / git / token / pre-init crash)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 5m)"
      - 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 hooks are failing"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} cannot reach the Anthropic control plane"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"
      - 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: "Sessions blocked from spawning: {{ $value }}. Read each one's error in the Activity tab, fix the cause, then select 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: "Orchestrator {{ $labels.pod }}: PollSpawnHints failing ({{ $value | humanize }}/s over 5m)"
      - 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: "Orchestrator {{ $labels.pod }}: >3 spawn-runner hook failures in 5m"

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

ランナーが失われたとき、セッションが待機しているとき、またはオーケストレーターが停止しているときにアラートを受け取るには、サンプルアラートルールと並べて次の 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: "Runners registered and scraped: {{ $value }}, below the floor. Check the runner workloads first, then the scrape targets if all are running."

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

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

ClaudeOrchestratorSessionsWaiting は、ランナーを待機しているセッションの数が 0 を超えた状態が 10 分間続くと発火します。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: "Sessions waiting for a runner: {{ $value }}, above the threshold for 10 minutes. Check claude_code_self_hosted_orchestrator_spawn_hooks_total by result, then runner workloads that don't start."
      - 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: "Over 1% of queue waits in the last 10 minutes exceeded 160 seconds. Check whether ClaudeOrchestratorDisconnected is firing, then claude_code_self_hosted_orchestrator_spawn_hooks_total by result and 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: "No orchestrator has been scraped for 5 minutes. If it's down, no on-demand runner starts, and sessions wait. Check the orchestrator workload first, then its scrape target if it's running."

• 名前空間：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 猶予期間が終了した時点でまだランナー上にあったセッションの終了などです。SIGTERM を送信する Kubernetes のローリング再起動は、ドレインの一例です。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 はセッション終了時、つまりその終了の直前にのみインクリメントされるため、15～60 秒ごとの Prometheus スクレイプでは、ランナーの系列が消える前にインクリメントを捉えられることはほとんどありません。この 3 つのセッション終了時のカウンターが、このセクションの以降で言う終端カウンターです。sessions_started_total は起動時にインクリメントされ、セッションの存続期間中は表示され続けるため確実に現れますが、ワンショット環境では累積カウントというよりも「現在実行中のセッション」に近い値になります。

終端カウンターの代わりに、目的に応じて次の表の系列を使用してください。

orchestrator_* の行は、オンデマンドオーケストレーターを実行している環境にのみ存在します。ランナーがセッションより長く存続する（--drain-grace-sec が 0 より大きい）固定フリートでは、スループットに sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) を使用してください。ワンショットのフリートでは、その系列には終端カウンターと同じスクレイプウィンドウの問題があるため、代わりにキューに入ったセッションの数を頼りにしてください。ランナーはキュー深度の系列をエクスポートしないため、バックログは Cloud environments 管理ページにある環境の Activity タブで確認してください。

セッションごとの結果レポートには、代わりに post-session フックを使用してください。フック自体の規約のとおり、VM のプリエンプションなどによるランナーの突然の終了を除き、子プロセスが起動されたすべてのセッション終了時に発火します。

次のステップ

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