Implementar entornos autohospedados en producción

​

Endurezca su implementación

• Contenedores efímeros por sesión: ejecute cada proceso de runner en un contenedor o VM nuevo que se destruya cuando el proceso salga, con --capacity 1 y el --drain-grace-sec 0 predeterminado para que cada contenedor sirva exactamente una sesión. Con una capacidad más alta, o con un drenaje de gracia positivo, un contenedor sirve múltiples sesiones del mismo propietario bloqueado; consulte Ciclo de vida del runner. No reutilice un sistema de archivos entre reinicios de runner, excepto en la configuración deliberada de checkout precalentado, y nunca entre propietarios.
• Sin credenciales amplias en la imagen: no incluya claves SSH de larga duración, credenciales de proveedor de nube, o tokens de acceso personal que otorguen más de lo que una sesión necesita. Genere credenciales utilizadas durante una sesión, como tokens de push o API, por sesión desde su script de envoltura. Para el clon inicial, que ocurre antes de que se ejecute el envoltura, use un hook de ciclo de vida checkout o --use-anthropic-git-proxy; consulte Configurar git.
• Mantenga el secreto del entorno fuera de los hosts que ejecutan sesiones: el secreto del entorno puede registrar runners y recoger cualquier sesión en cola en el entorno. En una flota fija vive en cada host de runner, donde el código de cualquier sesión puede leer el archivo secreto. Prefiera runners bajo demanda, donde el secreto permanece en el host del orquestador, que nunca ejecuta código de usuario, y cada runner recibe una orden de trabajo de un solo uso que registra exactamente un runner. En una flota fija, trate el archivo de secreto del entorno como legible por cada sesión y rote el secreto después de cualquier compromiso de sesión sospechoso.
• Salida de red de negación predeterminada: restrinja el tráfico saliente del contenedor de runner y sesión en su propio límite de red en cada entorno; Salida de negación predeterminada cubre qué permitir y por qué.
• IAM de host con privilegios mínimos: la identidad de cálculo adjunta al host del runner, como un perfil de instancia o una cuenta de servicio de nodo, debe otorgar solo lo que el runner en sí necesita. Las sesiones deben obtener sus propias credenciales a través de su script de envoltura en lugar de heredar las del host.
• Bloquee el punto final de metadatos en la nube desde las sesiones: mantener las sesiones fuera de la identidad del host requiere bloquear su acceso al punto final de metadatos en la nube, y las políticas de salida a nivel de subred no interceptan el tráfico de metadatos de enlace local, así que bloquéelo en el contenedor en sí:
  • IMDSv2 con un límite de salto de uno
  • GKE Workload Identity con ocultamiento de metadatos
  • Una denegación explícita para 169.254.169.254 en el espacio de nombres de red del contenedor de sesión
  El bloque se aplica a su script de envoltura y hooks de ciclo de vida también, ya que comparten el contenedor. Autentique cualquier intercambio de token con el JWT de sesión contra su propio servicio de token sobre salida permitida, o use una identidad web basada en archivos como IAM Roles for Service Accounts (IRSA) en Amazon EKS.
