Riferimento per ambienti self-hosted

Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; un Owner li abilita attivando Allow self-hosted environments nella pagina di amministrazione Cloud environments. Questa pagina è il riferimento per flag e metriche; consultare la guida rapida per la configurazione e Deploy to production per le ricette della flotta.

Questa pagina è il riferimento per i due processi che eseguite in un ambiente self-hosted: il runner, che esegue le sessioni cloud di Claude Code sui vostri host, e l’orchestrator di autoscaling opzionale, che avvia i runner mentre le sessioni si accodano. Ognuno ha la propria tabella di flag. Entrambi vengono eseguiti su host Linux o macOS, per i quali i valori predefiniti come /workspace e ~/.claude sono presupposti. Eseguite claude self-hosted-runner --help per l’elenco autorevole sulla vostra versione installata. Le serie di metriche e alcuni campi API utilizzano ancora pool per quello che queste pagine chiamano un ambiente; entrambi i termini denominano la stessa cosa. L’ID dell’ambiente è il campo pool_id, con la forma ccpool_...: ovunque queste pagine mostrino un identificatore pool, esso denomina l’ambiente. I flag CLI e le variabili d’ambiente lo scrivono come environment, come in --environment-secret-file; i nomi deprecati pool continuano a funzionare, come la riga --environment-secret-file descrive.

Flag CLI del runner

La maggior parte dei flag ha una variabile d’ambiente corrispondente. Quando entrambi sono impostati, il flag ha la precedenza. I flag di durata accettano minuti o secondi sulla CLI, ma la variabile d’ambiente associata è sempre in millisecondi, indicata dal suffisso _MS, e la colonna Default mostra l’unità del flag: --exit-if-unused-min 10 è equivalente a SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, e un valore Helm come SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" significa 15 millisecondi, non il valore predefinito di 15 minuti.

