Referencia de entornos autohospedados

Los entornos autohospedados están en versión beta pública en planes Team y Enterprise; un Propietario los habilita activando Allow self-hosted environments en la página de administración Cloud environments. Esta página es la referencia de banderas y métricas; consulte el inicio rápido para la configuración y Implementar en producción para las recetas de flota.

Esta página es la referencia para los dos procesos que ejecuta en un entorno autohospedado: el ejecutor, que ejecuta sesiones en la nube de Claude Code en sus hosts, y el orquestador de escalado automático opcional, que inicia ejecutores a medida que las sesiones se ponen en cola. Cada uno tiene su propia tabla de banderas. Ambos se ejecutan en hosts Linux o macOS, que los valores predeterminados como /workspace y ~/.claude asumen. Ejecute claude self-hosted-runner --help para la lista autorizada en su versión instalada. Las series de métricas y algunos campos de API aún utilizan pool para lo que estas páginas llaman un entorno; ambos términos nombran lo mismo. El ID del entorno es el campo pool_id, con la forma ccpool_...: dondequiera que estas páginas muestren un identificador pool, nombra el entorno. Las banderas CLI y las variables de entorno lo escriben como environment, como --environment-secret-file; los nombres pool obsoletos aún funcionan, como describe la fila --environment-secret-file.

Flags CLI del runner

La mayoría de los flags tienen una variable de entorno correspondiente. Cuando ambos se establecen, el flag tiene precedencia. Los flags de duración toman minutos o segundos en la CLI, pero la variable de entorno emparejada siempre está en milisegundos, indicada por el sufijo _MS, y la columna Default muestra la unidad del flag: --exit-if-unused-min 10 es equivalente a SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, y un valor de Helm como SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" significa 15 milisegundos, no los 15 minutos predeterminados.