• Aislamiento del sistema de archivos por runner: cada proceso de runner obtiene su propio directorio de trabajo que ningún otro proceso en el host puede leer o escribir. Haga --hooks-dir, el script de envoltura, y el ~/.claude/ del host de solo lectura para la sesión, ya sea integrado en la imagen o montado como solo lectura.
• El envío no tiene control de acceso por entorno: cualquier miembro de su organización de Anthropic puede enviar una sesión a cualquiera de sus entornos. Si un Propietario enruta canales de Claude Tag al entorno, cualquiera que la configuración de acceso de Claude Tag admita puede iniciar sesiones de canal que se ejecuten allí. Por defecto, eso es cualquiera en el espacio de trabajo de Slack conectado, con o sin una cuenta de Claude. Trate cada host de runner como alcanzable para la ejecución de código por todos los que pueden enviar al mismo, y coloque en un host de runner solo datos y credenciales que todas esas personas pueden leer. --lock-to-account limita qué sesiones de cuenta ejecuta un host determinado, pero no reduce quién puede enviar al entorno. Para hacer que los entornos autohospedados sean la única opción de selector, un Propietario puede ocultar entornos alojados por Anthropic para toda la organización desde la página Entornos en la nube.
• Aplique la protección de configuración del repositorio: elija el modo de protección con --confine-repo-settings. El warn predeterminado registra una violación y aún genera la sesión, enforce rechaza la sesión, y off desactiva el escaneo. El runner escanea la configuración comprometida de cada repositorio para:
  • Una concesión que se resuelve fuera del espacio de trabajo de esa sesión: una entrada additionalDirectories, una regla Edit, Write, o NotebookEdit en permissions.allow, o una entrada sandbox.filesystem.allowWrite o allowRead
  • Un bloque env no vacío
  • Una anulación de postura del operador como sandbox.enabled: false
  La protección se ejecuta independientemente de --trust-workspace, y no cubre hooks de repositorio, .mcp.json, o reglas de Bash; consulte Permisos y aprobación de herramientas para saber dónde pertenecen esas concesiones.

​

Requisitos de red

​

Salida de negación predeterminada

​

Autentíquese en un proxy de salida

​

Elija de dónde viene el valor Proxy-Authorization

• --proxy-authorization-command <command>: elija esto para un token que genera bajo demanda. El runner ejecuta el comando de shell y usa su stdout recortado como el valor del encabezado, por ejemplo Bearer <token>.
• --proxy-authorization-file <path>: elija esto para un token que otro proceso rota en su lugar. El runner lee el archivo y usa su contenido recortado como el valor del encabezado.

​

Configuraciones que el runner se niega a iniciar con

• Ambas banderas establecidas: una bandera más la variable de entorno de la otra bandera cuenta como establecer ambas.
• Sin URL de proxy: ni HTTPS_PROXY ni HTTP_PROXY contiene una URL http:// o https://. El runner lee ambas variables en mayúsculas o minúsculas, y no consulta ALL_PROXY.
• Cualquiera de las banderas pasadas al subcomando del orquestador: self-hosted-runner orchestrator no acepta las banderas o sus variables de entorno. Pase la bandera a cada runner que inicia el orquestador en su lugar.

​

Lo que el runner cambia mientras se establece una bandera de autorización de proxy

• Oyente: el oyente es un proxy directo en 127.0.0.1. El runner inicia el oyente antes de registrarse con el plano de control, y sale al inicio si el oyente no puede iniciar.
• Variables de proxy: el runner reescribe cualquiera de HTTPS_PROXY e HTTP_PROXY que establezca para que apunte al oyente. Ese valor reescrito alcanza el runner en sí, sus hooks de ciclo de vida, y cada sesión que ejecuta.
• Rotación de token: un token rotado entra en vigor sin un reinicio. Para cada conexión que el oyente abre a su proxy, el runner ejecuta su comando o lee su archivo nuevamente y agrega el resultado como el encabezado.
• Entorno de sesión: una sesión alcanza su proxy solo a través del oyente. En el entorno de cada sesión, el runner elimina ALL_PROXY, elimina cualquier ortografía de HTTPS_PROXY o HTTP_PROXY que no haya establecido, y fija NO_PROXY al valor propio del runner.
• Registros: el runner nunca registra el valor del encabezado.

​

Configurar git

• Deje que el runner configure git: inicie el runner con --configure-git para que escriba la misma identidad y configuración de firma de commit que usan las sesiones alojadas por Anthropic
• Envíe la configuración de git en su imagen: establezca la identidad y las credenciales de push usted mismo, por ejemplo para hacer commits bajo su propia identidad de bot

​

Deje que el runner configure git