Flag	Env var	Default	Description
`--api-url <url>`	none	`https://api.anthropic.com`	URL base dell’API. Eseguire l’override solo per i test.
`--base-dir <path>`	`SELF_HOSTED_RUNNER_BASE_DIR`	`/workspace`; nessuno su Windows	Directory per i checkout dei repository e le directory di lavoro per sessione. Il runner necessita dell’accesso in scrittura a questo percorso o al suo genitore. Il runner crea la directory all’avvio e esce con `cannot create or write to base directory` quando non riesce a crearla o scrivervi. Prima della v2.1.225, il runner creava la directory quando la prima sessione iniziava, quindi un percorso inutilizzabile causava il fallimento delle sessioni piuttosto che dell’avvio. Su Windows, che non è un host runner supportato, non c’è un valore predefinito: il runner esce all’avvio a meno che non passi il flag o imposti la variabile. Usa lo stesso valore su ogni runner in un ambiente. Vedi Keep the base directory and capacity identical across runners.
`--capacity <n>`	none	`1`	Numero massimo di sessioni simultanee che questo runner gestisce. Tutte le sessioni appartengono allo stesso owner bloccato. Usa lo stesso valore su ogni runner in un ambiente; vedi Keep the base directory and capacity identical across runners.
`--client-label <label>`	`SELF_HOSTED_RUNNER_CLIENT_LABEL`	l’hostname dell’host	Etichetta che il runner invia quando si registra. Il runner lo segnala anche come etichetta `client_label` di `claude_code_self_hosted_runner_info`. Richiede Claude Code v2.1.248 o successivo.
`--configure-git`	`SELF_HOSTED_RUNNER_CONFIGURE_GIT=1`	off	All’avvio, scrivi l’identità git globale, abilita la firma dei commit Anthropic, attiva la negoziazione push di git e installa hook di commit che aggiungono un trailer `Co-authored-by:`. La negoziazione push richiede Claude Code v2.1.257 o successivo. Vedi Configure git.
`--confine-repo-settings <mode>`	`SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS`	`warn`	Imposta la modalità della guardia che contrassegna una sessione quando le impostazioni impegnate di un repository tentano di concedere accesso in scrittura o lettura al di fuori dello spazio di lavoro della sessione, impostare variabili d’ambiente o eseguire l’override della postura sandbox o hooks dell’operatore, come `sandbox.enabled: false` o `disableAllHooks`. Il valore predefinito `warn` registra la violazione e avvia comunque la sessione, `enforce` rifiuta la sessione e `off` disabilita la scansione. Vedi Harden your deployment.
`--debug-token-dir <path>`	`SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR`	unset	Scrivi i token live su disco per l’ispezione. Solo debug; non usare in produzione.
`--defer-shutdown-max-min <n>`	`SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS`	`0`	Al primo `SIGTERM` o `SIGINT`, continua a servire le sessioni già collegate invece di drenare, quindi rilascia tutto ciò che è ancora collegato N minuti dopo e esci. Aumenta il timeout di arresto del tuo host prima di impostare questo. Vedi Defer the drain past the first signal. `0` disabilita. Richiede Claude Code v2.1.238 o successivo.
`--drain-grace-sec <n>`	`SELF_HOSTED_RUNNER_DRAIN_GRACE_MS`	`0`	Fino a quando il runner riceve un segnale di arresto o raggiunge il suo tempo di ritiro, controlla quando il runner esce dopo che le sue sessioni attive finiscono: `0` esce immediatamente senza polling per altri, e un valore positivo mantiene il runner attivo e ri-polling della coda dell’owner bloccato per quel numero di secondi, al costo dell’isolamento del contenitore per sessione descritto nella sezione hardening. Dopo un primo segnale che hai differito con `--defer-shutdown-max-min`, il runner esce non appena non contiene sessioni, indipendentemente da quello che imposti qui.
`--drain-marker-file <path>`	`SELF_HOSTED_RUNNER_DRAIN_MARKER_FILE`	unset	File marcatore che il tuo host scrive per annunciare un drenaggio elegante prima di inviare `SIGTERM`. Quando il file esiste all’inizio del drenaggio, il runner segnala la sua uscita ad Anthropic come un drenaggio dell’host piuttosto che un semplice segnale di arresto. Il drenaggio stesso, inclusa la sospensione `--drain-wait-sec`, funziona allo stesso modo senza il flag. Nomina un percorso su un filesystem locale che le sessioni non possono scrivere. Richiede Claude Code v2.1.271 o successivo.
`--drain-wait-sec <n>`	`SELF_HOSTED_RUNNER_DRAIN_WAIT_MS`	`0`	Una volta che il drenaggio inizia, che è su `SIGTERM` a meno che non imposti `--defer-shutdown-max-min`, attendi fino a N secondi affinché il turno in volo di ogni sessione e le attività in background finiscano prima di terminare il figlio. Durante questa attesa, il runner conta un’attività in background che ha appena finito come ancora in esecuzione fino a quando il turno di follow-up che legge il suo risultato inizia, per al massimo la finestra `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`. Aumenta anche il tuo timeout di arresto.
`--environment-secret-file <path>`	`SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET`	required	Percorso a un file contenente il segreto dell’ambiente, o, per i runner generati dall’orchestrator, il JWT del work-order monouso. `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` porta il valore del segreto direttamente, non un percorso di file. Il flag `--pool-secret-file` più vecchio e la variabile `SELF_HOSTED_RUNNER_POOL_SECRET` ancora funzionano e stampano un avviso di deprecazione su stderr; le build del runner del programma di anteprima più vecchie di 2.1.216 riconoscono solo quei nomi più vecchi.
`--exec-path <path>`	`SELF_HOSTED_RUNNER_EXEC_PATH`	own binary	File binario o script wrapper da generare per ogni sessione. Vedi Wrapper scripts.
`--exit-if-unused-min <n>`	`SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS`	`0`	Esci dopo N minuti di polling senza lavoro mai assegnato, per il scale-down dell’autoscaler. `0` disabilita.
`--git-host-rewrite <from>=<to>`	none	unset	Riscrivi gli URL di origine `https://<from>/...` a `https://<to>/...` prima della clonazione, per DNS a orizzonte diviso. Ripetibile; solo flag.
`--git-ssh-rewrite <host>`	none	unset	Riscrivi gli URL di origine `https://<host>/...` a `git@<host>:...` prima della clonazione, per host git solo SSH. Ripetibile; solo flag.
`--health-port <port>`	`SELF_HOSTED_RUNNER_HEALTH_PORT`	`8080`	Porta per il listener `/healthz` e `/metrics`. Imposta `0` per disabilitare.
`--hooks-dir <path>`	`SELF_HOSTED_RUNNER_HOOKS_DIR`	unset	Directory degli script hook del ciclo di vita. Vedi Lifecycle hooks.
`--host-config-snapshot <mode>`	`SELF_HOSTED_RUNNER_HOST_CONFIG_SNAPSHOT`	`disk`	Dove il runner mantiene lo snapshot di avvio della directory di configurazione dell’host che semina ogni sessione da. `disk` copia lo snapshot in una directory di proprietà del runner sotto `--base-dir` e, all’inizio di ogni sessione, verifica ogni file rispetto a un digest in memoria. Se un file nella copia è stato modificato, la sessione fallisce e il runner rifiuta le sessioni fino a quando non lo riavvii. `memory` mantiene l’intero snapshot sull’heap, limitato a 64 MiB; oltre il limite, le sessioni iniziano senza configurazione dell’host e mostrano un avviso che dice così. Quando il runner non può scrivere lo snapshot del disco, registra l’errore e usa `memory` per quella esecuzione. Richiede Claude Code v2.1.271 o successivo.
`--kill-session-after-min <n>`	`SELF_HOSTED_RUNNER_MAX_LIFETIME_MS`	`0`	Limita una sessione a N minuti di tempo reale, come limite di sicurezza per le sessioni bloccate. Su v2.1.260 o successivo, il runner rilascia una sessione che raggiunge il limite in modo che possa riprendere al prossimo messaggio dell’utente, e la termina solo se è ancora sul runner quando la finestra di grazia `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` finisce. Prima della v2.1.260, il runner terminava la sessione al limite. Vedi Some sessions don’t count as idle per i dettagli e come scegliere un valore. `0` disabilita.
`--lock-to-account <id>`	`SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT`	unset	Pre-blocca il runner a un account specifico all’avvio invece di bloccare alla prima sessione. Accetta un indirizzo email o un ID `user_...` nell’organizzazione dell’ambiente. Un runner pre-bloccato non raccoglie mai sessioni del canale Claude Tag, che non hanno account.
`--log-file <path>`	`SELF_HOSTED_RUNNER_LOG_FILE`	unset	Specchia i log del runner in un file oltre a stdout e stderr, creato con permessi `0600`. Richiesto per `self-hosted-runner doctor` per accodare i log localmente.
`--log-level <level>`	none	`info`	`info` o `debug`
`--post-session-hook-timeout-sec <n>`	`SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS`	`60`	Budget per l’hook `post-session` alla fine di ogni sessione, incluso l’arresto del runner
`--proxy-authorization-command <command>`	`SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND`	unset	Comando shell che il runner esegue per ogni connessione al tuo proxy di uscita, usando il suo stdout ritagliato come valore dell’intestazione `Proxy-Authorization`. Richiede `HTTPS_PROXY` o `HTTP_PROXY`, e non può essere combinato con `--proxy-authorization-file`. Vedi Authenticate to an egress proxy. Richiede Claude Code v2.1.238 o successivo.
`--proxy-authorization-file <path>`	`SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE`	unset	File che il runner legge per ogni connessione al tuo proxy di uscita, usando i suoi contenuti ritagliati come valore dell’intestazione `Proxy-Authorization`. Usa questo flag per un token che un altro processo ruota in posizione. Porta gli stessi requisiti di `--proxy-authorization-command`, e non può essere combinato con esso. Vedi Authenticate to an egress proxy. Richiede Claude Code v2.1.238 o successivo.
`--push-outcome-on-release`	`SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE`	off	Alla fine di una sessione avviata dal runner come un drenaggio o una versione inattiva, esegui il push dei rami di risultato tracciati a `origin` prima di eliminare lo spazio di lavoro, in modo che i commit in volo sopravvivano a un riavvio. Best-effort; aggiunge 30 secondi al budget di arresto, e richiede git 2.29 o più recente per riprendere dal ramo sottoposto a push. Limita l’accesso push ai ref `claude/*` prima di abilitare; vedi Resumed sessions lose unpushed work. I repository estratti tramite un hook del ciclo di vita `checkout` non vengono sottoposti a push; fai uno snapshot di quelli dall’hook `post-session` invece.
`--release-idle-session-min <n>`	`SELF_HOSTED_RUNNER_SESSION_IDLE_MS`	`0`	Rilascia uno slot di sessione dopo N minuti di inattività una volta che un turno finisce o la sessione attende l’azione dell’utente. Una sessione che è ancora a metà turno, inclusa una che contiene un compito in background che non finisce mai o un’approvazione richiesta dall’interno di una chiamata di strumento in esecuzione, non conta come inattiva; abbina con `--kill-session-after-min` come backstop duro. Dopo che il compito in background di una sessione finisce, il runner considera la sessione occupata fino a quando il turno di follow-up che legge il risultato inizia, per al massimo la finestra `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`. Fino a quando il runner riceve un segnale di arresto o raggiunge il suo tempo di ritiro, un rilascio che lascia il runner senza sessioni attive avvia lo stesso percorso di uscita di un drenaggio normale, governato da `--drain-grace-sec`. Dopo un primo segnale che hai differito con `--defer-shutdown-max-min`, il runner esce non appena un rilascio lo lascia senza sessioni. `0` disabilita.
`--remove-session-state [bool]`	`SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE`	off	Rimuovi le directory per sessione di una sessione sotto `<base-dir>/_sessions/` quando la sessione termina su questo runner, indipendentemente dall’esito. Reuse a pre-warmed checkout descrive cosa contengono e chi può leggerli quando rimangono. La rimozione è best-effort: le directory per sessione rimangono in posizione quando il runner viene ucciso o raggiunge la scadenza di drenaggio prima che la pulizia venga eseguita. Con il flag attivo, il log di debug di una sessione fallita o interrotta non viene mantenuto su disco. Richiede Claude Code v2.1.268 o successivo.
`--retire-at <epoch-seconds>`	`SELF_HOSTED_RUNNER_RETIRE_AT`	unset	Ritira il runner a un timestamp Unix assoluto in secondi, per l’infrastruttura che uccide il runner a un’ora nota; Runner lifecycle descrive la sequenza di rilascio e come dimensionare il margine. I valori prima del 2001 o dopo l’anno 5138 vengono rifiutati dal flag e ignorati dalla variabile d’ambiente.
`--server-auto-mode-lists <mode>`	`SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS`	`no-allow`	Quali degli elenchi di regole del classificatore della modalità auto che il control plane invia con una sessione possono raggiungere quella sessione: `all`, `no-allow` o `none`. Vedi Elenchi di regole della modalità auto per cosa applica ciascun valore. Un valore non valido arresta il runner all’avvio. Richiede Claude Code v2.1.295 o successivo.
`--session-stop-grace-sec <n>`	`SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS`	`5`	Quanto tempo aspettare affinché il processo Claude esca correttamente dopo la fine di una sessione, prima di forzare l’uccisione. Aumenta il valore se gli hook `SessionEnd` del figlio hanno bisogno di più tempo.
`--startup-timeout-min <n>`	`SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS`	`15`	Quanto tempo attendere un processo figlio che non si è inizializzato prima di rilasciare lo slot della sessione. Vedi Timeout di avvio della sessione per sapere da dove parte il conteggio e quali sessioni lascia in esecuzione. `0` disabilita il timeout.
`--trust-workspace [bool]`	`SELF_HOSTED_RUNNER_TRUST_WORKSPACE`	on	Semina la fiducia persistente per i percorsi del repository di ogni sessione in modo che `permissions.allow` e `additionalDirectories` impegnati nel repo siano onorati. Imposta `false` per eliminare le concessioni di autorizzazione impegnate nel repo e configurare le regole di autorizzazione nella `settings.json` della configurazione dell’host; le impostazioni `sandbox.*` impegnate nel repository si applicano comunque in entrambi i casi, motivo per cui la guardia repo-settings le scansiona indipendentemente da questo flag.
`--use-anthropic-git-proxy`	`CLAUDE_RUNNER_USE_GIT_PROXY=1`	off	Clona i repository su github.com tramite il proxy git di Anthropic invece dell’autenticazione git gestita dal cliente. Richiede `--capacity 1` e git 2.32 o più recente; il runner rifiuta di avviarsi altrimenti. Sostituisce i flag di riscrittura.