Flag	Env var	Default	Description
`--api-url <url>`	none	`https://api.anthropic.com`	URL base de API. Anule solo para pruebas.
`--base-dir <path>`	`SELF_HOSTED_RUNNER_BASE_DIR`	`/workspace`; ninguno en Windows	Directorio para checkouts de repositorio y directorios de trabajo por sesión. El runner necesita acceso de escritura a esta ruta o su padre. El runner crea el directorio al iniciar y sale con `cannot create or write to base directory` cuando no puede crearlo o escribir en él. Antes de v2.1.225, el runner creaba el directorio cuando la primera sesión comenzaba, por lo que una ruta inutilizable fallaba en sesiones en lugar de al iniciar. En Windows, que no es un host de runner compatible, no hay predeterminado: el runner sale al iniciar a menos que pase el flag o establezca la variable. Use el mismo valor en cada runner en un entorno. Consulte Keep the base directory and capacity identical across runners.
`--capacity <n>`	none	`1`	Máximo de sesiones concurrentes que este runner maneja. Todas las sesiones pertenecen al mismo owner bloqueado. Use el mismo valor en cada runner en un entorno; consulte Keep the base directory and capacity identical across runners.
`--client-label <label>`	`SELF_HOSTED_RUNNER_CLIENT_LABEL`	el hostname del host	Etiquete el runner que envía cuando se registra. El runner también lo reporta como la etiqueta `client_label` de `claude_code_self_hosted_runner_info`. Requiere Claude Code v2.1.248 o posterior.
`--configure-git`	`SELF_HOSTED_RUNNER_CONFIGURE_GIT=1`	off	Al iniciar, escriba la identidad global de git, habilite la firma de commits de Anthropic, active la negociación de push de git e instale hooks de commit que agreguen un tráiler `Co-authored-by:`. La negociación de push requiere Claude Code v2.1.257 o posterior. Consulte Configure git.
`--confine-repo-settings <mode>`	`SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS`	`warn`	Establece el modo del guard que marca una sesión cuando la configuración comprometida de un repositorio intenta otorgar acceso de escritura o lectura fuera del workspace de esa sesión, establecer variables de entorno o anular la postura de sandbox o hooks del operador, como `sandbox.enabled: false` o `disableAllHooks`. El `warn` predeterminado registra la violación e inicia la sesión de todas formas, `enforce` rechaza la sesión, y `off` desactiva el escaneo. Consulte Harden your deployment.
`--debug-token-dir <path>`	`SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR`	unset	Escriba tokens en vivo en disco para inspección. Solo depuración; no use en producción.
`--defer-shutdown-max-min <n>`	`SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS`	`0`	En el primer `SIGTERM` o `SIGINT`, continúe sirviendo las sesiones ya adjuntas en lugar de drenarlas, luego libere lo que aún esté adjunto N minutos después y salga. Aumente el timeout de parada de su host antes de establecer esto. Consulte Defer the drain past the first signal. `0` desactiva. Requiere Claude Code v2.1.238 o posterior.
`--drain-grace-sec <n>`	`SELF_HOSTED_RUNNER_DRAIN_GRACE_MS`	`0`	Hasta que el runner reciba una señal de apagado o alcance su tiempo de retiro, controla cuándo sale el runner después de que sus sesiones activas terminen: `0` sale inmediatamente sin sondear más, y un valor positivo mantiene el runner vivo y re-sondea la cola del owner bloqueado durante esos muchos segundos primero, al costo del aislamiento de contenedor por sesión descrito en la sección de endurecimiento. Después de una primera señal que difirió con `--defer-shutdown-max-min`, el runner sale tan pronto como no tenga sesiones, sin importar lo que establezca aquí.
`--drain-marker-file <path>`	`SELF_HOSTED_RUNNER_DRAIN_MARKER_FILE`	unset	Archivo marcador que su host escribe para anunciar un drenaje elegante antes de enviar `SIGTERM`. Cuando el archivo existe cuando comienza el drenaje, el runner reporta su salida a Anthropic como un drenaje de host en lugar de una señal de apagado simple. El drenaje en sí, incluida la espera de `--drain-wait-sec`, se ejecuta igual que sin el flag. Nombre una ruta en un sistema de archivos local que las sesiones no puedan escribir. Requiere Claude Code v2.1.271 o posterior.
`--drain-wait-sec <n>`	`SELF_HOSTED_RUNNER_DRAIN_WAIT_MS`	`0`	Una vez que comienza el drenaje, lo cual ocurre con `SIGTERM` a menos que establezcas `--defer-shutdown-max-min`, espera hasta N segundos a que terminen el turno en curso de cada sesión y sus tareas en segundo plano antes de terminar el proceso hijo. Durante esta espera, el runner cuenta una tarea en segundo plano que acaba de terminar como si aún estuviera en ejecución hasta que comienza el turno de seguimiento que lee su resultado, durante como máximo la ventana `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`. Aumenta también tu tiempo de espera de detención.
`--environment-secret-file <path>`	`SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET`	required	Ruta a un archivo que contiene el secreto del entorno, o, para runners generados por el orquestador, el JWT de orden de trabajo de un solo uso. `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` lleva el valor secreto directamente, no una ruta de archivo. El flag más antiguo `--pool-secret-file` y la variable `SELF_HOSTED_RUNNER_POOL_SECRET` aún funcionan e imprimen un aviso de deprecación a stderr; las compilaciones de runner del programa de vista previa más antiguas que 2.1.216 solo reconocen esos nombres más antiguos.
`--exec-path <path>`	`SELF_HOSTED_RUNNER_EXEC_PATH`	own binary	Binario o script de envoltura para generar para cada sesión. Consulte Wrapper scripts.
`--exit-if-unused-min <n>`	`SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS`	`0`	Salga después de N minutos de sondeo sin trabajo nunca asignado, para escala hacia abajo del autoscaler. `0` desactiva.
`--git-host-rewrite <from>=<to>`	none	unset	Reescriba las URLs de origen `https://<from>/...` a `https://<to>/...` antes de clonar, para DNS de horizonte dividido. Repetible; solo flag.
`--git-ssh-rewrite <host>`	none	unset	Reescriba las URLs de origen `https://<host>/...` a `git@<host>:...` antes de clonar, para hosts git solo SSH. Repetible; solo flag.
`--health-port <port>`	`SELF_HOSTED_RUNNER_HEALTH_PORT`	`8080`	Puerto para el listener `/healthz` y `/metrics`. Establezca `0` para desactivar.
`--hooks-dir <path>`	`SELF_HOSTED_RUNNER_HOOKS_DIR`	unset	Directorio de scripts de hook de ciclo de vida. Consulte Lifecycle hooks.
`--host-config-snapshot <mode>`	`SELF_HOSTED_RUNNER_HOST_CONFIG_SNAPSHOT`	`disk`	Dónde el runner mantiene la instantánea de inicio del directorio de configuración del host que siembra cada sesión desde. `disk` copia la instantánea en un directorio propiedad del runner bajo `--base-dir` y, en cada inicio de sesión, verifica cada archivo contra un resumen en memoria. Si un archivo en la copia ha sido modificado, la sesión falla y el runner rechaza sesiones hasta que lo reinicie. `memory` mantiene toda la instantánea en el heap, limitada a 64 MiB; sobre el límite, las sesiones comienzan sin configuración de host y muestran un aviso diciendo así. Cuando el runner no puede escribir la instantánea de disco, registra el fallo y usa `memory` para esa ejecución. Requiere Claude Code v2.1.271 o posterior.
`--kill-session-after-min <n>`	`SELF_HOSTED_RUNNER_MAX_LIFETIME_MS`	`0`	Limite una sesión a N minutos de reloj de pared, como límite de seguridad para sesiones atascadas. En v2.1.260 o posterior, el runner libera una sesión que alcanza el límite para que pueda reanudarse en el siguiente mensaje de su usuario, y la termina solo si aún está en el runner cuando termina la ventana de gracia `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`. Antes de v2.1.260, el runner terminaba la sesión en el límite. Consulte Some sessions don’t count as idle para los detalles y cómo elegir un valor. `0` desactiva.
`--lock-to-account <id>`	`SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT`	unset	Pre-bloquee el runner a una cuenta específica al iniciar en lugar de bloquear en la primera sesión. Acepta una dirección de correo electrónico o un ID `user_...` en la organización del entorno. Un runner pre-bloqueado nunca recoge sesiones del canal Claude Tag, que no tienen cuenta.
`--log-file <path>`	`SELF_HOSTED_RUNNER_LOG_FILE`	unset	Espeje los logs del runner a un archivo además de stdout y stderr, creado con permisos `0600`. Requerido para que `self-hosted-runner doctor` rastree logs localmente.
`--log-level <level>`	none	`info`	`info` o `debug`
`--post-session-hook-timeout-sec <n>`	`SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS`	`60`	Presupuesto para el hook `post-session` en cada final de sesión, incluido el apagado del runner
`--proxy-authorization-command <command>`	`SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND`	unset	Comando de shell que el runner ejecuta para cada conexión a su proxy de salida, usando su stdout recortado como el valor del encabezado `Proxy-Authorization`. Requiere `HTTPS_PROXY` o `HTTP_PROXY`, y no se puede combinar con `--proxy-authorization-file`. Consulte Authenticate to an egress proxy. Requiere Claude Code v2.1.238 o posterior.
`--proxy-authorization-file <path>`	`SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE`	unset	Archivo que el runner lee para cada conexión a su proxy de salida, usando su contenido recortado como el valor del encabezado `Proxy-Authorization`. Use este flag para un token que otro proceso rota en su lugar. Lleva los mismos requisitos que `--proxy-authorization-command`, y no se puede combinar con él. Consulte Authenticate to an egress proxy. Requiere Claude Code v2.1.238 o posterior.
`--push-outcome-on-release`	`SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE`	off	En un final de sesión iniciado por el runner como un drenaje o liberación por inactividad, empuje las ramas de resultado rastreadas a `origin` antes de eliminar el workspace, para que los commits en vuelo sobrevivan a un reinicio. Mejor esfuerzo; agrega 30 segundos al presupuesto de apagado, y requiere git 2.29 o más nuevo para reanudar desde la rama empujada. Restrinja el acceso de push a refs `claude/*` antes de habilitar; consulte Resumed sessions lose unpushed work. Los repositorios verificados a través de un hook de ciclo de vida `checkout` no se empujan; tome una instantánea de esos desde el hook `post-session` en su lugar.
`--release-idle-session-min <n>`	`SELF_HOSTED_RUNNER_SESSION_IDLE_MS`	`0`	Libere un slot de sesión después de N minutos de inactividad una vez que un turno termina o la sesión espera la acción del usuario. Una sesión que aún está a mitad de turno, incluida una que sostiene una tarea de fondo que nunca termina o una aprobación solicitada desde dentro de una llamada de herramienta en ejecución, no cuenta como inactiva; empareje con `--kill-session-after-min` como el tope duro. Después de que la tarea de fondo de una sesión termina, el runner considera la sesión ocupada hasta que comienza el turno de seguimiento que lee el resultado, durante como máximo la ventana `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`. Hasta que el runner reciba una señal de apagado o alcance su tiempo de retiro, una liberación que deja el runner sin sesiones activas inicia la misma ruta de salida que un drenaje normal, gobernado por `--drain-grace-sec`. Después de una primera señal que difirió con `--defer-shutdown-max-min`, el runner sale tan pronto como una liberación lo deja sin sesiones. `0` desactiva.
`--remove-session-state [bool]`	`SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE`	off	Elimine los directorios por sesión de una sesión bajo `<base-dir>/_sessions/` cuando la sesión termina en este runner, sin importar el resultado. Reuse a pre-warmed checkout describe lo que contienen y quién puede leerlos cuando permanecen. La eliminación es mejor esfuerzo: los directorios por sesión permanecen en su lugar cuando el runner es asesinado o alcanza su plazo de drenaje antes de que se ejecute la limpieza. Con el flag activado, el log de depuración de una sesión fallida o interrumpida no se mantiene en disco. Requiere Claude Code v2.1.268 o posterior.
`--retire-at <epoch-seconds>`	`SELF_HOSTED_RUNNER_RETIRE_AT`	unset	Retire el runner en una marca de tiempo Unix absoluta en segundos, para infraestructura que mata el runner en un tiempo conocido; Runner lifecycle describe la secuencia de liberación y cómo dimensionar el margen. Los valores antes de 2001 o después del año 5138 son rechazados por el flag e ignorados por la variable de entorno.
`--server-auto-mode-lists <mode>`	`SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS`	`no-allow`	Cuáles de las listas de reglas del clasificador del modo automático que el plano de control envía con una sesión pueden llegar a esa sesión: `all`, `no-allow` o `none`. Consulta Listas de reglas del modo automático para ver qué aplica cada valor. Un valor no válido detiene el runner al iniciar. Requiere Claude Code v2.1.295 o posterior.
`--session-stop-grace-sec <n>`	`SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS`	`5`	Cuánto tiempo esperar a que el proceso de Claude salga limpiamente después de que una sesión termina, antes de matarlo por la fuerza. Aumente el valor si los hooks `SessionEnd` propios del hijo necesitan más tiempo.
`--startup-timeout-min <n>`	`SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS`	`15`	Cuánto tiempo esperar a un proceso hijo que no se ha inicializado antes de liberar el slot de la sesión. Consulta Tiempo de espera de inicio de la sesión para saber dónde empieza el conteo y qué sesiones deja en ejecución. `0` desactiva el tiempo de espera.
`--trust-workspace [bool]`	`SELF_HOSTED_RUNNER_TRUST_WORKSPACE`	on	Semilla de confianza persistida para las rutas del repositorio de cada sesión para que `permissions.allow` y `additionalDirectories` comprometidos en el repositorio sean honrados. Establezca `false` para descartar concesiones de permisos comprometidas en el repositorio y configure reglas de permiso en la `settings.json` de la configuración del host en su lugar; la configuración `sandbox.*` comprometida en el repositorio aún se aplica de cualquier forma, que es por qué el guard de configuración de repositorio los escanea independientemente de este flag.
`--use-anthropic-git-proxy`	`CLAUDE_RUNNER_USE_GIT_PROXY=1`	off	Clona los repositorios de github.com a través del proxy de git de Anthropic en lugar de la autenticación de git administrada por el cliente. Requiere `--capacity 1` y git 2.32 o posterior; de lo contrario, el runner se niega a iniciar. Reemplaza los flags de reescritura.