• user.name = Claude y user.email = noreply@anthropic.com, coincidiendo con sesiones alojadas por Anthropic
• Firma de commit y etiqueta en formato SSH, enrutada a través de un shim gestionado por el runner que firma cada commit a través del servicio de firma de Anthropic usando las credenciales de la sesión. Las firmas son verificables en GitHub contra la clave de firma SSH publicada de Anthropic.

​

Envíe la configuración de git en su imagen

RUN git config --system user.name "Claude" && \
    git config --system user.email "noreply@anthropic.com"

• Una clave de implementación SSH limitada a un repositorio con una reescritura url.<base>.insteadOf
• Un credential.helper que devuelve un token de alcance mínimo
• GIT_SSH_COMMAND apuntando a una clave de alcance estrecho

• El runner establece GIT_TERMINAL_PROMPT=0, por lo que git no pide un nombre de usuario o contraseña.
• El runner ejecuta SSH con BatchMode=yes, añadido a su GIT_SSH_COMMAND si establece uno, por lo que SSH no pide una frase de contraseña o confirmación de host.
• El runner establece GCM_INTERACTIVE=never, por lo que Git Credential Manager no abre un diálogo de inicio de sesión.
• El runner borra core.askPass, así que si usa un ayudante askpass, establézcalo a través de la variable de entorno GIT_ASKPASS en su lugar.

RUN git config --system --add safe.directory '*'

​

Use el proxy de git de Anthropic

​

Reescriba URLs de git para redes privadas

• --git-host-rewrite <from>=<to>: para DNS de horizonte dividido, donde Anthropic alcanza su host de git a través de un nombre de host externo pero los runners deben usar uno interno
• --git-ssh-rewrite <host>: para hosts de git que solo aceptan SSH, reescribiendo https://<host>/owner/repo a git@<host>:owner/repo

​

Construya la imagen del runner

FROM debian:bookworm-slim
ARG CLAUDE_CODE_VERSION
RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \
      -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude
RUN git config --system user.name "Claude" \
 && git config --system user.email "noreply@anthropic.com" \
 && git config --system --add safe.directory '*'
ENTRYPOINT ["claude"]

docker build --build-arg CLAUDE_CODE_VERSION=2.1.224 -t <your-registry>/claude-runner:latest .

​

Dimensione CPU y memoria para sesiones

• Memoria: una solicitud y un límite de 4 GiB cada uno, que cumple con el mínimo de 4 GB en los requisitos del sistema de Claude Code. Mantenga los dos iguales para que el programador tenga en cuenta la memoria completa del contenedor. Cuando el contenedor alcanza su límite de memoria, el kernel mata procesos dentro de él, lo que puede terminar una sesión a mitad de la tarea.
• CPU: una solicitud de 2 CPUs y un límite de 4 CPUs, para que una sesión pueda aumentar por encima de la solicitud durante compilaciones. El kernel acelera un contenedor en su límite de CPU en lugar de matar procesos en él, por lo que las sesiones en el límite se ejecutan más lentamente pero siguen ejecutándose.

resources:
  requests:
    cpu: "2"
    memory: 4Gi
  limits:
    cpu: "4"
    memory: 4Gi

• Una sesión por runner: dé a cada contenedor los valores de una sesión. Use este dimensionamiento en --capacity 1, que la sección de endurecimiento recomienda, y para runners bajo demanda, donde establece los valores en la carga de trabajo que su hook spawn-runner envía, como la plantilla de pod de un Job de Kubernetes.
• Varias sesiones por runner: en un --capacity por encima de uno, multiplique los valores de una sesión por la capacidad, porque hasta esa cantidad de sesiones pueden ejecutarse en el contenedor a la vez. Las recetas de Kubernetes y Docker Compose ejecutan --capacity 4 sin límites de CPU o memoria, así que agregue límites dimensionados para la capacidad que ejecuta.