La maggior parte dei flag di durata ha un massimo, scelto per mantenere ogni timeout entro il limite del timer a 32 bit del runtime di circa 24,85 giorni. I flag --*-min hanno un limite di 10080 minuti, 7 giorni; --drain-grace-sec a 604800 secondi, anche 7 giorni; e --drain-wait-sec a 86400 secondi, 24 ore. --session-stop-grace-sec e --post-session-hook-timeout-sec non hanno limiti. Superare un limite si comporta diversamente per superficie:

Flag: l’avvio fallisce con un errore.
Variabile d’ambiente: il runner fissa il valore al limite del timer piuttosto che rifiutarlo.

Timeout di avvio della sessione

Se una sessione ha perso il suo slot durante un turno come /code-review, aggiorna il runner e il binario figlio alla v2.1.309 o successiva. Dalla v2.1.299 alla v2.1.308, il runner rilasciava una sessione, anche a metà turno, una volta trascorso il timeout di avvio senza un messaggio user o assistant. Con --startup-timeout-min <n>, il runner rilascia lo slot di una sessione quando il suo figlio non si è inizializzato entro <n> minuti dopo la clonazione. Durante un turno che inizia prima che il figlio si inizializzi, la sessione mantiene il suo slot finché non trascorrono <n> minuti senza alcuna riga sul canale di attività del figlio. Una volta che il figlio si inizializza, il runner azzera quel conteggio e il rilascio è governato da --release-idle-session-min. Per limitare una sessione il cui figlio è attivo ma bloccato, imposta --kill-session-after-min.

Elenchi di regole della modalità auto

--server-auto-mode-lists ti permette di decidere quali regole del classificatore della modalità auto provenienti dall’esterno del runner raggiungono le sessioni sui tuoi runner. Il control plane di Anthropic può inviare elenchi di regole con una sessione e chiedere al runner di applicarli. Alcune voci possono essere regole scritte da un amministratore della tua organizzazione. Gli elenchi sono environment, soft_deny e allow:

environment: una voce può far sì che il classificatore consenta di più così come di meno.
soft_deny: una voce blocca un’azione a meno che l’utente non l’abbia richiesta esplicitamente o non si applichi un’eccezione allow.
allow: le eccezioni alle voci soft_deny.

Il valore del flag sceglie quali elenchi applica il runner:

no-allow: il valore predefinito. Applica environment e soft_deny e trattiene allow. Una voce environment può comunque far sì che il classificatore consenta di più, quindi il valore predefinito non esclude ogni allentamento.
all: applica tutti e tre gli elenchi.
none: non ne applica nessuno. Scegli none per escludere ogni allentamento proveniente da questi elenchi. Elimina anche le restrizioni di soft_deny.

Nessuna impostazione del runner fa sì che il control plane chieda al runner di applicare gli elenchi. Quando non lo chiede, le sessioni non ricevono alcun elenco, qualunque cosa tu imposti. Per vedere cosa è successo, avvia il runner con --log-level debug. Per ogni sessione il runner registra quindi una riga contenente the server asked this runner to apply, oppure una contenente the server did not ask this runner to apply the auto mode lists it sends.

