Skip to main content
Lingkungan yang di-host sendiri berada dalam beta publik pada paket Team dan Enterprise; seorang Owner mengaktifkannya dengan mengaktifkan Allow self-hosted environments di halaman admin Cloud environments. Halaman ini adalah referensi flag dan metrik; lihat quickstart untuk setup dan Deploy to production untuk resep fleet.
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. 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 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. 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:

​
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:
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: Orchestrator melayani seri sendiri di GET /metrics pada port yang sama seperti /healthz: 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:
Aturan alert sampel ini adalah titik awal; tune threshold untuk ukuran fleet Anda:

​
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: 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