​

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-runner
  namespace: claude-runners
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-runner
  template:
    metadata:
      labels:
        app: claude-runner
        app.kubernetes.io/part-of: claude-code-self-hosted-runner
    spec:
      terminationGracePeriodSeconds: 90
      containers:
        - name: runner
          image: <your-registry>/claude-runner:latest
          args:
            - self-hosted-runner
            - --environment-secret-file
            - /etc/claude/environment-secret
            - --capacity
            - "4"
          volumeMounts:
            - name: environment-secret
              mountPath: /etc/claude
              readOnly: true
          ports:
            - name: health
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 30
      volumes:
        - name: environment-secret
          secret:
            secretName: claude-runner-environment-secret

kubectl create namespace claude-runners

kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

​

Docker Compose

services:
  claude-runner:
    image: <your-registry>/claude-runner:latest
    command:
      - self-hosted-runner
      - --environment-secret-file
      - /run/secrets/environment-secret
      - --capacity
      - "4"
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

secrets:
  environment-secret:
    file: ./environment-secret

​

Tiempo de apagado

• Con un período de gracia SIGTERM: establezca terminationGracePeriodSeconds en Kubernetes, stop_grace_period en Docker Compose, o el equivalente de su orquestador en al menos ese total. El valor predeterminado de Kubernetes de 30 segundos es más corto que la ruta de drenaje del runner, por lo que Kubernetes detiene el pod antes de que el runner termine de drenar.
• Con --retire-at: dimensione el margen entre el tiempo de jubilación y el tiempo de parada del host para cubrir turnos típicos, más la retención de tarea de fondo que Ciclo de vida del runner describe, más ese mismo total. Calcule el tiempo de jubilación en cada lanzamiento, por ejemplo date +%s más la vida útil prevista del runner.
• Con --defer-shutdown-max-min: agregue dos partes más al total de la ruta de drenaje. La primera es los minutos que configura. La segunda es la gracia posterior a la liberación que Diferir el drenaje más allá de la primera señal describe, 75 segundos en valores predeterminados. Con la bandera establecida, el runner también imprime la cifra combinada al inicio, después del total de la ruta de drenaje.

​

Diferir el drenaje más allá de la primera señal

​

Lo que sucede con las sesiones que el runner mantiene después de la primera señal

• Durante los primeros n minutos: el runner sirve sus sesiones normalmente y sigue aplicando --startup-timeout-min y --kill-session-after-min. Si también establece --release-idle-session-min, el runner libera cualquier sesión cuyo usuario ha estado inactivo ese tiempo; sin ella, el runner no libera ninguna sesión temprano, aparte de un tiempo de espera de inicio.
• Cuando los n minutos se agotan: el runner libera cada sesión que aún mantiene, inactiva o no. El runner espera a que la sesión de mitad de turno termine su turno, y hasta 60 segundos más para las tareas de fondo de un turno, antes de liberar esa sesión.
• Cuando la gracia posterior a la liberación se agota: el runner drena cualquier sesión que aún mantiene, y el plano de control reencola cada sesión drenada a otro runner de inmediato. La gracia posterior a la liberación comienza cuando los n minutos se agotan y es 75 segundos en valores predeterminados. Si establece --drain-wait-sec por encima de 60 segundos, la gracia posterior a la liberación es --drain-wait-sec más 15 segundos en su lugar.

​

Dimensione el tiempo de parada

​

Lo que alcanza un hook post-session en ejecución

