> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Referensi lingkungan yang di-host sendiri

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

<Note>
  Lingkungan yang di-host sendiri berada dalam beta publik pada paket Team dan Enterprise; seorang [Owner](/docs/id/cloud-environments#organization-shared-environments) mengaktifkannya dengan mengaktifkan **Allow self-hosted environments** di [halaman admin **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). Halaman ini adalah referensi flag dan metrik; lihat [quickstart](/docs/id/self-hosted-environments-quickstart) untuk setup dan [Deploy to production](/docs/id/self-hosted-environments-deploy) untuk resep fleet.
</Note>

Halaman ini adalah referensi untuk dua proses yang Anda jalankan dalam [lingkungan yang di-host sendiri](/docs/id/self-hosted-environments): runner, yang mengeksekusi Claude Code [cloud sessions](/docs/id/claude-code-on-the-web) 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`](#runner-cli-flags).

<h2 id="runner-cli-flags">
  Flag CLI Runner
</h2>

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](/docs/id/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners).                                                                                                                                                                                                                                                          |
| `--capacity <n>`                          | none                                              | `1`                                | Maksimum session bersamaan yang ditangani runner ini. Semua session milik [owner](/docs/id/self-hosted-environments#key-concepts) yang terkunci sama. Gunakan nilai yang sama di setiap runner dalam lingkungan; lihat [Keep the base directory and capacity identical across runners](/docs/id/self-hosted-environments-deploy#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`](#prometheus-metrics). 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](/docs/id/self-hosted-environments-deploy#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](/docs/id/self-hosted-environments-deploy#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](/docs/id/self-hosted-environments-deploy#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](/docs/id/self-hosted-environments-deploy#harden-your-deployment). Setelah sinyal pertama yang Anda tunda dengan [`--defer-shutdown-max-min`](/docs/id/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), 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`](/docs/id/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), 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-variable-only-settings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--environment-secret-file <path>`        | `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET`           | required                           | Path ke file yang berisi rahasia lingkungan, atau, untuk runner yang dihasilkan oleh [orchestrator](/docs/id/self-hosted-environments-configuration#on-demand-runners), 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](/docs/id/self-hosted-environments-configuration#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](/docs/id/self-hosted-environments-configuration#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`](#environment-variable-only-settings) berakhir. Sebelum v2.1.260, runner menghentikan session pada batas. Lihat [Some sessions don't count as idle](/docs/id/self-hosted-environments-deploy#some-sessions-don%E2%80%99t-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`](/docs/id/self-hosted-environments-configuration#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](/docs/id/self-hosted-environments-deploy#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](/docs/id/self-hosted-environments-deploy#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](/docs/id/self-hosted-environments-deploy#additional-limitations). Repositori yang diperiksa melalui hook lifecycle `checkout` tidak didorong; snapshot itu dari hook [`post-session`](/docs/id/self-hosted-environments-configuration#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`](#environment-variable-only-settings). 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`](/docs/id/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), 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](/docs/id/self-hosted-environments#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](/docs/id/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached), 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](/docs/id/self-hosted-environments-deploy#harden-your-deployment) memindainya terlepas dari flag ini.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--use-anthropic-git-proxy`               | `CLAUDE_RUNNER_USE_GIT_PROXY=1`                   | off                                | Clone melalui [Anthropic git proxy](/docs/id/self-hosted-environments-deploy#use-the-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.

<h2 id="orchestrator-cli-flags">
  Flag CLI Orchestrator
</h2>

Subperintah `self-hosted-runner orchestrator`, yang menghasilkan [on-demand runners](/docs/id/self-hosted-environments-configuration#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.                                                                                                                                                                                                   |

<h3 id="scm-connector-flags">
  Flag SCM connector
</h3>

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.

<h2 id="environment-variable-only-settings">
  Pengaturan variabel-lingkungan-saja
</h2>

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`](#runner-cli-flags) menjelaskan di mana hold berlaku pada drain dan idle release, dan [Runner lifecycle](/docs/id/self-hosted-environments#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](/docs/id/self-hosted-environments-configuration#mcp-servers), 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`                                                                                                                                                                                                                                                                                                                                                                                                        |

<h2 id="telemetry">
  Telemetry
</h2>

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](/docs/id/env-vars). `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](/docs/id/monitoring-usage), dan tidak mengontrol analytics Anthropic.

<h2 id="health-endpoint">
  Health endpoint
</h2>

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:

```json theme={null}
{
  "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](#scm-connector-flags) 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.

<h2 id="prometheus-metrics">
  Metrik Prometheus
</h2>

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](#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](#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](#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](#scm-connector-flags) 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](/docs/id/self-hosted-environments-deploy#kubernetes) atur; sesuaikan namespace untuk mencocokkan deployment Anda:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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"
```

<h3 id="pass-through-session-child-metrics">
  Pass through metrik session-child
</h3>

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](/docs/id/self-hosted-environments-configuration#wrapper-scripts) 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.

<h3 id="session-lifecycle-counter-semantics">
  Semantik counter lifecycle session
</h3>

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`](#environment-variable-only-settings) 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`](/docs/id/self-hosted-environments-configuration#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](/docs/id/self-hosted-environments-configuration#on-demand-runners). 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**](https://claude.ai/admin-settings/cloud-environments): runner tidak mengekspor seri queue-depth.

Untuk pelaporan outcome per-session, gunakan hook [`post-session`](/docs/id/self-hosted-environments-configuration#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](/docs/id/self-hosted-environments-configuration#post-session).

<h2 id="what’s-next">
  Apa selanjutnya
</h2>

* [Self-hosted environments](/docs/id/self-hosted-environments): lingkungan, runner, dan model session; [quickstart](/docs/id/self-hosted-environments-quickstart) dan [Deploy to production](/docs/id/self-hosted-environments-deploy) memegang setup dan operasi
* [Customize sessions](/docs/id/self-hosted-environments-configuration): wrapper script, lifecycle hook, dan on-demand runner
* [Verify session identity](/docs/id/self-hosted-environments-identity): session token, klaim-nya, dan cara memverifikasinya