Flag CLI dell’orchestrator

Il sottocomando self-hosted-runner orchestrator, che genera runner on-demand, accetta --api-url, --environment-secret-file, --hooks-dir, --health-port e --log-level con gli stessi valori predefiniti del runner e, dove il flag del runner ne ha uno, la stessa variabile d’ambiente, tranne che --hooks-dir è obbligatorio e deve contenere un hook spawn-runner. Accetta anche i suoi flag:

Flag	Default	Description
`--hook-concurrency <n>`	`4`	Numero massimo di hook `spawn-runner` in esecuzione in parallelo. Limita anche quante richieste di spawn vengono rivendicate per polling. L’orchestrator controlla la presenza di nuove richieste di spawn solo dopo che ogni hook avviato è terminato, quindi un hook lento ritarda gli hook successivi di quell’orchestrator.
`--hook-timeout <sec>`	`60`	Termina l’albero dei processi dell’hook dopo questo numero di secondi. Il timeout più la sua grazia di 5 secondi deve rimanere al di sotto di `--expected-spawn-seconds`; l’orchestrator lo applica all’avvio.
`--expected-spawn-seconds <sec>`	`120`	Tempo p99 previsto tra il momento in cui l’orchestrator riceve una richiesta di spawn e quello in cui il runner si registra, inclusa qualsiasi attesa di capacità sulla tua piattaforma. Il server applica un intervallo da 10 a 3600. Inviato ad ogni polling come lease lato server: se nessun runner si registra prima che trascorra, la sessione viene ri-offerta con un ID ordine nuovo. Tutte le repliche devono condividere questo valore.
`--min-idle <n>`	`0`	Mantieni almeno N slot di sessione inattivi liberi generando proattivamente runner di standby. `0` disabilita il pre-riscaldamento. Abbina con il `--exit-if-unused-min` del runner in modo che i runner di standby in eccesso si riprendano.
`--debug-dir <path>`	unset	Scrivi il work order e lo stderr dell’hook di ogni richiesta di spawn su disco. Solo debug; non impostare mai in produzione.

Flag del connettore SCM

Il connettore SCM non è disponibile, quindi lascia i flag in questa sezione non impostati. Se imposti --scm-connector-host, la connessione non si apre e l’orchestrator continua a ritentare. I runner comunque si avviano mentre la coda delle sessioni si accumula. Il connettore è una connessione WebSocket permanente dall’orchestrator al piano di controllo di Anthropic. È progettato per consentire ai flussi pre-sessione ospitati, come il selettore di repository e il risolutore di ramo o ref, di raggiungere un host GitHub Enterprise Server che è instradabile solo dall’interno della tua rete. Vedi Requisiti di rete nella pagina GitHub Enterprise Server per sapere cosa richiedono questi flussi.

Flag	Default	Description
`--scm-connector-host <host[:port]>`	unset	Nome host di GitHub Enterprise Server a cui inoltrare le richieste. La porta predefinita è `443`.
`--scm-connector-id <n>`	required with `--scm-connector-host`	L’ID numerico della connessione GitHub Enterprise Server della tua organizzazione.
`--scm-connector-provider <slug>`	`ghe`	Segmento di percorso che identifica il provider, corrispondente a `^[a-z0-9-]{1,32}$`.
`--scm-connector-ca-file <path>`	unset	Bundle CA aggiuntivo, in formato PEM, per le connessioni TLS all’host GitHub Enterprise Server.
`--scm-connector-host-rewrite <from>=<to_host:to_port>`	unset	Solo per test end-to-end: reindirizza la connessione TCP mantenendo l’intestazione Host e TLS SNI come `--scm-connector-host`.

Ad ogni tentativo di connessione l’orchestrator invia il suo segreto d’ambiente esistente e ritenta automaticamente con backoff esponenziale, limitato a 30 secondi più jitter.

Impostazioni solo variabili d’ambiente

Queste impostazioni del runner vengono lette solo dall’ambiente e coprono il comportamento che la maggior parte delle distribuzioni lascia al valore predefinito:

Env var	Default	Description
`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`	`30000`	Quanto tempo il runner considera una sessione occupata dopo che un compito in background finisce mentre il turno di follow-up che legge il risultato non è ancora iniziato. Le righe `--drain-wait-sec` e `--release-idle-session-min` descrivono dove si applica la tenuta su drenaggio e rilascio inattivo, e Runner lifecycle descrive dove si applica al ritiro `--retire-at`. `0` o un valore inutilizzabile ricade al valore predefinito, quindi la tenuta non può essere disattivata. Richiede Claude Code v2.1.228 o successivo.
`SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`	`~/.claude`	Directory acquisita nello snapshot di avvio del runner e seminata nella `CLAUDE_CONFIG_DIR` di ogni sessione; le modifiche su disco si applicano dopo un riavvio del runner. L’impostazione della variabile sposta anche dove il runner legge `.claude.json` per il seeding MCP, quindi impostarla, incluso al suo valore predefinito, trasferisce quella ricerca; punta a una directory vuota per disabilitare completamente il seeding.
`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`	`900000`	Quanto tempo il runner attende dopo che una sessione raggiunge il suo limite `--kill-session-after-min`, affinché un turno in esecuzione finisca o il rilascio si completi, prima di terminare la sessione
`SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS`	`7000`	Limite massimo su quanto tempo il runner conta una sessione come occupata per il drenaggio `--drain-wait-sec` dopo che un turno finisce, mentre il processo della sessione segnala la fine del turno ad Anthropic. `0` o un valore inutilizzabile ricade al valore predefinito, quindi la tenuta non può essere disattivata. Richiede Claude Code v2.1.275 o successivo.
`SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS`	`30000`	Quanto tempo il runner attende che il sistema operativo consegni `SIGKILL` a un figlio bloccato in I/O non interrompibile prima di uscire lui stesso. Limitato inferiormente a `--post-session-hook-timeout-sec` più 15 secondi, e 30 in più quando `--push-outcome-on-release` è impostato, quindi il minimo effettivo è 75 secondi ai valori predefiniti.
`CLAUDE_RUNNER_FETCH_DEPTH`	`50`	Profondità di fetch git per cloni freschi. Imposta un numero intero positivo, o `full` o `0` per un fetch completo. Per un clone già presente nel workspace, consulta Riutilizzare un checkout pre-riscaldato.
`CLAUDE_RUNNER_FETCH_SERVER_PROGRESS_CAP_MS`	`600000`	Quanto tempo in millisecondi, per tentativo, un fetch git può attendere i primi dati mentre i numeri di avanzamento del server git continuano a crescere, come quando il server prepara il pack per un repository di grandi dimensioni. `0` o `off` disattiva l’attesa: un fetch di questo tipo viene quindi interrotto dopo due minuti senza dati. Qualsiasi altro numero intero viene limitato a un valore compreso tra `120000` e `1800000`, da 2 a 30 minuti. Richiede Claude Code v2.1.295 o successivo.
`CLAUDE_RUNNER_SKIP_GIT_VERIFY`	unset	Quando `1`, salta il controllo della presenza `.git` dopo l’esecuzione di un hook `checkout`. Imposta questo quando il tuo hook materializza una fonte non-git.
`FORCE_AUTOUPDATE_PLUGINS`	unset	Quando `1`, consenti ai marketplace dei plugin di auto-aggiornare anche se il binario è bloccato
`CLAUDE_CODE_DISABLE_ARTIFACT`	unset	Quando `1`, disabilita lo strumento Artifact nelle sessioni indipendentemente dall’impostazione di amministrazione dell’organizzazione, e elimina il requisito di uscita `*.frame.claudeusercontent.com`