• Un SIGTERM mientras el runner ya está drenando: fuerza la salida del runner inmediatamente, omitiendo lo que queda de la ruta de drenaje. Sin --defer-shutdown-max-min, eso es el segundo SIGTERM que recibe el runner. Nada señala un hook post-session en ejecución, por lo que en un host desnudo donde un proceso init adopta huérfanos, termina por su cuenta, pero sin supervisión: su presupuesto de tiempo ya no se aplica, y una escritura en la tubería de registro cerrada puede matarlo con SIGPIPE, así que un hook que necesita sobrevivir a una salida forzada allí debe redirigir su propia salida a un archivo. En las recetas de contenedor en esta página el runner es el PID 1 del contenedor y su salida termina el contenedor, y bajo el KillMode=control-group predeterminado de systemd la matanza de cgroup alcanza el hook también, como la entrada Matanzas de cgroup describe; en ambos, trate una salida forzada como fatal para el hook y confíe en el período de gracia en su lugar.
• Señales de grupo de procesos, como kill -- -<pid> en un script de envoltura, control de trabajo de shell, o un vigilante de grupo: alcanzan el runner y un subproceso de hook checkout en ejecución, que permanece adjunto al grupo deliberadamente, pero no un hook post-session en ejecución o el hijo de sesión.
• Matanzas de cgroup, como el KillMode=control-group predeterminado de systemd o el SIGKILL que Kubernetes entrega a todo el contenedor cuando terminationGracePeriodSeconds expira: alcanzan todo, incluido el hook. El aislamiento de grupo de procesos no protege contra estos, que es por qué el período de gracia debe cubrir la ruta de drenaje completa.
• El tiempo de espera propio del hook: cuando un hook excede --post-session-hook-timeout-sec, el runner envía SIGTERM a todo el grupo de procesos del hook, luego SIGKILL dos segundos después, por lo que un trabajador que el hook bifurcó, como tar, rsync, o git, termina con el shell de envoltura en lugar de sobrevivir como un huérfano. La supervisión del runner termina una vez que el stdio del hook se cierra: un trabajador que redirigió su propia salida a un archivo y sobrevive a la etapa SIGTERM está más allá del alcance del runner.

​

Mantenga el directorio base y la capacidad idénticos en todos los runners

​

Reutilice un checkout precalentado

• Clon en la imagen: construya el clon en su imagen de runner en esa ruta. Cada contenedor nuevo comienza con el clon precalentado sin reutilizar un disco.
• Clon en un volumen persistente: en runners que prebloquea a la cuenta de un usuario con --lock-to-account, apunte --base-dir a un volumen persistente, para que el disco solo sirva esa cuenta. Un runner prebloquado nunca recoge sesiones de canal de Claude Tag, por lo que esta opción no se aplica a runners que las sirven.

• Cualquier forma de clon funciona: un clon completo, superficial, o de rama única en la ruta se usa tal cual. El runner nunca pasa --depth cuando obtiene en un clon existente, por lo que un precalentamiento completo mantiene su historial completo y uno superficial permanece superficial. CLAUDE_RUNNER_FETCH_DEPTH (full, 0, o un número; valor predeterminado 50) controla solo el clon frío que el runner hace cuando no existe clon aún.
• Los cambios rastreados se reinician, los archivos sin rastrear persisten: cada sesión comienza desde un reinicio duro que borra las modificaciones rastreadas de la sesión anterior, pero el runner nunca ejecuta git clean, por lo que los archivos sin rastrear de las sesiones anteriores del propietario bloqueado permanecen en el árbol.
• Con el proxy de git, el reinicio se convierte en un checkout: con --use-anthropic-git-proxy, el runner sanitiza el .git/ del clon antes de cada sesión, manteniendo el almacén de objetos, refs, y estado superficial pero eliminando el índice, por lo que cada sesión paga un checkout de árbol de trabajo completo en lugar de un reinicio casi instantáneo; aún nunca vuelve a clonar. Los precalentamientos de submódulos no son compatibles con el proxy.
• Los clones largos no necesitan solución alternativa: el runner limita cada operación de git con un vigilante de 120 segundos sin progreso y un límite duro de 30 minutos, no un tiempo de espera plano, por lo que un clon frío lento que sigue reportando progreso se completa.

​

Fije la versión

• Para mantener una flota en una versión: construya la imagen con una versión fijada, o en un host desnudo instale una versión específica y desactive las actualizaciones automáticas
• Para actualizar: instale la versión más reciente o reconstruya la imagen, luego reinicie los runners
• Plugins: los mercados de plugins tampoco se actualizan automáticamente; establezca FORCE_AUTOUPDATE_PLUGINS=1 en el entorno del runner para permitir que los plugins se actualicen automáticamente mientras el binario permanece fijado