La mayoría de los flags de duración tienen un máximo, elegido para mantener cada timeout dentro del techo del temporizador de 32 bits del runtime de aproximadamente 24,85 días. Los flags --*-min se limitan a 10080 minutos, 7 días; --drain-grace-sec a 604800 segundos, también 7 días; y --drain-wait-sec a 86400 segundos, 24 horas. --session-stop-grace-sec y --post-session-hook-timeout-sec no tienen límite. Exceder un límite se comporta diferente por superficie:

Flag: el inicio falla con un error.
Variable de entorno: el runner fija el valor al techo del temporizador en lugar de rechazarlo.

Tiempo de espera de inicio de la sesión

Si una sesión perdió su slot durante un turno como /code-review, actualiza el runner y el binario hijo a v2.1.309 o posterior. Desde v2.1.299 hasta v2.1.308, el runner liberaba una sesión, incluso a mitad de turno, una vez que pasaba el tiempo de espera de inicio sin un mensaje user o assistant. Con --startup-timeout-min <n>, el runner libera el slot de una sesión cuando su proceso hijo no se ha inicializado dentro de los <n> minutos posteriores a la clonación. Durante un turno que comienza antes de que el proceso hijo se inicialice, la sesión conserva su slot hasta que pasan <n> minutos sin ninguna línea en el canal de actividad del proceso hijo. Una vez que el proceso hijo se inicializa, el runner descarta ese conteo y --release-idle-session-min rige la liberación. Para limitar una sesión cuyo proceso hijo está vivo pero atascado, establece --kill-session-after-min.

Listas de reglas del modo automático

--server-auto-mode-lists te permite decidir qué reglas del clasificador del modo automático procedentes de fuera del runner llegan a las sesiones de tus runners. El plano de control de Anthropic puede enviar listas de reglas con una sesión y pedir al runner que las aplique. Algunas entradas pueden ser reglas que escribió un administrador de tu organización. Las listas son environment, soft_deny y allow:

environment: una entrada puede hacer que el clasificador permita más, así como menos.
soft_deny: una entrada bloquea una acción a menos que el usuario la haya pedido explícitamente o se aplique una excepción de allow.
allow: las excepciones a las entradas de soft_deny.

El valor del flag elige qué listas aplica el runner:

no-allow: el valor predeterminado. Aplica environment y soft_deny y retiene allow. Una entrada de environment todavía puede hacer que el clasificador permita más, así que el valor predeterminado no descarta toda relajación.
all: aplica las tres listas.
none: no aplica ninguna de ellas. Elige none para descartar toda relajación proveniente de estas listas. También elimina las restricciones de soft_deny.

Ningún ajuste del runner hace que el plano de control le pida al runner que aplique las listas. Cuando no se lo pide, las sesiones no reciben ninguna lista, sin importar lo que establezcas. Para ver qué ocurrió, inicia el runner con --log-level debug. Para cada sesión, el runner registra entonces una línea que contiene the server asked this runner to apply, o una que contiene the server did not ask this runner to apply the auto mode lists it sends.

Banderas de CLI del Orchestrator

El subcomando self-hosted-runner orchestrator, que genera runners bajo demanda, acepta --api-url, --environment-secret-file, --hooks-dir, --health-port y --log-level con los mismos valores predeterminados que el runner y, donde la bandera del runner tiene uno, la misma variable de entorno, excepto que --hooks-dir es obligatorio y debe contener un hook spawn-runner. También toma sus propias banderas:

Bandera	Predeterminado	Descripción
`--hook-concurrency <n>`	`4`	Máximo de hooks `spawn-runner` ejecutándose en paralelo. También limita cuántas solicitudes de generación se reclaman por sondeo. El orchestrator busca nuevas solicitudes de generación solo después de que haya terminado cada hook que inició, por lo que un hook lento retrasa los siguientes hooks de ese orchestrator.
`--hook-timeout <sec>`	`60`	Terminar el árbol de procesos del hook después de este número de segundos. El tiempo de espera más su período de gracia de 5 segundos debe mantenerse por debajo de `--expected-spawn-seconds`; el orchestrator lo aplica al inicio.
`--expected-spawn-seconds <sec>`	`120`	Tiempo p99 esperado desde que el orchestrator recibe una solicitud de generación hasta que el runner se registra, incluida cualquier espera de capacidad en tu plataforma. El servidor aplica un rango de 10 a 3600. Se envía en cada sondeo como el arrendamiento del lado del servidor: si ningún runner se registra antes de que transcurra, la sesión se vuelve a ofrecer con un ID de orden nuevo. Todas las réplicas deben compartir este valor.
`--min-idle <n>`	`0`	Mantener al menos N espacios de sesión inactivos libres generando runners en espera de forma proactiva. `0` desactiva el precalentamiento. Emparejar con `--exit-if-unused-min` del runner para que los runners en espera excedentes se reclamen a sí mismos.
`--debug-dir <path>`	sin establecer	Escribir la orden de trabajo de cada solicitud de generación y stderr del hook en el disco. Solo para depuración; nunca establecer en producción.

Banderas del conector SCM

El conector SCM no está disponible, así que deje las banderas en esta sección sin establecer. Si establece --scm-connector-host, la conexión no se abre y el orchestrator sigue reintentando. Los runners aún se inician a medida que las sesiones se encolan. El conector es una conexión WebSocket permanente desde el orchestrator al plano de control de Anthropic. Está diseñado para permitir que los flujos previos a la sesión alojados, como el selector de repositorio y el resolutor de rama o ref, lleguen a un host de GitHub Enterprise Server que solo es enrutable desde dentro de su red. Consulte Requisitos de red en la página de GitHub Enterprise Server para ver lo que esos flujos necesitan.

Bandera	Predeterminado	Descripción
`--scm-connector-host <host[:port]>`	sin establecer	Nombre de host de GitHub Enterprise Server al que reenviar solicitudes. El puerto predeterminado es `443`.
`--scm-connector-id <n>`	requerido con `--scm-connector-host`	El ID numérico de la conexión de GitHub Enterprise Server de su organización.
`--scm-connector-provider <slug>`	`ghe`	Segmento de ruta que identifica el proveedor, coincidiendo con `^[a-z0-9-]{1,32}$`.
`--scm-connector-ca-file <path>`	sin establecer	Paquete de CA adicional, en formato PEM, para conexiones TLS al host de GitHub Enterprise Server.
`--scm-connector-host-rewrite <from>=<to_host:to_port>`	sin establecer	Solo para pruebas de extremo a extremo: redirige la conexión TCP mientras mantiene el encabezado Host y TLS SNI como `--scm-connector-host`.

En cada intento de conexión, el orchestrator envía su secreto de entorno existente, y reintenta automáticamente con retroceso exponencial, limitado a 30 segundos más jitter.

Configuración solo de variables de entorno

Estas configuraciones del runner se leen solo del entorno y cubren comportamiento que la mayoría de los despliegues dejan en el predeterminado:

Env var	Default	Description
`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`	`30000`	Cuánto tiempo el runner considera una sesión ocupada después de que una tarea de fondo termina mientras el turno de seguimiento que lee el resultado no ha comenzado. Las filas `--drain-wait-sec` y `--release-idle-session-min` describen dónde se aplica la retención en drenaje y liberación por inactividad, y Runner lifecycle describe dónde se aplica en retiro `--retire-at`. `0` o un valor inutilizable vuelve al predeterminado, por lo que la retención no se puede desactivar. Requiere Claude Code v2.1.228 o posterior.
`SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`	`~/.claude`	Directorio capturado en la instantánea de inicio del runner y sembrado en el `CLAUDE_CONFIG_DIR` de cada sesión; los cambios en disco se aplican después de un reinicio del runner. Establecer la variable también mueve dónde el runner lee `.claude.json` para siembra de MCP, por lo que establecerlo, incluso a su propio predeterminado, reubica esa búsqueda; apunte a un directorio vacío para desactivar completamente la siembra.
`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`	`900000`	Cuánto tiempo el runner espera después de que una sesión alcanza su límite `--kill-session-after-min`, para que un turno en ejecución termine o se complete la liberación, antes de terminar la sesión
`SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS`	`7000`	Límite en cuánto tiempo el runner cuenta una sesión como ocupada para el drenaje `--drain-wait-sec` después de que un turno termina, mientras el proceso de la sesión reporta el final del turno a Anthropic. `0` o un valor inutilizable vuelve al predeterminado, por lo que la retención no se puede desactivar. Requiere Claude Code v2.1.275 o posterior.
`SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS`	`30000`	Cuánto tiempo el runner espera a que el SO entregue `SIGKILL` a un hijo atascado en E/S no interrumpible antes de salir él mismo. Tiene como valor mínimo `--post-session-hook-timeout-sec` más 15 segundos, y 30 más cuando `--push-outcome-on-release` está establecido, por lo que el mínimo efectivo es 75 segundos en valores predeterminados.
`CLAUDE_RUNNER_FETCH_DEPTH`	`50`	Profundidad de búsqueda de git para clones frescos. Establece un entero positivo, o `full` o `0` para una búsqueda completa. Para un clon que ya está en el espacio de trabajo, consulta Reutilizar un checkout precalentado.
`CLAUDE_RUNNER_FETCH_SERVER_PROGRESS_CAP_MS`	`600000`	Cuánto tiempo en milisegundos, por intento, una búsqueda de git puede esperar sus primeros datos mientras los números de progreso del propio servidor git siguen aumentando, como cuando el servidor prepara el pack para un repositorio grande. `0` u `off` desactiva la espera: esa búsqueda se corta entonces después de dos minutos sin datos. Cualquier otro número entero se limita a un valor entre `120000` y `1800000`, de 2 a 30 minutos. Requiere Claude Code v2.1.295 o posterior.
`CLAUDE_RUNNER_SKIP_GIT_VERIFY`	unset	Cuando es `1`, omita la verificación de presencia `.git` después de que se ejecute un hook `checkout`. Establezca esto cuando su hook materializa una fuente que no es git.
`FORCE_AUTOUPDATE_PLUGINS`	unset	Cuando es `1`, permita que los mercados de plugins se actualicen automáticamente aunque el binario esté fijado
`CLAUDE_CODE_DISABLE_ARTIFACT`	unset	Cuando es `1`, desactive la herramienta Artifact en sesiones independientemente de la configuración de administración de la organización, y elimine el requisito de salida `*.frame.claudeusercontent.com`

Telemetría

Los hijos de sesión envían telemetría operacional a Anthropic a menos que la desactive. No se envía código ni contenido del repositorio. Establezca variables de telemetría en el proceso del runner; el runner las reafirma después de aplicar variables de entorno proporcionadas por el servidor, por lo que la configuración del operador siempre tiene precedencia. Un control es específico para entornos autohospedados: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 se suscribe a métricas operacionales de Datadog, que están desactivadas de forma predeterminada en entornos autohospedados. Los controles generales de telemetría de Claude Code, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING, y CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, se aplican a hijos de sesión como se documenta en la referencia de variables de entorno. DISABLE_GROWTHBOOK está relacionado pero es diferente: establecer DISABLE_GROWTHBOOK=1 desactiva la búsqueda de banderas de características, y la telemetría permanece activada a menos que DISABLE_TELEMETRY también esté establecido. CLAUDE_CODE_ENABLE_TELEMETRY no está relacionado: habilita la exportación de OpenTelemetry a su propio recopilador, como se describe en Monitoring, y no controla la analítica de Anthropic.

Punto final de salud

El runner sirve GET /healthz en el puerto de salud configurado. La respuesta es 200 OK siempre que el proceso esté vivo, sea cual sea el estado del bucle de sondeo, por lo que un sondeo HTTP en este punto final detecta solo un proceso muerto. El cuerpo JSON describe el estado actual:

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

Use last_poll_age_ms como una señal de vivacidad en sondeos personalizados; un valor que crece sin límites indica que el bucle de sondeo está atascado. Tanto last_poll_at como last_poll_age_ms son null hasta que se completa el primer sondeo. El /healthz propio del orquestador, en su puerto de salud, siempre devuelve 200. El cuerpo lleva un campo connected que reporta si el sondeo más reciente tuvo éxito, más conteos de cola de generación por estado en queue_counts. Para ver por qué connected es false, lee el campo de nivel superior last_error, que cada sondeo exitoso restablece a null. Basa la preparación y las alertas en connected en lugar del código de estado. Cuando el conector SCM está configurado, el cuerpo /healthz del orquestador también lleva scm_connector_connected y un objeto scm_connector con connected, last_connected_at, last_error, reconnects, y requests_forwarded. Ambos campos son null cuando --scm-connector-host no está establecido.

Métricas de Prometheus

Cada runner sirve métricas de Prometheus en GET /metrics en el mismo puerto que /healthz. Series clave:

Series	Notes
`claude_code_self_hosted_runner_info{runner_id,version,client_label}`	Siempre `1`; útil para inventario de flota y detección de desviación de versión
`claude_code_self_hosted_runner_capacity`	`--capacity` configurado
`claude_code_self_hosted_runner_active_sessions`	Sesiones actualmente en ejecución
`claude_code_self_hosted_runner_locked_account{email}`	Presente una vez que el runner se ha bloqueado a un usuario y se ha emitido un token de sesión que lleva una reclamación `act.email`. La serie está ausente en un runner bloqueado a un agente de Claude Tag, cuyos tokens de sesión no llevan `act.email`. El valor de la etiqueta es el correo electrónico de la cuenta; si su almacén de métricas es ampliamente legible, suelte o hash la etiqueta en el tiempo de raspado, por ejemplo con `metric_relabel_configs` de Prometheus.
`claude_code_self_hosted_runner_last_poll_age_seconds`	Segundos desde el último sondeo exitoso. Alerte si es superior a 60.
`claude_code_self_hosted_runner_poll_errors_total{error_kind}`	Fallos acumulativos de PollWork por tipo: `transport`, `timeout`, `5xx`, `429`, o `4xx`. Las cinco series están presentes desde el inicio del proceso; alerte en `rate(...[5m]) > 0`.
`claude_code_self_hosted_runner_sessions_started_total{client_platform}`	Procesos hijo de sesión generados durante la vida útil del runner, una serie por origen de sesión como `web_claude_ai`, `ios`, `android`, `desktop_app`, o `claude_code_cli`, o `unknown` cuando el servidor no envió uno. Las sesiones de Slack llevan `claude_in_slack` o `claude-in-slack` dependiendo de qué integración de Slack las creó, así que coincida ambas con un selector de regex como `{client_platform=~"claude[-_]in[-_]slack"}`. Use `sum()` para el total de la flota.
`claude_code_self_hosted_runner_sessions_completed_total{client_platform}`	Sesiones que terminaron limpiamente, etiquetadas de la misma forma. Más amplio que una salida limpia simple: consulte semántica del contador del ciclo de vida de la sesión para lo que cuenta.
`claude_code_self_hosted_runner_sessions_failed_total{client_platform}`	Sesiones que terminaron en fallo, etiquetadas de la misma forma. Misma advertencia: consulte semántica del contador del ciclo de vida de la sesión.
`claude_code_self_hosted_runner_sessions_interrupted_total{client_platform}`	Sesiones que el runner terminó por una razón operacional en lugar de un resultado de sesión, etiquetadas de la misma forma. Consulte semántica del contador del ciclo de vida de la sesión.
`claude_code_self_hosted_runner_initializing_sessions`	Sesiones actualmente en la fase de inicialización, desde la asignación hasta el evento de inicialización del hijo
`claude_code_self_hosted_runner_session_init_duration_seconds`	Histograma de duraciones de inicialización de sesión
`claude_code_self_hosted_runner_session_init_errors_total`	Sesiones que fallaron antes de alcanzar la inicialización: una falla de hook de checkout, preparación de git, problema de token, o un bloqueo previo a la inicialización del hijo
`claude_code_self_hosted_runner_session_start_hook_errors_total`	Hooks `SessionStart` que reportaron un resultado de error, uno por ejecución de hook fallida
`claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform}`	Indicador por sesión de segundos desde que la sesión se volvió inactiva. Útil para terminar sesiones atascadas en un aviso de permiso sin respuesta.