Telemetria

I figli della sessione inviano telemetria operativa ad Anthropic a meno che non la disattivi. Nessun codice o contenuto del repository viene inviato. Imposta le variabili di telemetria sul processo del runner; il runner le ri-asserisce dopo aver applicato le variabili d’ambiente fornite dal server, quindi l’impostazione dell’operatore ha sempre la precedenza. Un controllo è specifico per gli ambienti self-hosted: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 acconsente alle metriche operative di Datadog, che sono disattivate per impostazione predefinita negli ambienti self-hosted. I controlli generali di telemetria di Claude Code, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING e CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, si applicano ai figli della sessione come documentato nel riferimento delle variabili d’ambiente. DISABLE_GROWTHBOOK è correlato ma diverso: impostare DISABLE_GROWTHBOOK=1 disabilita il recupero dei flag di funzionalità, e la telemetria rimane attiva a meno che DISABLE_TELEMETRY non sia anche impostato. CLAUDE_CODE_ENABLE_TELEMETRY non è correlato: abilita l’esportazione OpenTelemetry al tuo collettore, come descritto in Monitoring, e non controlla l’analittica di Anthropic.

Endpoint di salute

Il runner serve GET /healthz sulla porta di salute configurata. La risposta è 200 OK ogni volta che il processo è attivo, qualunque stato sia il ciclo di polling, quindi un probe HTTP su questo endpoint rileva solo un processo morto. Il corpo JSON descrive lo stato attuale:

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

Usa last_poll_age_ms come segnale di vivacità nei probe personalizzati; un valore che cresce senza limiti indica che il ciclo di polling è bloccato. Sia last_poll_at che last_poll_age_ms sono null fino al completamento del primo polling. Il /healthz dell’orchestrator, sulla sua porta di salute, restituisce sempre 200. Il corpo porta un campo connected che segnala se il polling più recente ha avuto successo, più i conteggi della coda di spawn per stato in queue_counts. Per capire perché connected è false, leggi il campo di primo livello last_error, che ogni polling riuscito reimposta a null. Basa readiness e alerting su connected piuttosto che sul codice di stato. Quando il connettore SCM è configurato, il corpo /healthz dell’orchestrator porta anche scm_connector_connected e un oggetto scm_connector con connected, last_connected_at, last_error, reconnects e requests_forwarded. Entrambi i campi sono null quando --scm-connector-host non è impostato.

Metriche Prometheus

Ogni runner serve metriche Prometheus su GET /metrics sulla stessa porta di /healthz. Serie chiave:

Series	Notes
`claude_code_self_hosted_runner_info{runner_id,version,client_label}`	Sempre `1`; utile per l’inventario della flotta e il rilevamento della deriva di versione
`claude_code_self_hosted_runner_capacity`	`--capacity` configurato
`claude_code_self_hosted_runner_active_sessions`	Sessioni attualmente in esecuzione
`claude_code_self_hosted_runner_locked_account{email}`	Presente una volta che il runner si è bloccato a un utente e un token di sessione che porta un’affermazione `act.email` è stato emesso. La serie è assente su un runner bloccato a un agente Claude Tag, i cui token di sessione non portano `act.email`. Il valore dell’etichetta è l’email dell’account; se il tuo archivio di metriche è ampiamente leggibile, elimina o hash l’etichetta al momento della raschiatura, ad esempio con Prometheus `metric_relabel_configs`.
`claude_code_self_hosted_runner_last_poll_age_seconds`	Secondi dall’ultimo polling riuscito. Avviso se superiore a 60.
`claude_code_self_hosted_runner_poll_errors_total{error_kind}`	Errori cumulativi di PollWork per tipo: `transport`, `timeout`, `5xx`, `429` o `4xx`. Tutte e cinque le serie sono presenti dall’avvio del processo; avviso su `rate(...[5m]) > 0`.
`claude_code_self_hosted_runner_sessions_started_total{client_platform}`	Processi figlio della sessione generati durante la vita del runner, una serie per origine della sessione come `web_claude_ai`, `ios`, `android`, `desktop_app` o `claude_code_cli`, o `unknown` quando il server non ne ha inviato uno. Le sessioni Slack portano `claude_in_slack` o `claude-in-slack` a seconda di quale integrazione Slack le ha create, quindi abbina entrambe con un selettore regex come `{client_platform=~"claude[-_]in[-_]slack"}`. Usa `sum()` per il totale della flotta.
`claude_code_self_hosted_runner_sessions_completed_total{client_platform}`	Sessioni che sono terminate correttamente, etichettate allo stesso modo. Più ampio di una semplice uscita pulita: vedi session lifecycle counter semantics per cosa conta.
`claude_code_self_hosted_runner_sessions_failed_total{client_platform}`	Sessioni che sono terminate in errore, etichettate allo stesso modo. Stessa avvertenza: vedi session lifecycle counter semantics.
`claude_code_self_hosted_runner_sessions_interrupted_total{client_platform}`	Sessioni che il runner ha terminato per un motivo operativo piuttosto che un risultato di sessione, etichettate allo stesso modo. Vedi session lifecycle counter semantics.
`claude_code_self_hosted_runner_initializing_sessions`	Sessioni attualmente nella fase di init, dall’assegnazione all’evento di init del figlio
`claude_code_self_hosted_runner_session_init_duration_seconds`	Istogramma delle durate di init della sessione
`claude_code_self_hosted_runner_session_init_errors_total`	Sessioni che hanno fallito prima di raggiungere init: un errore di hook di checkout, preparazione git, problema di token o un crash pre-init del figlio
`claude_code_self_hosted_runner_session_start_hook_errors_total`	Hook `SessionStart` che hanno segnalato un risultato di errore, uno per esecuzione di hook fallita
`claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform}`	Gauge per sessione di secondi dall’inattività della sessione. Utile per terminare le sessioni bloccate su un prompt di autorizzazione senza risposta.