​

Escale la flota

• Flota fija: ejecute un conjunto estático de réplicas de runner y escale en las métricas de Prometheus que cada runner sirve
• Runners bajo demanda: ejecute el subcomando claude self-hosted-runner orchestrator, que sondea Anthropic para sesiones que están en cola sin runner disponible e invoca su hook spawn-runner para arrancar uno por sesión. Consulte Runners bajo demanda.

​

Problemas conocidos y limitaciones

​

El tráfico del conector sale de su red

• https://api.anthropic.com/v2/ccr-sessions/*
• https://api.anthropic.com/v1/code/sessions/*
• https://api.anthropic.com/v1/code/mcp/*

​

Algunas sesiones no cuentan como inactivas

​

Limitaciones adicionales

• Las sesiones reanudadas pierden trabajo no empujado: cuando una sesión se libera, en tiempo de espera inactivo o en un reinicio de runner, y el usuario envía otro mensaje, la sesión se reanuda en un runner nuevo que clona el repositorio nuevamente desde su rama inicial, por lo que el trabajo que la sesión no había empujado se ha ido. Establezca --push-outcome-on-release para que el runner haga un mejor esfuerzo para empujar las ramas de resultado de la sesión antes de liberarla, para que la sesión reanudada comience desde esos commits en su lugar; esto preserva trabajo comprometido, no un árbol de trabajo sucio. Antes de habilitarlo, restrinja quién puede empujar a refs claude/* en el remoto de origen, por ejemplo con un conjunto de reglas de rama: en la reanudación, el runner obtiene la rama previamente empujada sin verificar quién la empujó, por lo que cualquiera con acceso de push a esos refs puede colocar contenido en el espacio de trabajo reanudado. El runner también descarta la configuración por sesión en la reanudación, lo que significa el directorio de configuración de Claude de la sesión y cualquier estado de shell que la sesión escribió; --push-outcome-on-release no cubre esos.
• Los repositorios privados no se pueden agregar en mitad de sesión: un repositorio agregado a una sesión después de que ha comenzado no se clona con credenciales en un runner autohospedado, por lo que la adición falla. Seleccione cada repositorio que la sesión necesita cuando la crea.
• Algunos conectores no aparecen en sesiones autohospedadas: un conector que aún no ha conectado en la configuración de claude.ai no se enumera en una sesión autohospedada, y la sesión no le pedirá que lo conecte. Conéctelo en Configuración primero, luego inicie una sesión nueva. Agregar un conector a una sesión ya en ejecución tampoco hace que sus herramientas estén disponibles para Claude; inicie una sesión nueva para recoger un conector recién agregado.

​

Reportar un problema

​

Solución de problemas

claude self-hosted-runner doctor

• El runner no aparece en el entorno: confirme que el host pueda alcanzar api.anthropic.com sobre HTTPS, que el secreto del entorno sea actual y que el reloj del host esté dentro de cinco minutos de la hora real; un sesgo mayor causa que la autenticación falle. El runner registra [runner:fatal] con el motivo del rechazo en caso de fallo de autenticación.
• El runner se cierra al inicio con cannot create or write to base directory: el runner no puede crear ni escribir en --base-dir, que por defecto es /workspace. Corrija la propiedad del directorio o apunte --base-dir a una ruta escribible, como se describe en Mantener el directorio base y la capacidad idénticos en todos los runners. Si el runner registra [runner:fatal] diciendo que la verificación del directorio base agotó el tiempo de espera, el directorio está en un montaje NFS o CSI colgado. Verifique la salud del montaje en lugar de los permisos. El runner imprime ambas fallas de inicio en stderr antes de abrir --log-file, así que búsquelas en la terminal o en los registros del contenedor de su plataforma en lugar del archivo de registro. Antes de v2.1.225, el runner no verificaba el directorio base al inicio, y esta configuración incorrecta fallaba en las sesiones después de la recogida.
• Las sesiones permanecen en cola: cada runner en línea puede estar bloqueado a un propietario diferente. Verifique la métrica claude_code_self_hosted_runner_locked_account de cada runner o el campo locked_account de su línea de registro [runner:health] para ver quién la mantiene. Ambos muestran el correo electrónico del propietario solo después de que el runner haya recibido un token de sesión que lleve un reclamo act.email, que las sesiones de un agente Claude Tag nunca hacen. Sin el reclamo, el runner no emite ninguna serie locked_account y registra locked_account=yes, lo que le indica que el runner está bloqueado pero no a qué propietario. Agregue réplicas o espere a que un runner existente se drene y reinicie. Si el entorno usa runners bajo demanda, verifique el orquestador en su lugar; consulte On-demand runners.
• Las sesiones fallan inmediatamente después de la recogida: abra la sesión en claude.ai/code para ver el error. Las causas más comunes son las credenciales de git faltantes en la imagen del runner y las herramientas de compilación que no están instaladas. Un directorio base no escribible detiene el runner al inicio en lugar de fallar en las sesiones. Consulte la entrada El runner se cierra al inicio con cannot create or write to base directory en esta lista.
• Las sesiones no pueden alcanzar la red a través de un proxy de salida autenticador: cuando la fuente que estableció con --proxy-authorization-command o --proxy-authorization-file falla, agota el tiempo de espera después de 30 segundos o produce un valor vacío, el runner responde esa conexión con 502 Bad Gateway y registra por qué. El runner redacta stderr del comando en ese registro y nunca registra el valor del encabezado. Con --proxy-authorization-command, ejecute el comando usted mismo en el host para confirmar que imprime el valor de encabezado completo en stdout. Si el runner se cierra al inicio con could not start the proxy-authorization listener, no pudo abrir su oyente de loopback.
• El runner registra líneas Poll failed que contienen rejecting the malformed poll response: el runner recibió una respuesta de sondeo de trabajo cuyo cuerpo no es el JSON esperado de la cola, la mayoría de las veces porque algo entre el runner y api.anthropic.com, como un proxy interceptor o un portal cautivo, respondió con su propia página. El runner rechaza la respuesta, la cuenta bajo el tipo transport de la métrica claude_code_self_hosted_runner_poll_errors_total, y reintenta en el cronograma de sondeo fallido descrito en Session lifecycle. El runner continúa sirviendo sus sesiones activas. Configure el proxy para pasar las respuestas de api.anthropic.com sin alterar. Antes de v2.1.246, el runner leía tal respuesta como una cola de trabajo vacía, lo que podría terminar sus sesiones activas o hacer que se cierre.
• La rama de una sesión ya no existe en el remoto: para una fuente de git que la sesión solo lee, el runner omite esa fuente y continúa con las restantes. Para la fuente a la que la sesión envía resultados, una rama eliminada, típicamente porque fue fusionada y auto-eliminada, falla la sesión con un error que nombra el repositorio y la rama y le pide que restaure la rama y reintente. El runner falla la sesión con el mismo error cuando omitir dejaría sin repositorio en absoluto. Antes de v2.1.228, tal sesión comenzaba en un directorio vacío.
• Las sesiones tardan minutos en iniciarse: el clon inicial generalmente domina. Observe la métrica claude_code_self_hosted_runner_session_init_duration_seconds para confirmar, y corte el clon con un pre-warmed checkout o un CLAUDE_RUNNER_FETCH_DEPTH más pequeño.
• El pod se mata a mitad del drenaje: aumente terminationGracePeriodSeconds al menos al valor que el runner registra al inicio. Consulte Shutdown timing.

​

Qué sigue

• Personalice sesiones: scripts de envoltura, hooks de ciclo de vida, runners bajo demanda, servidores MCP, y permisos
• Pruebe de extremo a extremo: verifique una nueva imagen de runner desde CI antes de promoverla
• Referencia: cada bandera CLI, variable de entorno, y métrica