El orquestador sirve sus propias series en GET /metrics en el mismo puerto que su /healthz:

Series	Notes
`claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname}`	Siempre `1`
`claude_code_self_hosted_orchestrator_connected`	`1` cuando el sondeo más reciente tuvo éxito; cae a `0` después de cualquier sondeo fallido, sea cual sea el tipo de fallo
`claude_code_self_hosted_orchestrator_last_poll_age_seconds`	Segundos desde el último intento de sondeo, éxito o fallo, a diferencia de la métrica con el mismo nombre del runner, que mide desde el último éxito; empareje con `connected` para detectar sondeos fallidos. El bucle de sondeo del orquestador espera en la ejecución del hook, así que alerte por encima de `--hook-timeout` más un margen, alrededor de 90 segundos en valores predeterminados, en lugar de un 60 plano.
`claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}`	Fallos acumulativos de PollSpawnHints por tipo: `transport`, `timeout`, `5xx`, `429`, o `4xx`. Las cinco series están presentes desde el inicio del proceso; alerte en `rate(...[5m]) > 0`.
`claude_code_self_hosted_orchestrator_queue_pending_sessions`	Solicitudes de generación reclamables ahora mismo
`claude_code_self_hosted_orchestrator_queue_backing_off_sessions`	Solicitudes de generación en retroceso de reintento después de una falla de hook reintentable
`claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`	Sesiones bloqueadas para generarse. Cada una permanece bloqueada hasta que un usuario le envía un nuevo mensaje o un Owner la reintenta desde la pestaña Activity del entorno. El recuento puede permanecer por encima de cero después de que corrijas la causa. Alerta si es superior a cero.
`claude_code_self_hosted_orchestrator_pool_pending_sessions`	Total de sesiones esperando un runner para este entorno. Agregado de todo el entorno, idéntico en cada instancia del orquestador: use `MAX` en lugar de `SUM` entre instancias.
`claude_code_self_hosted_orchestrator_pool_active_sessions`	Sesiones actualmente asignadas a un runner vivo en este entorno. Agregado de todo el entorno, idéntico en cada instancia del orquestador: use `MAX` en lugar de `SUM` entre instancias.
`claude_code_self_hosted_orchestrator_spawn_hooks_total{result}`	Resultados acumulativos del hook `spawn-runner`: `ok`, `retryable`, `non_retryable`. Cuenta invocaciones de hook del orquestador, no hijos de sesión que los runners generan: no comparable a `sessions_started_total`, ya que la capacidad superior a uno, grupos cálidos, y runners generados nuevamente para la misma sesión divergen los dos.
`claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds`	Histograma de duraciones de hook
`claude_code_self_hosted_orchestrator_warm_hints_dispatched_total`	Solicitudes de generación de espera despachadas desde el inicio del proceso
`claude_code_self_hosted_orchestrator_session_queue_wait_seconds`	Histograma de segundos que cada sesión esperó en la cola antes de que el orquestador la reclamara para generación, registrado desde la marca de tiempo de espera en cola que el plano de control envía con la solicitud de generación de cada sesión. Use para alertas de tiempo de cola p50/p99. Los generadores de precalentamiento no se muestrean.
`claude_code_self_hosted_orchestrator_clock_skew_seconds`	Sesgo de reloj local menos servidor; diagnóstico, presente una vez medido
`claude_code_self_hosted_orchestrator_scm_connector_connected`	`1` cuando el WebSocket del conector SCM está abierto; `0` mientras marca o retrocede. Ausente cuando `--scm-connector-host` no está establecido.
`claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total`	Solicitudes HTTP acumulativas proxificadas al host SCM configurado desde el inicio del proceso. Ausente cuando `--scm-connector-host` no está establecido.

Para escalado automático, elija la serie que coincida con su estilo de escalado y ciérrela antes de que se alimente al escalador:

Escalado de profundidad de cola: alimente claude_code_self_hosted_orchestrator_pool_pending_sessions en su escalador HPA o KEDA, no queue_pending_sessions.
Escalado de capacidad: escale en la relación de active_sessions del runner a capacity.
Cierre en connected: filtre la consulta con claude_code_self_hosted_orchestrator_connected == 1 por instancia, para que el valor obsoleto de una réplica desconectada no se alimente al escalador.

Durante una interrupción de sondeo completa, cada réplica desconectada, la consulta cerrada no devuelve datos. HPA mantiene el recuento de réplica actual en una métrica faltante, pero el escalador de Prometheus de KEDA en su ignoreNullValues: "true" predeterminado lee el resultado vacío como cero y escala hacia adentro; establezca ignoreNullValues: "false" en ScaledObject, opcionalmente con un piso de réplica fallback. El siguiente PodMonitor del Operador de Prometheus cubre ambos procesos. Selecciona pods por la etiqueta app.kubernetes.io/part-of: claude-code-self-hosted-runner y el puerto health nombrado que la receta de Kubernetes establece; ajuste los espacios de nombres para que coincidan con su despliegue:

# Ejemplo de PodMonitor del Operador de Prometheus para el runner + orquestador
# autohospedado de Claude Code. Ajuste los selectores de espacio de nombres y
# etiqueta para que coincidan con su despliegue. Tanto el runner como el
# orquestador sirven /metrics en su --health-port (predeterminado 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Coincide con el Deployment del runner de la receta de Kubernetes, más
      # cualquier Job de runner bajo demanda y pods del orquestador que etiquete
      # de la misma forma y dé un containerPort 'health' nombrado.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Reglas de alerta de ejemplo

Estas reglas de alerta de ejemplo son un punto de partida; ajuste los umbrales para el tamaño de su flota:

# 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"

Alertar sobre runners perdidos y sesiones en espera

En una flota fija, carga ClaudeRunnersBelowFloor. Con runners bajo demanda, carga ClaudeOrchestratorSessionsWaiting y ClaudeOrchestratorQueueWaitHigh en su lugar.

Alertar cuando una flota fija pierde runners

ClaudeRunnersBelowFloor se dispara cuando quedan menos runners registrados y raspados que el mínimo durante 10 minutos:

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."

Mínimo: establece el 2 en expr en aproximadamente la mitad de tu número de réplicas, redondeado hacia arriba. Con tres réplicas mantén 2, y la alerta se dispara cuando queda un runner o ninguno.
Espacio de nombres: reemplaza claude-runners en el matcher y en labels, y copia la alerta para cada espacio de nombres adicional. Si tus destinos no tienen una etiqueta namespace, elimina el matcher y la etiqueta, o la alerta lee 0 y se dispara.
ClaudeRunnerPollStale y ClaudeRunnerPollErrors: mantenlas cargadas desde las reglas de alerta de ejemplo, porque ClaudeRunnersBelowFloor sigue contando un runner que no puede sondear

Alertar cuando las sesiones esperan runners bajo demanda

ClaudeOrchestratorSessionsWaiting se dispara cuando el número de sesiones que esperan un runner se mantiene por encima de 0 durante 10 minutos. ClaudeOrchestratorQueueWaitHigh se dispara cuando más del 1% de las esperas en cola de los últimos 10 minutos superaron los 160 segundos, y eso se mantiene durante 5 minutos:

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."

Umbral: si siempre hay alguna sesión esperando, sube el > 0 en ClaudeOrchestratorSessionsWaiting por encima del número que sueles ver
ClaudeOrchestratorDisconnected: mantenla cargada desde las reglas de alerta de ejemplo, porque ClaudeOrchestratorSessionsWaiting deja de dispararse unos 2 minutos después de que se desconecta el último orquestador del espacio de nombres

Pasar a través de métricas de hijo de sesión

Cada sesión se ejecuta en su propio proceso hijo con sus propias métricas de OpenTelemetry; en --capacity superior a uno, el runner reescribe cómo se exponen esas métricas del hijo. Establecer OTEL_METRICS_EXPORTER=prometheus en el host del runner y CLAUDE_CODE_ENABLE_TELEMETRY=1 en el entorno de la sesión, por ejemplo desde su script de envoltura o el entorno propio del runner, que las sesiones heredan, re-expone los instrumentos de contador y indicador de cada hijo en el punto final /metrics propio del runner, junto con la serie del runner. El runner reescribe el exportador del hijo para empujar sobre OTLP a un receptor solo de loopback en el puerto de salud, etiqueta cada serie con etiquetas session_id y client_platform, y desaloja la serie de una sesión cuando esa sesión termina. Los histogramas no pasan, y una métrica del hijo cuyo nombre entraría en conflicto con el prefijo propio del runner se descarta. En el --capacity 1 predeterminado, la reescritura no se aplica: el hijo de la sesión vincula su propio punto final de Prometheus en el puerto 9464 como de costumbre.

Unir las métricas de una sesión con las del runner

Para ver cuánto han costado las sesiones inactivas, une la métrica claude_code_self_hosted_runner_session_idle_seconds del runner con la métrica de costo de Claude Code por ccr_session_id. La métrica del runner no lleva esa etiqueta, así que agrégasela con label_replace, como en esta consulta:

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 consulta devuelve un resultado por cada sesión inactiva durante más de diez minutos: el costo en dólares estadounidenses que su proceso de Claude Code ha contabilizado hasta ahora. Para unir otra métrica de Claude Code, reemplaza claude_code_cost_usage_total en la consulta. La consulta funciona con cualquier --capacity.

session_id: en el puerto 9464, esa etiqueta en las métricas de Claude Code contiene el session.id propio de Claude Code, que no coincide con ninguna serie del runner. Una unión por ella no devuelve nada, así que haz la unión por ccr_session_id.
Las métricas de Claude Code no tienen ccr_session_id: comprueba que OTEL_METRICS_INCLUDE_SESSION_ID no esté establecido en false

Semántica del contador del ciclo de vida de la sesión

Los contadores sessions_started_total, sessions_completed_total, sessions_failed_total, y sessions_interrupted_total clasifican cada sesión por cómo terminó. Cada hijo de sesión generado incrementa sessions_started_total en el tiempo de generación, y exactamente uno de los otros tres incrementa al salir, por lo que sessions_started_total menos la suma de los otros tres es igual al número de hijos de sesión actualmente en ejecución.

completed: la sesión terminó limpiamente. Esto cubre el hijo saliendo por su cuenta con código 0, la sesión siendo archivada o eliminada mientras el hijo aún estaba conectado, y el runner devolviendo el slot limpiamente: liberar la sesión en el timeout de inactividad, en el tiempo de retiro o en el límite --kill-session-after-min; un timeout de inicio; o una desasignación del lado del servidor que el bucle de sondeo notó antes de que el hijo saliera. Incrementa sessions_completed_total.
failed: el hijo salió por su cuenta con un código distinto de cero, ya sea un bloqueo o una falla de configuración después de la generación. Incrementa sessions_failed_total.
interrupted: el runner terminó el hijo por una razón operacional que no es ni un éxito de sesión ni una falla del runner, como un drenaje, o terminar una sesión que aún estaba en el runner cuando la ventana de gracia SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS después de su límite --kill-session-after-min terminó. Un reinicio rodante de Kubernetes enviando SIGTERM es un ejemplo de un drenaje. Incrementa sessions_interrupted_total.

