SpyBara
Go Premium

self-hosted-environments-reference.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 342 additions and 0 deletions.

2026
Sat 12 03:02 Fri 18 23:58 Sat 19 23:57

Referensi lingkungan yang di-host sendiri

Referensi lengkap untuk runner dan orchestrator yang di-host sendiri: flag CLI, variabel lingkungan, dan metrik Prometheus.

Halaman ini adalah referensi untuk dua proses yang Anda jalankan dalam lingkungan yang di-host sendiri: runner, yang mengeksekusi Claude Code cloud sessions di host Anda, dan orchestrator autoscaling opsional, yang memulai runner saat session antri. Masing-masing memiliki tabel flag-nya sendiri. Keduanya berjalan di host Linux atau macOS, yang default seperti /workspace dan ~/.claude asumsikan. Jalankan claude self-hosted-runner --help untuk daftar otoritatif pada versi terinstal Anda.

Seri metrik dan beberapa field API masih menggunakan pool untuk apa yang halaman ini sebut lingkungan; kedua istilah menamakan hal yang sama. ID lingkungan adalah field pool_id, dengan bentuk ccpool_...: di mana pun halaman ini menunjukkan identifier pool, itu menamakan lingkungan. Flag CLI dan variabel lingkungan mengejanya environment, seperti --environment-secret-file; ejaan pool yang sudah usang masih berfungsi, seperti yang dijelaskan baris --environment-secret-file.

Flag CLI Runner

Sebagian besar flag memiliki variabel lingkungan yang sesuai. Ketika keduanya diatur, flag mengambil prioritas. Flag durasi mengambil menit atau detik di CLI, tetapi variabel lingkungan yang dipasangkan selalu dalam milidetik, ditunjukkan oleh suffix _MS, dan kolom Default menunjukkan unit flag: --exit-if-unused-min 10 setara dengan SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, dan nilai Helm seperti SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" berarti 15 milidetik, bukan default 15 menit.