L’orchestrator serve le sue serie su GET /metrics sulla stessa porta del suo /healthz:

Series	Notes
`claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname}`	Sempre `1`
`claude_code_self_hosted_orchestrator_connected`	`1` quando il polling più recente ha avuto successo; scende a `0` dopo qualsiasi polling fallito, qualunque sia il tipo di errore
`claude_code_self_hosted_orchestrator_last_poll_age_seconds`	Secondi dall’ultimo tentativo di polling, successo o errore, a differenza della metrica identicamente denominata del runner, che misura dall’ultimo successo; abbina con `connected` per catturare i polling falliti. Il ciclo di polling dell’orchestrator attende l’esecuzione dell’hook, quindi avviso sopra `--hook-timeout` più un margine, circa 90 secondi ai valori predefiniti, piuttosto che un flat 60.
`claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}`	Errori cumulativi di PollSpawnHints per tipo: `transport`, `timeout`, `5xx`, `429` o `4xx`. Tutte e cinque le serie sono presenti dall’avvio del processo; avviso su `rate(...[5m]) > 0`.
`claude_code_self_hosted_orchestrator_queue_pending_sessions`	Richieste di spawn rivendicabili in questo momento
`claude_code_self_hosted_orchestrator_queue_backing_off_sessions`	Richieste di spawn in backoff di retry dopo un errore di hook riprova
`claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`	Sessioni a cui è impedito lo spawn. Ognuna resta bloccata finché un utente non le invia un nuovo messaggio o un Owner non la riprova dalla scheda Activity dell’ambiente. Il conteggio può restare sopra zero anche dopo che hai risolto la causa. Avviso se superiore a zero.
`claude_code_self_hosted_orchestrator_pool_pending_sessions`	Sessioni totali in attesa di un runner per questo ambiente. Aggregato a livello di ambiente, identico su ogni istanza dell’orchestrator: usa `MAX` piuttosto che `SUM` tra le istanze.
`claude_code_self_hosted_orchestrator_pool_active_sessions`	Sessioni attualmente assegnate a un runner vivo in questo ambiente. Aggregato a livello di ambiente, identico su ogni istanza dell’orchestrator: usa `MAX` piuttosto che `SUM` tra le istanze.
`claude_code_self_hosted_orchestrator_spawn_hooks_total{result}`	Risultati cumulativi dell’hook `spawn-runner`: `ok`, `retryable`, `non_retryable`. Conta le invocazioni dell’hook dell’orchestrator, non i figli della sessione che i runner generano: non comparabili a `sessions_started_total`, poiché la capacità superiore a uno, i pool caldi e i runner generati di nuovo per la stessa sessione divergono i due.
`claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds`	Istogramma delle durate dell’hook
`claude_code_self_hosted_orchestrator_warm_hints_dispatched_total`	Richieste di spawn di standby inviate dall’avvio del processo
`claude_code_self_hosted_orchestrator_session_queue_wait_seconds`	Istogramma di secondi che ogni sessione ha atteso nella coda prima che l’orchestrator la rivendicasse per spawn, registrato dal timestamp di attesa della coda che il piano di controllo invia con la richiesta di spawn di ogni sessione. Usa per l’avviso del tempo di coda p50/p99. I spawn di pre-riscaldamento non vengono campionati.
`claude_code_self_hosted_orchestrator_clock_skew_seconds`	Skew dell’orologio locale meno server; diagnostico, presente una volta misurato
`claude_code_self_hosted_orchestrator_scm_connector_connected`	`1` quando il WebSocket del connettore SCM è aperto; `0` durante la composizione o il backoff. Assente quando `--scm-connector-host` non è impostato.
`claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total`	Richieste HTTP cumulative inoltrate all’host SCM configurato dall’avvio del processo. Assente quando `--scm-connector-host` non è impostato.

Per l’autoscaling, scegli la serie che corrisponde al tuo stile di scaling e gated prima che si nutra nello scaler:

Scaling della profondità della coda: alimenta claude_code_self_hosted_orchestrator_pool_pending_sessions nel tuo HPA o scaler KEDA, non queue_pending_sessions.
Scaling della capacità: scala sul rapporto tra active_sessions e capacity del runner.
Gate su connected: filtra la query con claude_code_self_hosted_orchestrator_connected == 1 per istanza, quindi il valore stantio di una replica disconnessa non si nutre nello scaler.

Durante un’interruzione completa del polling, ogni replica disconnessa, la query gated non restituisce dati. HPA mantiene il numero di replica attuale su una metrica mancante, ma lo scaler Prometheus di KEDA al suo ignoreNullValues: "true" predefinito legge il risultato vuoto come zero e scala in; imposta ignoreNullValues: "false" su ScaledObject, facoltativamente con un floor di replica fallback. Il seguente PodMonitor di Prometheus Operator copre entrambi i processi. Seleziona i pod per l’etichetta app.kubernetes.io/part-of: claude-code-self-hosted-runner e la porta denominata health che la ricetta Kubernetes imposta; regola gli spazi dei nomi per corrispondere alla tua distribuzione:

# Example Prometheus Operator PodMonitor for the Claude Code self-hosted
# runner + orchestrator. Adjust the namespace and label selectors to match
# your deployment. Both the runner and the orchestrator serve /metrics on
# their --health-port (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:
      # Matches the runner Deployment from the Kubernetes recipe, plus any
      # on-demand runner Jobs and orchestrator pods you label the same way
      # and give a named 'health' containerPort.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Regole di avviso di esempio

Queste regole di avviso di esempio sono un punto di partenza; sintonizza le soglie per la dimensione della tua flotta:

# Example Prometheus alert rules for the Claude Code self-hosted runner
# + orchestrator. Tune thresholds for your fleet size and SLOs.
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }} has not polled in >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runners are running mixed versions"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_init_errors_total[10m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Sessions are failing before init (checkout hook / git / token / pre-init crash)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "SessionStart hooks are failing"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} cannot reach the Anthropic control plane"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: max by (namespace) (claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions and on (instance) max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1) > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "Sessions blocked from spawning: {{ $value }}. Read each one's error in the Activity tab, fix the cause, then select Retry"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: PollSpawnHints failing ({{ $value | humanize }}/s over 5m)"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: >3 spawn-runner hook failures in 5m"

Avvisi su runner persi e sessioni in attesa