Antes de v2.1.260, el runner terminaba cada sesión que alcanzaba su límite --kill-session-after-min y la contaba en sessions_interrupted_total. El CLAUDE_RUNNER_EXIT_REASON del hook post-session clasifica los traspasos limpios de manera diferente. El hook los reporta como interrupted, porque el runner detuvo el hijo: una liberación, un agotamiento del tiempo de espera de inicio, una desasignación del servidor, y un archivado o eliminación que el sondeo notó primero. Estos contadores registran esos mismos eventos como completed, porque el slot fue devuelto limpiamente. Si reconcilia recibos de hook contra sessions_completed_total directamente, subestima completaciones. Use el hook para garantías por sesión y los contadores para tasas agregadas. En un entorno de un solo disparo, --capacity 1 con el --drain-grace-sec 0 predeterminado, cada proceso del runner sale momentos después de que su única sesión termina. sessions_completed_total, sessions_failed_total, y sessions_interrupted_total incrementan solo al final de la sesión, justo antes de esa salida, por lo que un raspado de Prometheus cada 15 a 60 segundos rara vez detecta el incremento antes de que la serie del runner desaparezca; estos tres contadores de final de sesión son los contadores terminales a los que se refiere el resto de esta sección. sessions_started_total incrementa en la generación y permanece visible durante la vida de la sesión, por lo que se muestra de forma confiable, pero en un entorno de un solo disparo se lee más cerca de “sesiones actualmente en ejecución” que un recuento acumulativo. Use la serie en esta tabla para el objetivo correspondiente en lugar de los contadores terminales:

Goal	Use
Throughput	`claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}`, un contador en el orquestador de larga vida que incrementa una vez por hook `spawn-runner` exitoso y permanece significativo bajo `rate()`. Cuenta invocaciones de hook en lugar de sesiones, por lo que el precalentamiento y los generadores repetidos para la misma sesión lo divergen de los recuentos de sesión.
Utilization	`sum(claude_code_self_hosted_runner_active_sessions)` contra `sum(claude_code_self_hosted_runner_capacity)`, ambos indicadores válidos en cada raspado independientemente de la vida útil del runner
Backlog	`claude_code_self_hosted_orchestrator_pool_pending_sessions` para profundidad de cola, y `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`, alertando si es superior a cero
Failures	`claude_code_self_hosted_runner_sessions_failed_total`, mejor esfuerzo: los bloqueos reales después de la generación sí lo incrementan, y `rate()` es significativo en runners que sobreviven a sus sesiones con `--drain-grace-sec` superior a `0`. Un entorno de un solo disparo tiene el mismo problema de ventana de raspado que los otros contadores terminales, así que trate cualquier valor distinto de cero que vea como digno de investigación. Las fallas antes de la generación, como una falla de hook de checkout, preparación de git, o un problema de token, aparecen solo en `session_init_errors_total`.

Las filas orchestrator_* existen solo en entornos que ejecutan el orquestador bajo demanda. En una flota fija cuyos runners sobreviven a sus sesiones, con --drain-grace-sec superior a 0, use sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) para throughput; en una flota de un solo disparo esa serie tiene el mismo problema de ventana de raspado que los contadores terminales, así que confíe en el recuento de sesiones en cola en su lugar. Verifique el backlog en la pestaña Activity del entorno, en la página de administración Cloud environments: los runners no exportan una serie de profundidad de cola. Para reportes de resultado por sesión, use el hook post-session en su lugar: se dispara en cada final de sesión donde se generó un proceso hijo, aparte de la terminación abrupta del runner como una preemción de VM, según el contrato propio del hook.

Qué sigue

Self-hosted environments: el entorno, runner, y modelo de sesión; el quickstart y Deploy to production contienen configuración y operaciones
Customize sessions: scripts de envoltura, hooks de ciclo de vida, y runners bajo demanda
Verify session identity: el token de sesión, sus reclamaciones, y cómo verificarlo

Configuración

Permisos y sandboxing

Entornos

Modelo y respuestas

Interfaz

Referencia de entornos autohospedados

Flags CLI del runner

Tiempo de espera de inicio de la sesión

Listas de reglas del modo automático

Banderas de CLI del Orchestrator

Banderas del conector SCM

Configuración solo de variables de entorno

Telemetría

Punto final de salud

Métricas de Prometheus

Reglas de alerta de ejemplo

Alertar sobre runners perdidos y sesiones en espera

Alertar cuando una flota fija pierde runners

Alertar cuando las sesiones esperan runners bajo demanda

Pasar a través de métricas de hijo de sesión

Unir las métricas de una sesión con las del runner

Semántica del contador del ciclo de vida de la sesión

Qué sigue

​Flags CLI del runner

​Tiempo de espera de inicio de la sesión

​Listas de reglas del modo automático

​Banderas de CLI del Orchestrator

​Banderas del conector SCM

​Configuración solo de variables de entorno

​Telemetría

​Punto final de salud

​Métricas de Prometheus

​Reglas de alerta de ejemplo

​Alertar sobre runners perdidos y sesiones en espera

​Alertar cuando una flota fija pierde runners

​Alertar cuando las sesiones esperan runners bajo demanda

​Pasar a través de métricas de hijo de sesión

​Unir las métricas de una sesión con las del runner

​Semántica del contador del ciclo de vida de la sesión

​Qué sigue

Flags CLI del runner

Tiempo de espera de inicio de la sesión

Listas de reglas del modo automático

Banderas de CLI del Orchestrator

Banderas del conector SCM

Configuración solo de variables de entorno

Telemetría

Punto final de salud

Métricas de Prometheus

Reglas de alerta de ejemplo

Alertar sobre runners perdidos y sesiones en espera

Alertar cuando una flota fija pierde runners

Alertar cuando las sesiones esperan runners bajo demanda

Pasar a través de métricas de hijo de sesión

Unir las métricas de una sesión con las del runner

Semántica del contador del ciclo de vida de la sesión

Qué sigue