Flag Env var Default Description
--api-url <url> none https://api.anthropic.com URL dasar API. Ganti hanya untuk pengujian.
--base-dir <path> SELF_HOSTED_RUNNER_BASE_DIR /workspace; tidak ada di Windows Direktori untuk checkout repositori dan direktori kerja per-session. Runner memerlukan akses tulis ke path ini atau induknya. Runner membuat direktori saat startup dan keluar dengan cannot create or write to base directory ketika tidak dapat membuat atau menulis ke dalamnya. Sebelum v2.1.225, runner membuat direktori ketika session pertama dimulai, jadi path yang tidak dapat digunakan gagal session daripada startup. Di Windows, yang bukan host runner yang didukung, tidak ada default: runner keluar saat startup kecuali Anda melewatkan flag atau mengatur variabel. Gunakan nilai yang sama di setiap runner dalam lingkungan. Lihat Keep the base directory and capacity identical across runners.
--capacity <n> none 1 Maksimum session bersamaan yang ditangani runner ini. Semua session milik owner yang terkunci sama. Gunakan nilai yang sama di setiap runner dalam lingkungan; lihat Keep the base directory and capacity identical across runners.
--client-label <label> SELF_HOSTED_RUNNER_CLIENT_LABEL hostname host Label yang dikirim runner saat mendaftar. Runner juga melaporkannya sebagai label client_label dari claude_code_self_hosted_runner_info. Memerlukan Claude Code v2.1.248 atau lebih baru.
--configure-git SELF_HOSTED_RUNNER_CONFIGURE_GIT=1 off Saat startup, tulis identitas git global, aktifkan penandatanganan commit Anthropic, aktifkan negosiasi push git, dan instal commit hooks yang menambahkan trailer Co-authored-by:. Negosiasi push memerlukan Claude Code v2.1.257 atau lebih baru. Lihat Configure git.
--confine-repo-settings <mode> SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS warn Menetapkan mode guard yang menandai session ketika pengaturan repositori yang berkomitmen mencoba memberikan akses tulis atau baca di luar workspace session sendiri, mengatur variabel lingkungan, atau mengganti postur sandbox atau hooks operator, seperti sandbox.enabled: false atau disableAllHooks. Default warn mencatat pelanggaran dan masih memulai session, enforce menolak session, dan off menonaktifkan pemindaian. Lihat Harden your deployment.
--debug-token-dir <path> SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR unset Tulis token langsung ke disk untuk inspeksi. Debug saja; jangan gunakan dalam produksi.
--defer-shutdown-max-min <n> SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS 0 Pada SIGTERM atau SIGINT pertama, terus melayani session yang sudah terpasang daripada mengalirnya, kemudian lepaskan apa pun yang masih terpasang N menit kemudian dan keluar. Naikkan timeout berhenti host Anda sebelum mengatur ini. Lihat Defer the drain past the first signal. 0 menonaktifkan. Memerlukan Claude Code v2.1.238 atau lebih baru.
--drain-grace-sec <n> SELF_HOSTED_RUNNER_DRAIN_GRACE_MS 0 Sampai runner menerima sinyal shutdown atau mencapai waktu pensiun, mengontrol kapan runner keluar setelah session aktifnya selesai: 0 keluar segera tanpa polling lebih lanjut, dan nilai positif membuat runner tetap hidup dan re-polling antrian owner yang terkunci untuk banyak detik itu terlebih dahulu, dengan biaya isolasi kontainer per-session yang dijelaskan di bagian hardening. Setelah sinyal pertama yang Anda tunda dengan --defer-shutdown-max-min, runner keluar segera setelah tidak memiliki session, apa pun yang Anda atur di sini.
--drain-wait-sec <n> SELF_HOSTED_RUNNER_DRAIN_WAIT_MS 0 Setelah drain dimulai, yang mana pada SIGTERM kecuali Anda mengatur --defer-shutdown-max-min, tunggu hingga N detik untuk setiap turn in-flight session dan background task selesai sebelum menghentikan child. Selama menunggu ini, runner menghitung background task yang baru saja selesai sebagai masih berjalan sampai turn follow-up yang membaca hasilnya dimulai, untuk paling banyak jendela SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS.
--environment-secret-file <path> SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET required Path ke file yang berisi rahasia lingkungan, atau, untuk runner yang dihasilkan oleh orchestrator, JWT work-order sekali pakai. SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET membawa nilai rahasia secara langsung, bukan path file. Flag --pool-secret-file yang lebih lama dan variabel SELF_HOSTED_RUNNER_POOL_SECRET masih berfungsi dan mencetak pemberitahuan deprecation ke stderr; build runner program preview yang lebih lama dari 2.1.216 hanya mengenali nama yang lebih lama itu.
--exec-path <path> SELF_HOSTED_RUNNER_EXEC_PATH binary sendiri Binary atau wrapper script untuk dihasilkan untuk setiap session. Lihat Wrapper scripts.
--exit-if-unused-min <n> SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS 0 Keluar setelah N menit polling tanpa pekerjaan yang pernah ditugaskan, untuk scale-down autoscaler. 0 menonaktifkan.
--git-host-rewrite <from>=<to> none unset Tulis ulang URL sumber https://<from>/... ke https://<to>/... sebelum cloning, untuk split-horizon DNS. Dapat diulang; flag saja.
--git-ssh-rewrite <host> none unset Tulis ulang URL sumber https://<host>/... ke git@<host>:... sebelum cloning, untuk git host SSH-only. Dapat diulang; flag saja.
--health-port <port> SELF_HOSTED_RUNNER_HEALTH_PORT 8080 Port untuk listener /healthz dan /metrics. Atur 0 untuk menonaktifkan.
--hooks-dir <path> SELF_HOSTED_RUNNER_HOOKS_DIR unset Direktori script hook lifecycle. Lihat Lifecycle hooks.
--kill-session-after-min <n> SELF_HOSTED_RUNNER_MAX_LIFETIME_MS 0 Batasi session ke N menit wall-clock, sebagai batas keselamatan untuk session yang macet. Pada v2.1.260 atau lebih baru, runner melepaskan session yang mencapai batas sehingga dapat dilanjutkan pada pesan berikutnya pengguna, dan menghentikannya hanya jika masih ada di runner ketika jendela grace SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS berakhir. Sebelum v2.1.260, runner menghentikan session pada batas. Lihat Some sessions don't count as idle untuk detail dan cara memilih nilai. 0 menonaktifkan.
--lock-to-account <id> SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT unset Pre-lock runner ke akun spesifik saat startup daripada mengunci pada session pertama. Menerima alamat email atau ID user_... dalam organisasi lingkungan. Runner yang pre-locked tidak pernah mengambil session Claude Tag channel, yang tidak memiliki akun.
--log-file <path> SELF_HOSTED_RUNNER_LOG_FILE unset Mirror log runner ke file selain stdout dan stderr, dibuat dengan izin 0600. Diperlukan untuk self-hosted-runner doctor untuk tail log secara lokal.
--log-level <level> none info info atau debug
--post-session-hook-timeout-sec <n> SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS 60 Anggaran untuk hook post-session di setiap akhir session, termasuk shutdown runner
--proxy-authorization-command <command> SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND unset Perintah shell yang dijalankan runner untuk setiap koneksi ke proxy egress Anda, menggunakan stdout yang dipangkas sebagai nilai header Proxy-Authorization. Memerlukan HTTPS_PROXY atau HTTP_PROXY, dan tidak dapat digabungkan dengan --proxy-authorization-file. Lihat Authenticate to an egress proxy. Memerlukan Claude Code v2.1.238 atau lebih baru.
--proxy-authorization-file <path> SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE unset File yang dibaca runner untuk setiap koneksi ke proxy egress Anda, menggunakan isinya yang dipangkas sebagai nilai header Proxy-Authorization. Gunakan flag ini untuk token yang proses lain rotasi di tempat. Membawa persyaratan yang sama dengan --proxy-authorization-command, dan tidak dapat digabungkan dengannya. Lihat Authenticate to an egress proxy. Memerlukan Claude Code v2.1.238 atau lebih baru.
--push-outcome-on-release SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE off Pada akhir session yang dimulai runner seperti drain atau idle release, push tracked outcome branch ke origin sebelum menghapus workspace, jadi commit in-flight bertahan restart. Best-effort; menambah 30 detik ke anggaran shutdown, dan memerlukan git 2.29 atau lebih baru untuk melanjutkan dari branch yang didorong. Batasi akses push ke ref claude/* sebelum mengaktifkan; lihat Resumed sessions lose unpushed work. Repositori yang diperiksa melalui hook lifecycle checkout tidak didorong; snapshot itu dari hook post-session sebagai gantinya.
--release-idle-session-min <n> SELF_HOSTED_RUNNER_SESSION_IDLE_MS 0 Lepaskan slot session setelah N menit inaktivitas setelah turn selesai atau session menunggu tindakan pengguna. Session yang masih mid-turn, termasuk yang menahan background task yang tidak pernah selesai atau persetujuan yang diminta dari dalam panggilan tool yang berjalan, tidak dihitung sebagai idle; pasangkan dengan --kill-session-after-min sebagai backstop keras. Setelah background task session selesai, runner menganggap session sibuk sampai turn follow-up yang membaca hasil dimulai, untuk paling banyak jendela SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS. Sampai runner menerima sinyal shutdown atau mencapai waktu pensiun, release yang meninggalkan runner tanpa session aktif memulai jalur keluar yang sama seperti drain normal, diatur oleh --drain-grace-sec. Setelah sinyal pertama yang Anda tunda dengan --defer-shutdown-max-min, runner keluar segera setelah release meninggalkannya tanpa session. 0 menonaktifkan.
--retire-at <epoch-seconds> SELF_HOSTED_RUNNER_RETIRE_AT unset Pensiun runner pada timestamp Unix absolut dalam detik, untuk infrastruktur yang membunuh runner pada waktu yang diketahui; Runner lifecycle menjelaskan urutan release dan cara mengukur margin. Nilai sebelum 2001 atau setelah tahun 5138 ditolak oleh flag dan diabaikan oleh variabel lingkungan.
--session-stop-grace-sec <n> SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS 5 Berapa lama menunggu proses Claude keluar dengan bersih setelah session berakhir, sebelum force-killing. Naikkan nilai jika hook SessionEnd child sendiri memerlukan lebih banyak waktu.
--startup-timeout-min <n> SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS 15 Lepaskan slot session jika child belum menandakan bahwa itu diinisialisasi dalam N menit spawn. Dihapus oleh sinyal init child di activity channel, bukan oleh output biasa, setelah itu --release-idle-session-min mengambil alih. 0 menonaktifkan.
--trust-workspace [bool] SELF_HOSTED_RUNNER_TRUST_WORKSPACE on Seed kepercayaan yang bertahan untuk setiap path repositori session sehingga permissions.allow dan additionalDirectories yang berkomitmen repo dihormati. Atur false untuk menghapus hibah izin yang berkomitmen repo dan mengonfigurasi aturan allow dalam settings.json konfigurasi host sebagai gantinya; pengaturan sandbox.* yang berkomitmen repo masih berlaku baik cara, itulah mengapa repo-settings guard memindainya terlepas dari flag ini.
--use-anthropic-git-proxy CLAUDE_RUNNER_USE_GIT_PROXY=1 off Clone melalui Anthropic git proxy daripada auth git yang dikelola pelanggan. Memerlukan --capacity 1 dan git 2.32 atau lebih baru; runner menolak untuk memulai sebaliknya. Menggantikan flag rewrite.

Sebagian besar flag durasi memiliki maksimum, dipilih untuk menjaga setiap timeout di dalam ceiling timer 32-bit runtime sekitar 24,85 hari. Flag --*-min cap pada 10080 menit, 7 hari; --drain-grace-sec pada 604800 detik, juga 7 hari; dan --drain-wait-sec pada 86400 detik, 24 jam. --session-stop-grace-sec dan --post-session-hook-timeout-sec tidak terbatas. Melampaui cap berperilaku berbeda per surface:

  • Flag: startup gagal dengan error.
  • Variabel lingkungan: runner menjepit nilai ke ceiling timer daripada menolaknya.

Flag CLI Orchestrator

Subperintah self-hosted-runner orchestrator, yang menghasilkan on-demand runners, menerima --api-url, --environment-secret-file, --hooks-dir, --health-port, dan --log-level dengan default yang sama seperti runner dan, di mana flag runner memiliki satu, variabel lingkungan yang sama, kecuali bahwa --hooks-dir diperlukan dan harus berisi hook spawn-runner. Ini juga mengambil flag sendiri:

Flag Default Description
--hook-concurrency <n> 4 Maksimum hook spawn-runner berjalan secara paralel. Juga membatasi berapa banyak permintaan spawn yang diklaim per poll.
--hook-timeout <sec> 60 Hentikan pohon proses hook setelah banyak detik ini. Timeout plus grace kill 5-detiknya harus tetap di bawah --expected-spawn-seconds; orchestrator memberlakukan ini saat startup.
--expected-spawn-seconds <sec> 120 Expected p99 boot time untuk runner yang dihasilkan, dalam range yang diberlakukan server 10 hingga 3600. Dikirim pada setiap poll sebagai lease server-side; jika tidak ada runner yang mendaftar sebelum itu berlalu, session ditawarkan kembali dengan ID pesanan segar. Semua replika harus berbagi nilai ini.
--min-idle <n> 0 Pertahankan setidaknya N slot session idle gratis dengan menghasilkan runner standby secara proaktif. 0 menonaktifkan pre-warming. Pasangkan dengan --exit-if-unused-min runner sehingga runner standby surplus merebut diri mereka sendiri.
--debug-dir <path> unset Tulis work order setiap permintaan spawn dan hook stderr ke disk. Debug saja; jangan pernah atur dalam produksi.

Flag SCM connector

Orchestrator dapat menahan koneksi WebSocket berdiri ke control plane Anthropic sehingga hosted pre-session flow, seperti repository picker dan branch atau ref resolver, dapat menjangkau host GitHub Enterprise Server yang hanya dapat dirutekan dari dalam jaringan Anda. Connector tetap off kecuali Anda mengatur --scm-connector-host.

Flag Default Description
--scm-connector-host <host[:port]> unset Hostname GitHub Enterprise Server untuk meneruskan permintaan ke. Port default ke 443. Mengatur flag ini mengaktifkan connector.
--scm-connector-id <n> required with --scm-connector-host ID numerik koneksi GitHub Enterprise Server organisasi Anda. Hubungi tim akun Anthropic Anda untuk nilai ketika Anda mengaktifkan connector.
--scm-connector-provider <slug> ghe Segmen path mengidentifikasi provider, cocok dengan ^[a-z0-9-]{1,32}$.
--scm-connector-ca-file <path> unset Bundle CA ekstra, dalam format PEM, untuk koneksi TLS ke host GitHub Enterprise Server.
--scm-connector-host-rewrite <from>=<to_host:to_port> unset Untuk pengujian end-to-end saja: mengalihkan koneksi TCP sambil menjaga header Host dan TLS SNI sebagai --scm-connector-host.

Connector mengautentikasi dengan rahasia lingkungan orchestrator yang ada dan reconnect secara otomatis: dengan exponential backoff pada koneksi yang dijatuhkan, atau delay tetap 30-detik ketika control plane menutup koneksi karena replika orchestrator lain sudah memegangnya.

Pengaturan variabel-lingkungan-saja

Pengaturan runner ini dibaca dari lingkungan saja dan mencakup perilaku yang sebagian besar deployment tinggalkan di default:

Env var Default Description
SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 30000 Berapa lama runner menganggap session sibuk setelah background task selesai sementara turn follow-up yang membaca hasil belum dimulai. Baris --drain-wait-sec dan --release-idle-session-min menjelaskan di mana hold berlaku pada drain dan idle release, dan Runner lifecycle menjelaskan di mana itu berlaku pada pensiun --retire-at. 0 atau nilai yang tidak dapat digunakan kembali ke default, jadi hold tidak dapat dimatikan. Memerlukan Claude Code v2.1.228 atau lebih baru.
SELF_HOSTED_RUNNER_HOST_CONFIG_DIR ~/.claude Direktori ditangkap ke snapshot startup runner dan disemai ke CLAUDE_CONFIG_DIR setiap session; perubahan di disk berlaku setelah restart runner. Mengatur variabel juga memindahkan di mana runner membaca .claude.json untuk MCP seeding, jadi mengaturnya, termasuk ke default sendiri, merelokasi lookup itu; arahkan ke direktori kosong untuk menonaktifkan seeding sepenuhnya.
SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS 900000 Berapa lama runner menunggu setelah session mencapai batas --kill-session-after-min, untuk turn yang sedang berjalan selesai atau release selesai, sebelum itu menghentikan session
SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS 30000 Berapa lama runner menunggu OS untuk mengirimkan SIGKILL ke child yang macet dalam I/O yang tidak dapat diinterupsi sebelum keluar sendiri. Floored pada --post-session-hook-timeout-sec plus 15 detik, dan 30 lebih banyak ketika --push-outcome-on-release diatur, jadi minimum efektif adalah 75 detik di default.
CLAUDE_RUNNER_FETCH_DEPTH 50 Git fetch depth untuk fresh clone. Atur integer positif, atau full atau 0 untuk fetch lengkap. Repositori yang sudah ada di workspace menjaga kedalaman yang ada.
CLAUDE_RUNNER_SKIP_GIT_VERIFY unset Ketika 1, lewati pemeriksaan kehadiran .git setelah hook checkout berjalan. Atur ini ketika hook Anda materialize sumber non-git.
FORCE_AUTOUPDATE_PLUGINS unset Ketika 1, biarkan marketplace plugin auto-update meskipun binary dipasang
CLAUDE_CODE_DISABLE_ARTIFACT unset Ketika 1, nonaktifkan tool Artifact dalam session terlepas dari pengaturan admin organisasi, dan lepaskan persyaratan egress *.frame.claudeusercontent.com

Telemetry

Child session mengirim telemetry operasional ke Anthropic kecuali Anda mematikannya. Tidak ada kode atau konten repositori yang dikirim. Atur variabel telemetry pada proses runner; runner re-assert mereka setelah menerapkan variabel lingkungan yang disediakan server, jadi pengaturan operator selalu mengambil prioritas.

Satu kontrol spesifik untuk lingkungan yang di-host sendiri: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 opt in ke metrik operasional Datadog, yang off secara default dalam lingkungan yang di-host sendiri. Kontrol telemetry Claude Code umum, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING, dan CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, berlaku untuk child session seperti yang didokumentasikan dalam referensi variabel lingkungan. DISABLE_GROWTHBOOK terkait tetapi berbeda: mengatur DISABLE_GROWTHBOOK=1 menonaktifkan pengambilan feature-flag, dan telemetry tetap on kecuali DISABLE_TELEMETRY juga diatur.

CLAUDE_CODE_ENABLE_TELEMETRY tidak terkait: itu mengaktifkan export OpenTelemetry ke collector Anda sendiri, seperti yang dijelaskan dalam Monitoring, dan tidak mengontrol analytics Anthropic.

Health endpoint

Runner melayani GET /healthz pada port health yang dikonfigurasi. Respons adalah 200 OK kapan pun proses hidup, apa pun state poll loop, jadi probe HTTP pada endpoint ini mendeteksi proses mati saja. Badan JSON menjelaskan state saat ini:

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

Gunakan last_poll_age_ms sebagai sinyal liveness dalam probe kustom; nilai yang tumbuh tanpa batas menunjukkan poll loop macet. Baik last_poll_at dan last_poll_age_ms adalah null sampai poll pertama selesai.

Orchestrator melayani /healthz sendiri pada port health-nya. Endpoint-nya selalu mengembalikan 200, dan badan membawa field connected melaporkan apakah poll terbaru berhasil, plus spawn-queue count per-state dalam queue_counts. Gate readiness dan alerting pada connected daripada status code.

Ketika SCM connector dikonfigurasi, badan /healthz orchestrator juga membawa scm_connector_connected dan objek scm_connector dengan connected, last_connected_at, last_error, reconnects, dan requests_forwarded. Kedua field adalah null ketika --scm-connector-host tidak diatur.

Metrik Prometheus

Setiap runner melayani metrik Prometheus di GET /metrics pada port yang sama seperti /healthz. Seri kunci:

Series Notes
claude_code_self_hosted_runner_info{runner_id,version,client_label} Selalu 1; berguna untuk inventori fleet dan deteksi version-drift
claude_code_self_hosted_runner_capacity --capacity yang dikonfigurasi
claude_code_self_hosted_runner_active_sessions Session yang sedang berjalan
claude_code_self_hosted_runner_locked_account{email} Hadir setelah runner telah mengunci ke pengguna dan session token membawa klaim act.email telah dikeluarkan. Seri tidak ada pada runner yang terkunci ke agen Claude Tag, yang session token-nya tidak membawa act.email. Nilai label adalah email akun; jika metrics store Anda secara luas dapat dibaca, lepaskan atau hash label pada scrape time, misalnya dengan Prometheus metric_relabel_configs.
claude_code_self_hosted_runner_last_poll_age_seconds Detik sejak poll terakhir yang berhasil. Alert jika lebih dari 60.
claude_code_self_hosted_runner_poll_errors_total{error_kind} Kegagalan PollWork kumulatif berdasarkan jenis: transport, timeout, 5xx, 429, atau 4xx. Semua lima seri hadir dari proses start; alert pada rate(...[5m]) > 0.
claude_code_self_hosted_runner_sessions_started_total{client_platform} Proses child session yang dihasilkan selama lifetime runner, satu seri per asal session seperti web_claude_ai, ios, android, desktop_app, atau claude_code_cli, atau unknown ketika server tidak mengirim satu. Session Slack membawa baik claude_in_slack atau claude-in-slack tergantung integrasi Slack mana yang membuatnya, jadi cocokkan keduanya dengan selector regex seperti {client_platform=~"claude[-_]in[-_]slack"}. Gunakan sum() untuk total fleet.
claude_code_self_hosted_runner_sessions_completed_total{client_platform} Session yang berakhir dengan bersih, berlabel dengan cara yang sama. Lebih luas daripada plain clean exit: lihat session lifecycle counter semantics untuk apa yang dihitung.
claude_code_self_hosted_runner_sessions_failed_total{client_platform} Session yang berakhir dalam kegagalan, berlabel dengan cara yang sama. Caveat yang sama: lihat session lifecycle counter semantics.
claude_code_self_hosted_runner_sessions_interrupted_total{client_platform} Session yang runner hentikan untuk alasan operasional daripada outcome session, berlabel dengan cara yang sama. Lihat session lifecycle counter semantics.
claude_code_self_hosted_runner_initializing_sessions Session yang sedang dalam fase init, dari assignment sampai event init child
claude_code_self_hosted_runner_session_init_duration_seconds Histogram durasi init session
claude_code_self_hosted_runner_session_init_errors_total Session yang gagal sebelum mencapai init: kegagalan hook checkout, git prep, masalah token, atau crash child pre-init
claude_code_self_hosted_runner_session_start_hook_errors_total Hook SessionStart yang melaporkan outcome error, satu per eksekusi hook yang gagal
claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform} Gauge per-session detik sejak session menjadi idle. Berguna untuk menghentikan session yang macet pada prompt izin yang tidak dijawab.

Orchestrator melayani seri sendiri di GET /metrics pada port yang sama seperti /healthz:

Series Notes
claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname} Selalu 1
claude_code_self_hosted_orchestrator_connected 1 ketika poll terbaru berhasil; turun ke 0 setelah poll yang gagal, apa pun jenis kegagalan
claude_code_self_hosted_orchestrator_last_poll_age_seconds Detik sejak upaya poll terakhir, sukses atau gagal, tidak seperti metrik runner yang identik, yang mengukur sejak sukses terakhir; pasangkan dengan connected untuk menangkap poll yang gagal. Poll loop orchestrator menunggu eksekusi hook, jadi alert di atas --hook-timeout plus margin, sekitar 90 detik di default, daripada flat 60.
claude_code_self_hosted_orchestrator_poll_errors_total{error_kind} Kegagalan PollSpawnHints kumulatif berdasarkan jenis: transport, timeout, 5xx, 429, atau 4xx. Semua lima seri hadir dari proses start; alert pada rate(...[5m]) > 0.
claude_code_self_hosted_orchestrator_queue_pending_sessions Spawn request yang dapat diklaim sekarang
claude_code_self_hosted_orchestrator_queue_backing_off_sessions Spawn request dalam retry backoff setelah kegagalan hook yang dapat dicoba ulang
claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions Spawn request diblokir sampai Owner mencoba ulang dari tab Activity lingkungan; alert jika di atas nol
claude_code_self_hosted_orchestrator_pool_pending_sessions Total session menunggu runner untuk lingkungan ini. Agregat environment-wide, identik di setiap instance orchestrator: gunakan MAX daripada SUM di seluruh instance.
claude_code_self_hosted_orchestrator_pool_active_sessions Session yang saat ini ditugaskan ke runner yang hidup dalam lingkungan ini. Agregat environment-wide, identik di setiap instance orchestrator: gunakan MAX daripada SUM di seluruh instance.
claude_code_self_hosted_orchestrator_spawn_hooks_total{result} Outcome hook spawn-runner kumulatif: ok, retryable, non_retryable. Menghitung invokasi hook orchestrator, bukan child session yang dihasilkan runner: tidak dapat dibandingkan dengan sessions_started_total, karena kapasitas di atas satu, warm pool, dan runner yang dihasilkan lagi untuk session yang sama semua menyimpang keduanya.
claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds Histogram durasi hook
claude_code_self_hosted_orchestrator_warm_hints_dispatched_total Spawn request standby dikirim sejak proses start
claude_code_self_hosted_orchestrator_session_queue_wait_seconds Histogram detik setiap session menunggu dalam antrian sebelum orchestrator mengklaimnya untuk spawn, dicatat dari timestamp queue-wait yang control plane kirim dengan setiap spawn request session. Gunakan untuk p50/p99 queue-time alerting. Pre-warming spawn tidak diambil sampel.
claude_code_self_hosted_orchestrator_clock_skew_seconds Local-minus-server clock skew; diagnostik, hadir setelah diukur
claude_code_self_hosted_orchestrator_scm_connector_connected 1 ketika WebSocket SCM connector terbuka; 0 saat dialing atau backing off. Tidak ada ketika --scm-connector-host tidak diatur.
claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total Permintaan HTTP kumulatif yang di-proxy ke host SCM yang dikonfigurasi sejak proses start. Tidak ada ketika --scm-connector-host tidak diatur.

Untuk autoscaling, pilih seri yang cocok dengan gaya scaling Anda dan gate sebelum itu memberi makan scaler:

  • Queue-depth scaling: feed claude_code_self_hosted_orchestrator_pool_pending_sessions ke HPA atau KEDA scaler Anda, bukan queue_pending_sessions.
  • Capacity scaling: scale pada rasio active_sessions runner ke capacity.
  • Gate on connected: filter query dengan claude_code_self_hosted_orchestrator_connected == 1 per instance, jadi nilai stale replika yang terputus tidak memberi makan scaler.

Selama outage poll penuh, setiap replika terputus, query yang di-gate mengembalikan tidak ada data. HPA menahan jumlah replika saat ini pada metrik yang hilang, tetapi Prometheus scaler KEDA pada default ignoreNullValues: "true" membaca hasil kosong sebagai nol dan scale in; atur ignoreNullValues: "false" pada ScaledObject, secara opsional dengan floor replika fallback.

Prometheus Operator PodMonitor berikut mencakup kedua proses. Ini memilih pod berdasarkan label app.kubernetes.io/part-of: claude-code-self-hosted-runner dan port bernama health yang resep Kubernetes atur; sesuaikan namespace untuk mencocokkan deployment Anda:

# Example Prometheus Operator PodMonitor untuk Claude Code self-hosted
# runner + orchestrator. Sesuaikan namespace dan label selector untuk mencocokkan
# deployment Anda. Baik runner dan orchestrator melayani /metrics pada
# --health-port mereka (default 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Cocok dengan Deployment runner dari resep Kubernetes, plus apa pun
      # on-demand runner Jobs dan orchestrator pod yang Anda label dengan cara yang sama
      # dan berikan containerPort bernama 'health'.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Aturan alert sampel ini adalah titik awal; tune threshold untuk ukuran fleet Anda:

# Contoh aturan alert Prometheus untuk Claude Code self-hosted runner
# + orchestrator. Tune threshold untuk ukuran fleet dan SLO Anda.
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 }} belum poll dalam >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runner menjalankan versi campuran"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 session init failures dalam 10m (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 gagal ({{ $value | humanize }}/s selama 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 SessionStart hook failures dalam 10m"

  - 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 }} tidak dapat menjangkau control plane Anthropic"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} belum poll dalam >90s (poll loop menunggu eksekusi hook)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "{{ $value }} session circuit-broken — spawn-runner hook berulang kali non-retryable; perbaiki infra kemudian coba ulang dari tab Activity"
      - 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 gagal ({{ $value | humanize }}/s selama 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 dalam 5m"

Pass through metrik session-child

Setiap session berjalan dalam proses child sendiri dengan metrik OpenTelemetry sendiri; pada --capacity di atas satu, runner menulis ulang bagaimana metrik child itu diekspos. Mengatur OTEL_METRICS_EXPORTER=prometheus pada host runner dan CLAUDE_CODE_ENABLE_TELEMETRY=1 dalam lingkungan session, misalnya dari wrapper script Anda atau lingkungan runner sendiri, yang session warisi, re-expose setiap counter dan gauge instrument child pada endpoint /metrics runner sendiri, bersama seri runner. Runner menulis ulang exporter child untuk push melalui OTLP ke receiver loopback-only pada port health, tag setiap seri dengan label session_id dan client_platform, dan evict seri session ketika session itu berakhir. Histogram tidak pass through, dan metrik child yang nama-nya akan bertabrakan dengan prefix runner sendiri dijatuhkan.

Pada default --capacity 1, rewrite tidak berlaku: child session mengikat endpoint Prometheus sendiri pada port 9464 seperti biasa.

Semantik counter lifecycle session

Counter sessions_started_total, sessions_completed_total, sessions_failed_total, dan sessions_interrupted_total mengklasifikasikan setiap session berdasarkan bagaimana itu berakhir. Setiap child session yang dihasilkan menambah sessions_started_total pada waktu spawn, dan tepat satu dari tiga lainnya menambah pada exit, jadi sessions_started_total minus jumlah tiga lainnya sama dengan jumlah child session yang sedang berjalan.

  • completed: session berakhir dengan bersih. Ini mencakup child keluar sendiri dengan kode 0, session diarsipkan atau dihapus sementara child masih terhubung, dan runner menyerahkan kembali slot dengan bersih: melepaskan session pada idle timeout, waktu retire, atau limit --kill-session-after-min; startup timeout; atau server-side deassign yang diperhatikan poll loop sebelum child keluar. Menambah sessions_completed_total.
  • failed: child keluar sendiri dengan kode non-nol, baik crash atau setup failure setelah spawn. Menambah sessions_failed_total.
  • interrupted: runner menghentikan child untuk alasan operasional yang bukan kesuksesan session maupun fault runner, seperti drain, atau menghentikan session yang masih ada di runner ketika jendela grace SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS setelah limit --kill-session-after-min berakhir. Kubernetes rolling restart mengirim SIGTERM adalah satu contoh drain. Menambah sessions_interrupted_total.

Sebelum v2.1.260, runner menghentikan setiap session yang mencapai limit --kill-session-after-min dan menghitungnya dalam sessions_interrupted_total.

Hook post-session CLAUDE_RUNNER_EXIT_REASON mengklasifikasikan clean handoff secara berbeda. Hook melaporkan release, startup timeout, dan server deassign sebagai interrupted, karena runner menghentikan child. Counter ini mencatat event yang sama sebagai completed, karena slot diserahkan dengan bersih.

Jika Anda merekonsiliasi penerimaan hook terhadap sessions_completed_total secara langsung, Anda kurang menghitung completion. Gunakan hook untuk jaminan per-session dan counter untuk rate agregat.

Pada lingkungan one-shot, --capacity 1 dengan default --drain-grace-sec 0, setiap proses runner keluar sesaat setelah session satu-nya berakhir. sessions_completed_total, sessions_failed_total, dan sessions_interrupted_total menambah hanya pada akhir session, tepat sebelum exit itu, jadi Prometheus scrape setiap 15 hingga 60 detik jarang menangkap increment sebelum seri runner menghilang; tiga counter akhir-session ini adalah counter terminal yang sisa bagian ini merujuk. sessions_started_total menambah pada spawn dan tetap terlihat untuk kehidupan session, jadi itu secara andal menunjukkan, tetapi pada lingkungan one-shot itu membaca lebih dekat ke "session yang sedang berjalan" daripada count kumulatif.

Gunakan seri dalam tabel ini untuk goal yang sesuai daripada counter terminal:

Goal Use
Throughput claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}, counter pada orchestrator long-lived yang menambah sekali per hook spawn-runner yang berhasil dan tetap bermakna di bawah rate(). Ini menghitung invokasi hook daripada session, jadi pre-warming dan spawn berulang untuk session yang sama menyimpang itu dari session count.
Utilization sum(claude_code_self_hosted_runner_active_sessions) terhadap sum(claude_code_self_hosted_runner_capacity), kedua gauge valid di setiap scrape terlepas dari lifetime runner
Backlog claude_code_self_hosted_orchestrator_pool_pending_sessions untuk queue depth, dan claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions, alert jika di atas nol
Failures claude_code_self_hosted_runner_sessions_failed_total, best effort: crash nyata setelah spawn memang menambahnya, dan rate() bermakna pada runner yang outlive session mereka dengan --drain-grace-sec di atas 0. Lingkungan one-shot memiliki masalah scrape-window yang sama seperti counter terminal lainnya, jadi perlakukan nilai non-nol apa pun yang Anda lihat sebagai layak diselidiki. Kegagalan sebelum spawn, seperti kegagalan hook checkout, persiapan git, atau masalah token, muncul hanya dalam session_init_errors_total.

Baris orchestrator_* ada hanya pada lingkungan yang menjalankan on-demand orchestrator. Pada fleet tetap yang runner outlive session mereka, dengan --drain-grace-sec di atas 0, gunakan sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) untuk throughput; pada fleet one-shot seri itu memiliki masalah scrape-window yang sama seperti counter terminal, jadi andalkan queue-sessions count sebagai gantinya. Periksa backlog pada tab Activity lingkungan, pada halaman admin Cloud environments: runner tidak mengekspor seri queue-depth.

Untuk pelaporan outcome per-session, gunakan hook post-session sebagai gantinya: itu api di setiap akhir session di mana proses child dihasilkan, terlepas dari terminasi runner yang tiba-tiba seperti preemption VM, per kontrak hook sendiri.

Apa selanjutnya