Su una flotta fissa, carica ClaudeRunnersBelowFloor. Con i runner on-demand, carica invece ClaudeOrchestratorSessionsWaiting e ClaudeOrchestratorQueueWaitHigh.

Avviso quando una flotta fissa perde runner

ClaudeRunnersBelowFloor si attiva quando per 10 minuti restano meno runner registrati e raccolti della soglia minima:

groups:
  # Fixed fleets only. With on-demand runners the count follows demand,
  # so ClaudeRunnersBelowFloor would fire whenever demand is low.
  - name: claude-code-self-hosted-fixed-fleet-capacity
    rules:
      - alert: ClaudeRunnersBelowFloor
        expr: (count(claude_code_self_hosted_runner_info{namespace="claude-runners"}) or vector(0)) < 2
        for: 10m
        labels: {severity: critical, namespace: claude-runners}
        annotations:
          summary: "Runners registered and scraped: {{ $value }}, below the floor. Check the runner workloads first, then the scrape targets if all are running."

Soglia minima: imposta il 2 in expr a circa metà del numero di repliche, arrotondato per eccesso. Con tre repliche mantieni 2, e l’avviso si attiva quando resta un solo runner o nessuno.
Namespace: sostituisci claude-runners nel matcher e in labels, e copia l’avviso per ogni ulteriore namespace. Se i tuoi target non hanno un’etichetta namespace, rimuovi il matcher e l’etichetta, altrimenti l’avviso legge 0 e si attiva.
ClaudeRunnerPollStale e ClaudeRunnerPollErrors: mantienili caricati dalle regole di avviso di esempio, perché ClaudeRunnersBelowFloor conta comunque un runner che non riesce a eseguire il polling

Avviso quando le sessioni attendono runner on-demand

ClaudeOrchestratorSessionsWaiting si attiva quando il numero di sessioni in attesa di un runner resta sopra 0 per 10 minuti. ClaudeOrchestratorQueueWaitHigh si attiva quando oltre l’1% delle attese in coda negli ultimi 10 minuti ha superato i 160 secondi, e questa condizione persiste per 5 minuti:

groups:
  # On-demand runners only. Needs no edit for the namespace.
  - name: claude-code-self-hosted-on-demand-capacity
    rules:
      - alert: ClaudeOrchestratorSessionsWaiting
        expr: |
          max by (namespace) (
            claude_code_self_hosted_orchestrator_pool_pending_sessions
            and on (instance)
            max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1
          ) > 0
        for: 10m
        labels: {severity: warning}
        annotations:
          summary: "Sessions waiting for a runner: {{ $value }}, above the threshold for 10 minutes. Check claude_code_self_hosted_orchestrator_spawn_hooks_total by result, then runner workloads that don't start."
      - alert: ClaudeOrchestratorQueueWaitHigh
        expr: |
          histogram_quantile(0.99, sum by (namespace, le) (
            rate(claude_code_self_hosted_orchestrator_session_queue_wait_seconds_bucket[10m])
          )) > 160
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Over 1% of queue waits in the last 10 minutes exceeded 160 seconds. Check whether ClaudeOrchestratorDisconnected is firing, then claude_code_self_hosted_orchestrator_spawn_hooks_total by result and claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds."

Soglia: se c’è sempre qualche sessione in attesa, alza il > 0 in ClaudeOrchestratorSessionsWaiting sopra il numero che vedi di solito
ClaudeOrchestratorDisconnected: mantienilo caricato dalle regole di avviso di esempio, perché ClaudeOrchestratorSessionsWaiting smette di attivarsi circa 2 minuti dopo che l’ultimo orchestrator nel namespace si disconnette

Passa attraverso le metriche del figlio della sessione

Ogni sessione viene eseguita nel suo processo figlio con le sue metriche OpenTelemetry; a --capacity superiore a uno, il runner riscrive come quelle metriche figlio vengono esposte. L’impostazione di OTEL_METRICS_EXPORTER=prometheus sull’host del runner e CLAUDE_CODE_ENABLE_TELEMETRY=1 nell’ambiente della sessione, ad esempio dal tuo script wrapper o dall’ambiente del runner stesso, che le sessioni ereditano, ri-espone gli strumenti di contatore e gauge di ogni figlio sull’endpoint /metrics del runner, insieme alle serie del runner. Il runner riscrive l’esportatore del figlio per eseguire il push su OTLP a un ricevitore solo loopback sulla porta di salute, etichetta ogni serie con etichette session_id e client_platform, e rimuove le serie di una sessione quando quella sessione termina. Gli istogrammi non passano, e una metrica figlio il cui nome entrerebbe in collisione con il prefisso del runner è eliminata. Al --capacity 1 predefinito, la riscrittura non si applica: il figlio della sessione lega il suo endpoint Prometheus sulla porta 9464 come al solito.

Unire le metriche di una sessione a quelle del runner

Per vedere quanto sono costate le sessioni inattive, esegui il join tra claude_code_self_hosted_runner_session_idle_seconds del runner e la metrica di costo di Claude Code su ccr_session_id. La metrica del runner non porta quell’etichetta, quindi assegnagliela con label_replace, come in questa query:

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

La query restituisce un risultato per ogni sessione inattiva da oltre dieci minuti: il costo in dollari USA che il suo processo Claude Code ha conteggiato finora. Per eseguire il join con un’altra metrica di Claude Code, sostituisci claude_code_cost_usage_total nella query. La query funziona con qualsiasi --capacity.

session_id: sulla porta 9464, quell’etichetta sulle metriche di Claude Code contiene il session.id proprio di Claude Code, che non corrisponde ad alcuna serie del runner. Un join su di essa non restituisce nulla, quindi esegui il join su ccr_session_id.
Le metriche di Claude Code non hanno ccr_session_id: verifica che OTEL_METRICS_INCLUDE_SESSION_ID non sia impostato su false

Semantica del contatore del ciclo di vita della sessione

I contatori sessions_started_total, sessions_completed_total, sessions_failed_total e sessions_interrupted_total classificano ogni sessione in base a come è terminata. Ogni figlio della sessione generato incrementa sessions_started_total al momento della generazione, e esattamente uno degli altri tre incrementa all’uscita, quindi sessions_started_total meno la somma degli altri tre è uguale al numero di figli della sessione attualmente in esecuzione.

completed: la sessione è terminata correttamente. Questo copre il figlio che esce da solo con codice 0, la sessione archiviata o eliminata mentre il figlio era ancora connesso, e il runner che restituisce lo slot in modo pulito: il rilascio della sessione al timeout di inattività, al tempo di ritiro o al limite --kill-session-after-min; un timeout di avvio; o un deassign lato server che il ciclo di polling ha notato prima che il figlio uscisse. Incrementa sessions_completed_total.
failed: il figlio è uscito da solo con un codice diverso da zero, sia un crash che un errore di configurazione dopo la generazione. Incrementa sessions_failed_total.
interrupted: il runner ha terminato il figlio per un motivo operativo che non è né un successo della sessione né un errore del runner, come un drenaggio, o terminando una sessione che era ancora sul runner quando la finestra di grazia SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS dopo il suo limite --kill-session-after-min è terminata. Un riavvio rolling di Kubernetes che invia SIGTERM è un esempio di drenaggio. Incrementa sessions_interrupted_total.

Prima della v2.1.260, il runner terminava ogni sessione che raggiungeva il suo limite --kill-session-after-min e la contava in sessions_interrupted_total. Il CLAUDE_RUNNER_EXIT_REASON dell’hook post-session classifica gli handoff puliti diversamente. L’hook li segnala come interrupted, perché il runner ha fermato il figlio: un rilascio, un timeout di avvio, un deassign del server e un’archiviazione o eliminazione che il polling ha notato per primo. Questi contatori registrano gli stessi eventi come completed, perché lo slot è stato restituito correttamente. Se riconcili le ricevute dell’hook direttamente contro sessions_completed_total, sottostimi i completamenti. Usa l’hook per le garanzie per sessione e i contatori per i tassi aggregati. Su un ambiente monouso, --capacity 1 con il --drain-grace-sec 0 predefinito, ogni processo del runner esce momenti dopo la fine della sua sessione. sessions_completed_total, sessions_failed_total e sessions_interrupted_total incrementano solo alla fine della sessione, subito prima di quell’uscita, quindi un raschiamento Prometheus ogni 15-60 secondi raramente cattura l’incremento prima che le serie del runner scompaiano; questi tre contatori di fine sessione sono i contatori terminali a cui il resto di questa sezione si riferisce. sessions_started_total incrementa alla generazione e rimane visibile per la vita della sessione, quindi si mostra in modo affidabile, ma su un ambiente monouso legge più vicino a “sessioni attualmente in esecuzione” che a un conteggio cumulativo. Usa la serie in questa tabella per l’obiettivo corrispondente invece dei contatori terminali:

Goal	Use
Throughput	`claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}`, un contatore sull’orchestrator di lunga durata che incrementa una volta per hook `spawn-runner` riuscito e rimane significativo sotto `rate()`. Conta le invocazioni dell’hook piuttosto che le sessioni, quindi il pre-riscaldamento e i spawn ripetuti per la stessa sessione divergono da conteggi di sessione.
Utilization	`sum(claude_code_self_hosted_runner_active_sessions)` contro `sum(claude_code_self_hosted_runner_capacity)`, entrambi i gauge validi ad ogni raschiamento indipendentemente dalla durata del runner
Backlog	`claude_code_self_hosted_orchestrator_pool_pending_sessions` per la profondità della coda, e `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`, avviso se superiore a zero
Failures	`claude_code_self_hosted_runner_sessions_failed_total`, best effort: i veri crash dopo la generazione incrementano, e `rate()` è significativo su runner che sopravvivono alle loro sessioni con `--drain-grace-sec` superiore a `0`. Un ambiente monouso ha lo stesso problema della finestra di raschiamento degli altri contatori terminali, quindi tratta qualsiasi valore diverso da zero che vedi come degno di indagine. I fallimenti prima della generazione, come un errore di hook di checkout, preparazione git o un problema di token, appaiono solo in `session_init_errors_total`.

Le righe orchestrator_* esistono solo su ambienti che eseguono l’orchestrator on-demand. Su una flotta fissa i cui runner sopravvivono alle loro sessioni, con --drain-grace-sec superiore a 0, usa sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) per il throughput; su una flotta monouso quella serie ha lo stesso problema della finestra di raschiamento dei contatori terminali, quindi affidati al conteggio delle sessioni in coda. Controlla il backlog nella scheda Activity dell’ambiente, nella pagina di amministrazione Cloud environments: i runner non esportano una serie di profondità della coda. Per la segnalazione dei risultati per sessione, usa l’hook post-session invece: si attiva alla fine di ogni sessione dove un processo figlio è stato generato, a parte la terminazione abrupte del runner come una preemption VM, per il contratto proprio dell’hook.

Prossimi passi

Self-hosted environments: l’ambiente, il runner e il modello di sessione; la guida rapida e Deploy to production contengono la configurazione e le operazioni
Customize sessions: script wrapper, hook del ciclo di vita e runner on-demand
Verify session identity: il token di sessione, le sue affermazioni e come verificarlo

Impostazioni

Permessi e sandboxing

Ambienti

Modello e risposte

Interfaccia

Riferimento per ambienti self-hosted

Flag CLI del runner

Timeout di avvio della sessione

Elenchi di regole della modalità auto

Flag CLI dell’orchestrator

Flag del connettore SCM

Impostazioni solo variabili d’ambiente

Telemetria

Endpoint di salute

Metriche Prometheus

Regole di avviso di esempio

Avvisi su runner persi e sessioni in attesa

Avviso quando una flotta fissa perde runner

Avviso quando le sessioni attendono runner on-demand

Passa attraverso le metriche del figlio della sessione

Unire le metriche di una sessione a quelle del runner

Semantica del contatore del ciclo di vita della sessione

Prossimi passi

​Flag CLI del runner

​Timeout di avvio della sessione

​Elenchi di regole della modalità auto

​Flag CLI dell’orchestrator

​Flag del connettore SCM

​Impostazioni solo variabili d’ambiente

​Telemetria

​Endpoint di salute

​Metriche Prometheus

​Regole di avviso di esempio

​Avvisi su runner persi e sessioni in attesa

​Avviso quando una flotta fissa perde runner

​Avviso quando le sessioni attendono runner on-demand

​Passa attraverso le metriche del figlio della sessione

​Unire le metriche di una sessione a quelle del runner

​Semantica del contatore del ciclo di vita della sessione

​Prossimi passi

Flag CLI del runner

Timeout di avvio della sessione

Elenchi di regole della modalità auto

Flag CLI dell’orchestrator

Flag del connettore SCM

Impostazioni solo variabili d’ambiente

Telemetria

Endpoint di salute

Metriche Prometheus

Regole di avviso di esempio

Avvisi su runner persi e sessioni in attesa

Avviso quando una flotta fissa perde runner

Avviso quando le sessioni attendono runner on-demand

Passa attraverso le metriche del figlio della sessione

Unire le metriche di una sessione a quelle del runner

Semantica del contatore del ciclo di vita della sessione

Prossimi passi