Implementar entornos autohospedados en producción

​

Endurezca su implementación

• Contenedores efímeros por sesión: ejecuta 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; consulta Ciclo de vida del runner. No reutilices un sistema de archivos entre reinicios de runner, excepto en la configuración deliberada de checkout precalentado, y nunca entre propietarios.
  • Cuando el runner detiene una sesión, no envía ninguna señal a un proceso que siga en ejecución después de que su comando de shell terminó, como un servicio que se convirtió en daemon. Destruir el contenedor o la VM finaliza ese proceso.
• Sin credenciales amplias en la imagen: no incluyas 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. Genera las credenciales utilizadas durante una sesión, como tokens de push o de API, por sesión desde tu script de envoltura. El clon inicial ocurre antes de que se ejecute el script de envoltura, así que gestiónalo con un hook de ciclo de vida checkout, o con --use-anthropic-git-proxy cuando todos los repositorios de una sesión estén en github.com. Para ambos casos, consulta Configurar git.
• Mantén las credenciales de GitHub del host lejos de las sesiones: Claude puede usar cualquier credencial de GitHub que una sesión pueda leer, con el acceso que esa credencial otorgue. Mantén las credenciales de GitHub de alcance amplio del propio host del runner fuera de todo lo que una sesión pueda leer. Una credencial así puede ser un token de acceso personal, el token que gh auth login guarda para tu cuenta, o un GH_TOKEN en el entorno del runner.
  • Con git administrado por Anthropic: con una credencial así, Claude llega a GitHub directamente en lugar de hacerlo a través del git administrado por Anthropic.
  • Sin git administrado por Anthropic: una credencial de clonación puede permanecer en la imagen si limitas su alcance tan estrictamente como describe Incluir la configuración de git en tu imagen.
• 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

• statsig.anthropic.com, *.sentry.io, claude.ai y platform.claude.com: estos hosts aparecen en algunas listas de verificación de red empresarial más antiguas, pero el runner no los alcanza. Las obtenciones de banderas de características van a api.anthropic.com, y el runner se autentica con el secreto del entorno en lugar de OAuth interactivo.
• mcp-proxy.anthropic.com: las sesiones autohospedadas no lo usan. Cuando la entrega de conectores está habilitada para tu organización, los conectores de claude.ai de tu organización llegan a las sesiones a través de api.anthropic.com. Consulta Servidores MCP.

• El instalador de una línea: obtiene install.sh de claude.ai en el momento de la instalación.
• claude auth login interactivo: inicia sesión a través de claude.ai, claude.com y platform.claude.com. La configuración guiada, el modo con sesión iniciada de doctor y el envío desde CI lo usan. El navegador con el que inicias sesión también carga las verificaciones de navegador de la página de inicio de sesión de claude.ai desde hcaptcha.com, *.hcaptcha.com y challenges.cloudflare.com. Si tu organización usa inicio de sesión único, ese navegador también puede ser redirigido a través de sso.claude.com.

​

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.
• push.negotiate = true, para que git pregunte a su host de git qué commits ya tiene antes de empacar un push. Requiere Claude Code v2.1.257 o posterior.
• core.hooksPath apuntando a un directorio de hooks gestionado por el runner. Sus hooks commit-msg y prepare-commit-msg añaden a cada commit un tráiler Co-authored-by: para el creador de la sesión. El tráiler se construye a partir del correo electrónico en CCR_SESSION_ACCOUNT_EMAIL y se omite cuando esa variable no está establecida. Si tu imagen ya establece core.hooksPath y el runner no usa git gestionado por Anthropic, el runner conserva tu ajuste, omite instalar estos hooks e imprime una advertencia [runner:git].

​

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

• Solo github.com: Anthropic atiende una sesión solo cuando todos sus repositorios están en github.com, y el proxy de git aún no admite GitHub Enterprise Server. En un runner con el proxy de git, una sesión con un repositorio en otro host de git no se inicia.
• Credenciales solo para los repositorios de la sesión: Anthropic proporciona credenciales de git para los repositorios que forman parte de la sesión, no para otros repositorios en el mismo host de git. Un submódulo privado, una dependencia que tu gestor de paquetes obtiene con git o un marketplace de plugins en otro repositorio no reciben ninguna credencial de Anthropic. Pide a las personas que crean sesiones que agreguen cada repositorio que una sesión necesita al crearla. Cada ejecución de una tarea programada en la nube es una sesión con los repositorios de la tarea, así que pide al propietario de cada tarea que agregue cada repositorio que necesitan sus ejecuciones.
• Solo push de ramas: un push que elimina una rama falla, y también falla un push a cualquier otro tipo de ref, como una etiqueta. Para saber qué ramas puede actualizar un push, consulta Proxy de GitHub.
• Cuentas de GitHub conectadas: pide a cada persona que crea sesiones de usuario con un repositorio que conecte GitHub. Sin su propia conexión, esas sesiones no se inician.
• --capacity 1: el proxy de git requiere una sesión por proceso de runner, así que ejecuta más réplicas para paralelismo. Activa el proxy de git de Anthropic enumera los requisitos.
• Configuración global de git reemplazada: el runner elimina y reemplaza la configuración global de git del usuario con el que se ejecuta. Ejecútalo como un usuario dedicado o en un contenedor.
• Credenciales del host para los push del host: el push de --push-outcome-on-release del runner y cualquier push que haga tu hook post-session siguen usando las propias credenciales de git del host del runner y su ruta de red hacia github.com. Mantén esas credenciales fuera de la configuración global de git, y consulta Incluye la configuración de git en tu imagen para conocer formas de proporcionarlas.
• Decisión por sesión: Anthropic decide para cada sesión del runner si atiende su git, y una sesión que no atiende no se inicia. Cuando las sesiones no se inician en un runner con el proxy de git cubre las causas.

​

Activa el proxy de git de Anthropic

• Claude Code v2.1.267 o posterior: las versiones anteriores aceptan el flag pero no reportan la solicitud para que Anthropic atienda git ni imprimen la línea Registering as opted in, por lo que Anthropic no atiende sus sesiones.
• --capacity 1, el valor predeterminado: cada proceso de runner maneja una sesión a la vez, así que ejecuta más réplicas para paralelismo.
• Git 2.32 o posterior: las versiones anteriores de git ignoran la configuración de git por sesión que el runner prepara para el proxy de git.

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

​

Cómo atiende Anthropic git para una sesión

• Sesiones de usuario: Anthropic usa el token OAuth de GitHub almacenado para el creador de la sesión.
• Sesiones de bot y de agente: Anthropic usa el token de instalación de GitHub App de tu organización.
• Reescrituras de URL: --git-host-rewrite y --git-ssh-rewrite no tienen efecto en un repositorio que atiende el proxy de git.

​

Cuando las sesiones no se inician en un runner con el proxy de git

• Ni governed git ACTIVE ni la línea withheld: un runner anterior a Claude Code v2.1.267 no registra ninguna de las dos líneas, y Anthropic no atiende sus sesiones. Actualiza el runner a v2.1.267 o posterior siguiendo Fija la versión.
• La línea withheld: Anthropic no atendió la sesión. Un runner que antes funcionaba con el proxy de git puede fallar así sin ningún cambio de tu parte.
  • Un repositorio no está en github.com: una sesión con aunque sea un repositorio en otro host de git, como GitHub Enterprise Server, no se atiende, incluidos sus repositorios de github.com. Desactiva el proxy de git de Anthropic para los runners de ese entorno.
  • Todos los repositorios están en github.com: reporta el fallo a tu equipo de cuenta de Anthropic con el ID de sesión de la línea withheld. Anthropic registra el motivo de su lado.
• Una línea que contiene remote: access denied by the git proxy: una sesión que Anthropic atiende aún puede ser rechazada, por ejemplo cuando la política de la organización deniega el acceso a git para la sesión, o la sesión no está autorizada para el repositorio. El registro del runner muestra entonces una línea que contiene remote: access denied by the git proxy, y el resto de esa línea indica el motivo.
• GitHub authentication required: esto aparece cuando el creador de la sesión no tiene una conexión de GitHub funcional en claude.ai. El clon de la sesión falla, y el error de git dice GitHub authentication required. Please reconnect your GitHub account. Pídele a esa persona que conecte o vuelva a conectar GitHub en su configuración de claude.ai.

​

Desactiva el proxy de git de Anthropic

unset CLAUDE_RUNNER_USE_GIT_PROXY

​

Acceso a la API de GitHub sin la GitHub CLI

gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

• Credenciales: el gh integrado envía sus solicitudes REST a través de git gestionado por Anthropic, que proporciona la credencial de GitHub del lado de Anthropic, así que la imagen no necesita ningún token de GitHub para ello
• Qué sesiones lo obtienen: Anthropic decide por sesión si git gestionado por Anthropic atiende el gh de la sesión. Cuando lo hace, la línea [runner:session] governed git ACTIVE que el runner registra para la sesión muestra gh_path_shim=true. Cuando no lo hace, la sesión no tiene gh
• jq: instala jq en la imagen si quieres que --jq funcione
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: si el entorno de la sesión la establece, Claude Code no proporciona el gh integrado, y la sesión no tiene gh

​

Confíe en una autoridad de certificados privada con git gestionado por Anthropic

• Almacén de certificados del sistema: instale su CA en el almacén de certificados del sistema del host del runner, y git confía en él sin ninguna variable.
• GIT_SSL_CAINFO: establézcalo en un archivo PEM de sus CAs, por ejemplo GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem.
• GIT_SSL_NO_VERIFY: no ayuda detrás de un proxy de re-firma. El clon propio del runner a través de git gestionado por Anthropic verifica certificados incluso cuando la variable está establecida, así que ese clon falla hasta que git confía en su CA a través de uno de los otros dos enfoques.

• GIT_SSL_CAINFO: contra qué verifica git a git gestionado por Anthropic depende de dónde se ejecute git:
  • Clon y fetch propios del runner: se ejecutan sin la variable y verifican git gestionado por Anthropic contra un archivo de certificado por sesión que escribe el runner. El runner crea ese archivo a partir del paquete de CA del sistema del host del runner y los certificados de tu archivo.
  • Git dentro de la sesión: obtiene configuración http.sslCAInfo que nombra tu archivo en lugar de la variable, más entradas http.<url>.sslCAInfo que verifican git gestionado por Anthropic contra el archivo por sesión.
  • Hooks checkout y post-session: heredan la variable sin cambios.
• GIT_SSL_NO_VERIFY: qué verificaciones de certificado permanecen desactivadas depende de dónde se ejecute git:
  • Clon y obtenciones propios del runner: se ejecutan sin la variable y verifican el certificado que se les presenta.
  • Git dentro de la sesión: obtiene configuración http.sslVerify=false en lugar de la variable, así que las verificaciones permanecen desactivadas para otros hosts. También obtiene entradas http.<url>.sslVerify=true que mantienen las verificaciones activadas para git gestionado por Anthropic.
  • Hooks checkout y post-session: cuando la sesión tiene un repositorio en git gestionado por Anthropic, obtienen configuración http.sslVerify=false en lugar de la variable. También obtienen entradas http.<url>.sslVerify=true que mantienen las verificaciones activadas para git gestionado por Anthropic.

​

Agrega repositorios de github.com a sesiones de canales de Claude Tag

​

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, o un host de runner que solo tiene una clave SSH. Por ejemplo, para clonar repositorios de github.com por SSH, agrega --git-ssh-rewrite github.com al comando del runner. El runner entonces reescribe https://github.com/owner/repo a git@github.com:owner/repo. SSH debe conectarse sin pedir nada.

​

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 jq python3 \
 && 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="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \
  -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.
• Varios contenedores de runner en un host: dimensiona el host para la suma de las capacidades de los runners, porque cada runner cuenta solo sus propias sesiones contra --capacity:
  • Memoria: multiplica la memoria de una sesión por la suma y luego agrega lo que usan los propios procesos del host
  • CPU: multiplica la solicitud de CPU de una sesión por la suma. Para permitir que todas las sesiones superen su solicitud a la vez, multiplica en su lugar su límite de CPU.
  Da a cada runner su propio contenedor. Usa la misma ruta de --base-dir en cada uno, en un almacenamiento que ningún otro contenedor de runner monte, para que cada runner tenga su propio directorio de trabajo.

​

Da a cada sesión su propio límite de memoria

• En un contenedor: ejecuta un runner por contenedor y establece el límite de memoria del contenedor, como limits.memory en Kubernetes, --memory en Docker o mem_limit en un archivo de Compose. Mantén la suma de los límites de los contenedores por debajo de la memoria del host, porque cuando el propio host se queda sin memoria, el kernel puede matar procesos en cualquier parte del host.
• Bajo systemd sin contenedor: establece MemoryMax en la unidad del runner y ejecuta un runner por host, porque los runners que usan el mismo --base-dir en un sistema de archivos comparten los repositorios clonados allí. Por ejemplo, en --capacity 1 sin un hook checkout, sus sesiones sobre un mismo repositorio pueden trabajar en el mismo checkout a la vez. Para ejecutar varios runners en un host, da a cada uno un contenedor.

​

Deja margen bajo los límites de procesos e hilos

​

Dónde establecer cada límite

​

Mide el pico de una sesión

​

Comprueba un límite pids.max

• Comprueba si se alcanzó pids.max: busca en el registro del kernel del host, por ejemplo con dmesg, una línea que contenga cgroup: fork rejected by pids controller in y la ruta de un cgroup. El kernel la registra solo la primera vez que rechaza un proceso o hilo en ese cgroup, así que busca en todo el registro.
• Consulta el límite vigente: lee pids.max en el directorio de cgroup del runner y en cada directorio por encima de él. El valor más bajo es el límite vigente, y max significa que no hay límite en ese nivel.

​

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"
            - --base-dir
            - /workspace
          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"
      - --base-dir
      - /workspace
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

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

​

Tiempo de apagado

1. El runner espera hasta --drain-wait-sec segundos, 0 por defecto, a que terminen los turnos que aún están en ejecución.
2. Termina el árbol de procesos de cada sesión, incluido cualquier comando que Claude aún estaba ejecutando, pero no un proceso que sigue en ejecución después de que su comando de shell terminó.
3. Ejecuta el hook de ciclo de vida post-session.

• --drain-wait-sec para el paso 1, 0 segundos por defecto
• --session-stop-grace-sec para el paso 2, 5 segundos por defecto
• --post-session-hook-timeout-sec para el paso 3, 60 segundos por defecto
• Un margen fijo de 15 segundos
• 30 segundos más cuando --push-outcome-on-release está establecido

• Con --retire-at: deja suficiente tiempo entre el tiempo de retiro y el momento en que el host se detiene para que terminen los turnos típicos, más la espera de las tareas en segundo plano que describe Ciclo de vida del runner, más el tiempo registrado. Calcula el tiempo de retiro en cada lanzamiento, por ejemplo date +%s más la vida útil prevista del runner.
• Con --defer-shutdown-max-min: el tiempo de parada también debe cubrir los minutos que configuras y una espera adicional antes de que comience el drenaje, 75 segundos con la configuración predeterminada. Diferir el drenaje más allá de la primera señal explica ambos. El runner también registra este tiempo más largo al inicio.

​

Dejar que los turnos en ejecución terminen antes de un reinicio

• --drain-wait-sec: aproximadamente lo que duran los turnos y las tareas en segundo plano que quieres dejar terminar. Es un máximo: la espera termina antes si ellos terminan primero.
• Tu tiempo de parada: terminationGracePeriodSeconds en Kubernetes, stop_grace_period en Docker Compose. Por ejemplo, con --drain-wait-sec 120, reemplaza el 90 en la receta de Kubernetes o de Docker Compose por 200.
• Si cambiaste otros ajustes de apagado: los 80 segundos corresponden a la configuración predeterminada. Inicia un runner con tus flags y usa al menos el número de su línea de inicio This runner needs up to, que incluye la espera. Con --defer-shutdown-max-min establecido, usa el número mayor de la siguiente línea de inicio, después de Size the stop timeout to at least. Tiempo de apagado enumera lo que aumenta estos números.

​

Publicar un mensaje de estado antes de un reinicio

​

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, las sesiones inactivas permanecen en el runner.
• 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 del 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, trata una salida forzada como fatal para el hook y confía 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 todo el drenaje.
• 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

• Con --capacity 1: el runner obtiene la ref solicitada, desasocia HEAD y hace un reinicio duro a ella, lo cual es casi instantáneo cuando ha cambiado poco.
• Con un --capacity mayor que uno: el runner obtiene en ese clon y luego extrae un worktree separado a partir de él para cada sesión. Un clon precalentado ahorra la descarga, pero no el checkout.

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

• Profundidad del clon: crea el clon sin --depth, con o sin --single-branch. El runner nunca pasa --depth cuando obtiene en un clon con un remoto origin, incluso si configuras CLAUDE_RUNNER_FETCH_DEPTH. Con un clon completo, cada sesión descarga solo los commits que le faltan al clon. Con un clon superficial, una sesión en una rama que se bifurcó antes del commit más antiguo del clon descarga todo el historial de esa rama.
• Los cambios rastreados se reinician, los archivos sin rastrear persisten: con --capacity 1, 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.
• Directorios por sesión persisten también: junto al checkout, el runner crea entradas por sesión bajo <base-dir>/_sessions/ para cada sesión que ejecuta. El directorio de configuración de Claude de la sesión contiene una copia local de la transcripción de la conversación. Junto a él se encuentran los archivos cargados de la sesión, cuando la sesión tiene alguno. El directorio de sesión también se encuentra allí: contiene cualquier worktree por sesión y checkouts de hook checkout mientras se ejecuta la sesión, y mantiene cualquier otra cosa que Claude escribió en él. Por defecto, el runner deja estos en su lugar cuando termina la sesión, por lo que en un disco que sobrevive al proceso del runner se acumulan. Cada sesión se ejecuta como el usuario del runner, por lo que cualquier sesión posterior que ese disco sirva puede leerlos. Si mantiene un --base-dir persistente, dimensione el volumen para ese crecimiento. Lo mismo se aplica a cualquier configuración que reinicie el runner en el mismo sistema de archivos, incluida la receta de Docker Compose.
• Con --remove-session-state, los directorios por sesión no persisten: inicie el runner con --remove-session-state para que elimine los directorios por sesión de cada sesión cuando termina la sesión. La eliminación es de mejor esfuerzo: los directorios permanecen cuando el runner se mata antes de que se ejecute su limpieza. El clon canónico y los archivos que una sesión escribió en otro lugar del host, como el directorio temporal, permanecen independientemente.
• 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. Mantiene el almacén de objetos y el estado superficial, y elimina el índice. Sin el índice, cada sesión comienza con un checkout completo del directorio de trabajo en lugar de un reinicio casi instantáneo. El runner sigue obteniendo en el clon existente en lugar de volver a clonar el repositorio. Los precalentamientos de submódulos no son compatibles con el proxy.
• Con el proxy de git, un precalentamiento con reftable pierde sus refs: cuando el runner sanitiza .git/ antes de cada sesión, mantiene .git/refs/ y elimina el directorio .git/reftable/. Un clon precalentado con el formato de refs reftable de git pierde así sus refs, por lo que debes precalentar el clon con el formato de refs files de git en su lugar.
• 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.

​

Confirma que el runner usa tu clon

​

Fije la versión

• Antes de fijar una versión: consulta las versiones de Claude Code que requieren los modelos para cada modelo que usan tus sesiones. Si un modelo requiere una versión más reciente que la que ejecutan tus sesiones, el servidor rechaza las solicitudes para ese modelo con Claude Code no admite este modelo.
• 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 una flota fija: lee las entradas del changelog entre tu versión y la que vas a instalar; luego instala la versión más reciente o vuelve a crear la imagen y reinicia los runners
• Para actualizar runners bajo demanda: lee las entradas del changelog entre tu versión y la que vas a instalar; luego cambia la imagen que inicia tu hook spawn-runner. Cada runner nuevo obtiene la nueva versión. Un runner que ya está en ejecución, incluido un runner en espera que inició --min-idle, conserva su versión hasta que termina. No lo reinicies, porque su orden de trabajo es de un solo uso.
• Si las sesiones inician un binario diferente: si usas --exec-path o un hook command para iniciar un binario de Claude Code distinto del propio del runner, las sesiones ejecutan la versión de ese binario. Actualiza ese binario cuando actualices el runner.
• 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.

​

Libera las sesiones inactivas en una flota fija

• Series por encima de ese tiempo, como 1800 para 30 minutos: las sesiones inactivas ocupan esos espacios, así que establece --release-idle-session-min
• Todas las series por debajo: ninguna sesión ha estado inactiva tanto tiempo. Agrega runners o establece --kill-session-after-min para las sesiones que nunca quedan inactivas.
• Un runner sin series: ninguna sesión lo ocupa. Consulta Sessions stay queued en Solución de problemas.
• Un runner cuyas métricas no responden: es posible que su proceso haya terminado. Consulta An environment that looks healthy en Cuando el runner termina.

• Trabajo sin enviar: una sesión liberada se reanuda con su siguiente mensaje, sin el trabajo que no había enviado con push. Para conservar sus commits, consulta Las sesiones reanudadas pierden el trabajo sin enviar.
• El runner termina: un runner que libera su última sesión inicia una salida normal. Haz que tu supervisor lo reinicie en un sistema de archivos limpio, como se describe en Refuerza tu despliegue.
• Sesiones que nunca quedan inactivas: establece también --kill-session-after-min, porque algunas sesiones no cuentan como inactivas

​

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

• Si la sesión está esperando a su usuario, el runner la libera. Si su turno ha terminado y solo mantiene tareas de fondo, el runner espera hasta 60 segundos a que esas tareas terminen y luego la libera. La sesión se reanuda cuando su usuario envía su siguiente mensaje.
• Si un turno aún se está ejecutando, el runner espera a que el turno termine, o a que la sesión espere a su usuario, y luego la libera.
• Si la sesión aún está en el runner cuando la ventana de gracia termina, el runner la termina, y se pierde el trabajo de cualquier turno en ejecución. Un turno esperando una aprobación solicitada desde dentro de una llamada de herramienta en ejecución es una forma en que una sesión supera la ventana.

​

Limitaciones adicionales

• Las sesiones reanudadas pierden el trabajo sin push: un runner nuevo vuelve a clonar el repositorio desde su rama inicial, por lo que el trabajo al que la sesión no había hecho push se pierde.
  • Para conservar el trabajo con commit: establece --push-outcome-on-release en todos los runners del entorno, porque un runner sin el flag reanuda la sesión desde su rama inicial. Un runner con el flag hace, en la medida de lo posible, push de las ramas de resultado de la sesión antes de liberarla, y la sesión reanudada comienza desde esos commits. El push usa las credenciales de git propias del host del runner, incluso en un runner que usa git administrado por Anthropic.
  • Con un hook checkout: a los repositorios obtenidos mediante un hook de ciclo de vida checkout no se les hace push. En su lugar, guarda una instantánea de ellos desde el hook post-session.
  • Antes de habilitar el flag: restringe quién puede hacer push a las refs claude/* en el remoto de origen. Al reanudar, el runner obtiene la rama a la que se hizo push previamente sin verificar quién hizo el push.
  • Los cambios sin commit se siguen perdiendo: para pedirle a Claude que haga commit y push cuando termine de responder, consulta Pedir a las sesiones que hagan push de su trabajo
• Un comando interrumpido por la pérdida de un runner puede volver a ejecutarse: cuando la sesión se reanuda en otro runner, Claude ve la llamada a herramienta interrumpida con un resultado que indica que su desenlace es desconocido.
• Un repositorio agregado a mitad de sesión puede fallar al clonarse: Claude lo clona con git clone a través de HTTPS. En un runner sin --use-anthropic-git-proxy, la clonación falla con un error de autenticación de git si nada en el host puede leer el repositorio. Siempre que puedas, selecciona todos los repositorios que la sesión necesita al crearla.
• 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.
• Cuando alguien archiva o elimina una sesión, o libera su runner desde el menú de la sesión: no cuentes con el push de --push-outcome-on-release. Para guardar los commits en esos casos, haz push de HEAD a una rama de rescate desde un hook post-session. Si partes del ejemplo de esa sección, haz que haga push incluso cuando no haya nada sin commit, porque solo hace push después de un commit de instantánea.

​

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.
• El runner se cierra al inicio con RegisterRunner failed: y un error de certificado TLS: el error puede ser self signed certificate in certificate chain, por ejemplo. El runner no confía en la autoridad de certificación (CA) detrás del certificado que recibió, como ocurre detrás de un proxy que inspecciona TLS. Establece NODE_EXTRA_CA_CERTS en el entorno del runner con un archivo PEM que contenga la CA raíz del proxy. No necesitas establecerla de nuevo para las sesiones, que la heredan. Git no la lee: para clonar a través de ese proxy, establece también GIT_SSL_CAINFO.
• Tu script de inicio imprime un error de escritura que contiene Resource temporarily unavailable y se cierra: tu script comparte su stdout o stderr con el proceso claude self-hosted-runner u orquestador que inicia, el cual ha cambiado esa tubería o socket compartido al modo no bloqueante. Cuando la tubería está llena, una escritura de tu script falla con este error del sistema operativo en lugar de esperar, y con set -e el script se cierra. Para evitar el error, envía la salida del runner o del orquestador a un archivo que el usuario de tu script pueda crear. Agrega >> "$HOME/claude-runner.log" 2>&1 al comando que lo inicia, antes de cualquier & que lo envíe a segundo plano:
  claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1
  
  La salida propia de tu script sigue yendo adonde iba antes, mientras que lo que el runner escribe en stdout y stderr, incluidos sus errores de inicio, va a ese archivo. Usa esta redirección del shell en lugar de solo --log-file, que replica el registro en un archivo mientras el runner sigue escribiendo en stdout y stderr. Si ya pasas --log-file, mantenlo también, porque la redirección no cambia lo que recibe ese archivo.
• El orquestador registra poll failed: con un error de certificado TLS y sigue reintentando: el orquestador no confía en la CA detrás del certificado que recibió, como ocurre detrás de un proxy que inspecciona TLS. Establece NODE_EXTRA_CA_CERTS en el entorno del orquestador con un archivo PEM que contenga la CA raíz del proxy. Establécela también para los runners que inicia tu hook spawn-runner. Por ejemplo, una línea puede terminar en poll failed: self signed certificate in certificate chain — retrying in 1s, con las palabras de la biblioteca TLS entre los dos puntos y el guion. Para confirmar la corrección, comprueba que connected sea true en el cuerpo de /healthz del orquestador.
• 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: abre la sesión en claude.ai/code para ver el error. Si el error muestra que git no pudo autenticarse, revisa las credenciales de git del runner. En un runner iniciado con --use-anthropic-git-proxy, consulta Cuando las sesiones no se inician en un runner con el proxy de git. Un directorio base no escribible detiene el runner al inicio en lugar de hacer fallar las sesiones. Consulta la entrada El runner se cierra al inicio con cannot create or write to base directory en esta lista.
• Una sesión se recoge, pero Claude nunca responde su primer mensaje: si tus runners llegan a api.anthropic.com a través de un proxy, configúralo para que deje pasar la respuesta /worker/events/stream de la sesión a medida que llega. Aumentar los tiempos de espera del runner no ayuda. Para confirmar la causa en el registro del runner, consulta Una sesión se recoge, pero Claude nunca responde su primer mensaje.
• Las sesiones no se inician en un runner que estableció --use-anthropic-git-proxy: busca en el registro del runner access denied by the git proxy, o un error de git que nombre una dirección de api.anthropic.com que contenga /git_proxy/. Para saber si Anthropic atendió la sesión y corregir la causa, consulta Cuando las sesiones no se inician en un runner con el proxy de git.
• 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. Una causa es un proxy interceptor o un portal cautivo que responde con su propia página. Si el runner se conecta a través de un proxy, configura el proxy para que pase las respuestas de api.anthropic.com sin alterarlas. El runner rechaza la respuesta malformada, la cuenta bajo el tipo transport de la métrica claude_code_self_hosted_runner_poll_errors_total, y reintenta según el cronograma de sondeo fallido descrito en Session lifecycle. El runner sigue atendiendo sus sesiones activas. Antes de v2.1.246, el runner interpretaba una respuesta así como una cola de trabajo vacía, lo que podía terminar sus sesiones activas o hacer que se cerrara.
• Una sesión falla con no longer exists on the remote o couldn't find remote ref: el runner interpreta el couldn't find remote ref de git como una rama eliminada. La rama aún puede existir. Búscala en tu host de git, exactamente con el nombre que aparece en el mensaje, y luego revisa cada causa que corresponda:
  • La rama ya no existe: restáurala, como pide el mensaje.
  • La rama existe y no administras el runner: envía al administrador del runner el mensaje completo e indícale que la rama existe.
  • La rama existe y el runner tiene un hook checkout: un comando de git en tu hook puede imprimir couldn't find remote ref en stderr antes de que el hook termine con un código distinto de cero. Encuentra ese comando y corrige la ref que solicita o el remoto del que obtiene. El runner pasa a tu hook la revisión que pidió la sesión como CLAUDE_RUNNER_REPO_REF.
  • La rama existe y el runner no tiene hook checkout: el runner obtiene la rama por sí mismo. Si se aplica un --git-host-rewrite al repositorio, confirma que el host al que reescribe tenga la rama con el mismo nombre, y envía la rama allí si no la tiene.
  • La rama existe y el runner es anterior a v2.1.301: actualiza el runner como se describe en Fijar la versión, para que una falla distinta muestre su propio error. Antes de v2.1.301, otras fallas con couldn't find remote ref en su salida de error también se reportaban como una rama eliminada.
  Una vez que el runner esté actualizado o la causa esté corregida, reintenta la sesión o inicia una nueva. Si ninguna de estas comprobaciones encuentra la causa, reporta un problema. Para la fuente a la que la sesión envía resultados, una rama eliminada hace fallar la sesión. Para una fuente de git que la sesión solo lee, el runner omite esa fuente y continúa con las restantes. El runner hace fallar la sesión cuando omitirla la dejaría sin ningún repositorio. Antes de v2.1.228, una sesión así comenzaba en un directorio vacío.
• Claude Tag a veces no publica su respuesta en Slack: el recordatorio de respuesta es un hook que proporciona el plano de control. Confirma con claude --version que el runner sea Claude Code v2.1.229 o posterior, ya que los runners más antiguos ignoran los hooks proporcionados; confirma que python3 --version funcione dentro de la imagen del runner, ya que los hooks ejecutan python3; y confirma que ningún archivo de configuración desactive los hooks, ya sea disableAllHooks en managed-settings.json, en el ~/.claude/settings.json del usuario del runner o en el .claude/settings.json o .claude/settings.local.json del repositorio, o bien allowManagedHooksOnly o un strictPluginOnlyCustomization que cubra los hooks en la configuración administrada.
• Una sesión comienza sin uno de sus repositorios: en un runner sin un hook checkout, el host de git puede rechazar la verificación de acceso del runner para un repositorio que la sesión solo lee. El runner entonces omite ese repositorio, registra una línea [runner:warn] could not access context source que nombra el rechazo, e inicia la sesión en los restantes. El runner omite solo un rechazo claro: el host responde que el repositorio no fue encontrado, git no encuentra credenciales para el host, o la autenticación falla. Una falla de red, un tiempo de espera agotado, o un HTTP 403 aún falla el inicio de sesión, al igual que un rechazo para un repositorio al que la sesión envía resultados. El runner aún falla una sesión que omitir dejaría sin repositorio en absoluto. Con --use-anthropic-git-proxy, el runner omite solo un repositorio que el proxy de git mismo deniega. La verificación de acceso se ejecuta nuevamente cada vez que la sesión comienza en un runner, así que una vez que la identidad de git del runner tiene acceso de lectura, el siguiente inicio clona el repositorio. Antes de v2.1.274, cada uno de estos rechazos fallaba el inicio de sesión.
• Una sesión no se inicia con This runner couldn't read: el runner le pidió al host de git un repositorio con sus credenciales de git y obtuvo una respuesta de no encontrado. El repositorio no existe, o esas credenciales no pueden acceder al repositorio.
  • Si administras el runner: otorga a sus credenciales de git acceso de lectura al repositorio y luego inicia una nueva sesión.
  • Si iniciaste la sesión: si el repositorio no existe, inicia una nueva sesión con el repositorio correcto. Si el runner no puede acceder al repositorio, pide al administrador del runner que otorgue acceso y luego inicia una nueva sesión.
• Las sesiones tardan minutos en iniciarse o reanudarse: una causa es un clon desde cero. En una flota que inicia cada runner sobre un disco vacío, sin hook checkout, el runner clona de nuevo los repositorios de la sesión antes de iniciar Claude Code. Una sesión que se reanuda sobre un disco vacío vuelve a esperar el mismo clon. Para evitar el clon desde cero, proporciona un checkout precalentado. Si ya proporcionas uno, confirma que el runner lo usa. Cuando el runner hace el clon por sí mismo y se cierra después de una sola sesión, reduce CLAUDE_RUNNER_FETCH_DEPTH desde su valor predeterminado de 50 commits para obtener menos historial. Si usas un hook, este se ejecuta en lugar del clon del runner, así que revisa lo que hace tu hook. Observa la métrica claude_code_self_hosted_runner_session_init_duration_seconds para ver cuánto tardan los inicios.
• Los turnos fallan con un 401: cuando un turno termina con un 401 o 403 de la API de Anthropic, el runner obtiene un CLAUDE_CODE_OAUTH_TOKEN nuevo de Anthropic y lo pasa a la sesión. El turno fallido no se reintenta. Este token es de corta duración, y el runner lo rota a través del stdin de la sesión. Cuando una obtención falla, el runner registra una línea inference_token refresh failed que dice cuándo reintentará, y continúa reintentando mientras la sesión se ejecute. Si cada llamada comienza a fallar aproximadamente 30 minutos en una sesión, un script contenedor probablemente ha cortado stdin de la sesión, por lo que las rotaciones de token no pueden alcanzarlo; consulte Keep stdin and file descriptor 3 attached. Antes de v2.1.274, el runner dejaba de reintentar una obtención fallida después de algunos intentos y esperaba la siguiente programada. Un turno fallido no desencadenaba una obtención, por lo que cada turno fallaba con un 401 hasta la siguiente obtención programada.
• Un turno falla en claude.ai/code con This model needs a newer version of Claude Code: la versión de Claude Code con la que tus runners inician sesiones es más antigua que la que requiere el modelo de la sesión, así que la API rechaza la solicitud. Actualiza los runners a la versión que pide el mensaje, o a una posterior, como se describe en Fijar la versión. Mientras tanto, las personas pueden elegir otro modelo en la sesión.
• El pod se mata a mitad del drenaje: aumente terminationGracePeriodSeconds al menos al valor que el runner registra al inicio. Consulte Shutdown timing.

​

Cuando el runner se cierra

• Una salida normal: el runner terminó sus sesiones y se drenó, alcanzó su tiempo de jubilación, o se le indicó que se detuviera. Reinícielo para que el entorno tenga capacidad nuevamente. Runner lifecycle describe estas salidas.
• Un inicio fallido: el runner no puede iniciarse con la configuración o el host que se le proporcionó, por lo que se cierra segundos después de que comienza, y se cierra de la misma manera cada vez que lo reinicia. Reiniciarlo más rápido no ayuda. Alguien necesita leer su salida y corregir la causa.
• Pérdida de contacto: un runner que no puede comunicarse con Anthropic durante más tiempo que su lease, por ejemplo mientras su host está suspendido, puede ser eliminado del entorno. Cuando un runner eliminado se reconecta, se cierra. Su registro puede mostrar una línea [runner:fatal] que contiene runner record gone server-side o, tras una interrupción más larga, poll auth failed. El runner no vuelve a registrarse por sí solo, así que reinícialo.

​

Reconocer un inicio fallido

[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

• Sin línea en absoluto: un runner que el host mata no imprime ninguno. Si la salida termina sin línea [runner:fatal] y sin línea error:, verifique si el host u su orquestador detuvo el proceso, por ejemplo por exceder un límite de memoria.
• El código de salida: el runner no reserva un código de salida para errores que se repiten en cada inicio. Se cierra con el mismo código para un error de configuración, como una combinación no compatible de banderas, y para una falla que puede aclararse por sí sola, como que la API permanezca inalcanzable a través de los propios reintentos del runner. Base la decisión de esperar más tiempo en qué tan pronto se cerró el runner, y lea la salida del runner para aprender por qué.
• Un entorno que se ve saludable: algunos pasos de inicio se ejecutan después de que el runner se registra con su entorno, como --configure-git y la configuración de credenciales del proxy de git de Anthropic. Si uno de esos pasos falla, el entorno puede seguir listando ese runner durante algunos minutos después de que el proceso haya salido, y la página Cloud environments puede leer Healthy mientras ningún runner está recogiendo trabajo. Si las sesiones permanecen en cola en un entorno que se ve saludable, verifique si su supervisor está reiniciando el runner.

​

Reiniciar con una espera que crece

• Kubernetes: el Deployment en esta página no necesita cambios. Después de que un contenedor se cierra, el kubelet por defecto espera antes de reiniciar el contenedor, y la espera crece en cada reinicio hasta un techo. La espera comienza de nuevo una vez que el contenedor ha estado ejecutándose durante un tiempo sin cerrarse. El kubelet aplica la misma espera después de una salida normal cuando el contenedor se ejecutó solo brevemente. Un runner que se drena a menudo puede por lo tanto mostrar el estado CrashLoopBackOff también, así que lea la salida antes de concluir que el runner no puede iniciarse. El comando a continuación lee la salida de la última ejecución de un pod del Deployment:
  kubectl logs --previous -n claude-runners deploy/claude-runner
  
  Cuando la última ejecución fue un inicio fallido, la línea [runner:fatal] o error: está entre las últimas líneas de la salida. Para leer la última ejecución de otro pod, nombre ese pod en lugar de deploy/claude-runner.
• Docker y Docker Compose: la receta Compose en esta página no necesita cambios. Con restart: always, Docker espera más tiempo antes de cada reinicio de un contenedor que sigue cerrándose, hasta un techo. Reemplace <container> con el nombre del contenedor en el comando a continuación, que lee cuántas veces Docker ha reiniciado el contenedor:
  docker inspect --format '{{.RestartCount}}' <container>
  
  El comando imprime un número. Un número que sigue aumentando significa que Docker sigue reiniciando el runner.
• Una unidad systemd: por defecto systemd espera el mismo RestartSec antes de cada reinicio y no lo alarga, así que una unidad con Restart=always reinicia un runner que no puede iniciarse en ese mismo intervalo cada vez. Cuando los inicios vienen lo suficientemente rápido como para alcanzar el límite de velocidad de inicio de la unidad, cinco inicios en 10 segundos por defecto, systemd deja de reiniciar la unidad. La unidad permanece detenida hasta que alguien la inicie de nuevo, lo que systemd permite una vez que el intervalo del límite de velocidad ha pasado o después de systemctl reset-failed. Porque RestartSec se aplica a cada reinicio, un valor más largo también retrasa el reinicio después de una salida normal. Elija un valor que equilibre los dos, y alerte sobre el recuento de reinicio de la unidad.
• Un bucle de shell o su propio supervisor: aplique la misma regla usted mismo. Comience con una espera de cinco segundos. Después de cada ejecución que terminó dentro de un minuto, duplique la espera para el siguiente reinicio, hasta cinco minutos. Después de una ejecución que duró un minuto o más, vuelva a cinco segundos.

​

Verificar por qué el runner sigue cerrándose

• La última línea [runner:fatal] o error:: dice por qué se detuvo el runner. Solución de problemas enumera las causas comunes.
• La combinación de banderas: el proxy de git de Anthropic requiere --capacity 1. Las recetas en esta página usan una capacidad más alta, así que bájela cuando agregue el proxy a una de ellas.
• Lo que el servicio de su entorno puede alcanzar: si el runner comienza a mano y falla bajo su supervisor, compare el usuario, el directorio de inicio, el PATH, y el límite de memoria. --configure-git y el proxy de git de Anthropic necesitan git en el PATH y un ~/.gitconfig escribible.
• El secreto del entorno: si revocó el secreto o lo escribió mal, el runner imprime una línea que contiene RegisterRunner auth failed.
• La pestaña Activity del entorno: abra el entorno y seleccione Activity. Si nuevos runners siguen apareciendo allí y ninguno recoge trabajo, su supervisor está reiniciando el runner.

​

Una sesión se recoge, pero Claude nunca responde su primer mensaje

GET https://api.anthropic.com/v1/code/sessions/<session-id>/worker/events/stream

• No almacenes la respuesta en búfer: déjala pasar a medida que llega. Su tipo de contenido es text/event-stream.
• Deja que la respuesta permanezca abierta: puede permanecer abierta hasta una hora. Si el proxy tiene un tiempo de espera por inactividad, mantenlo muy por encima de 15 segundos, porque Anthropic envía un keep-alive al menos con esa frecuencia por defecto.

​

Confirmar la causa en el registro del runner

1. Espera a que transcurra --startup-timeout-min, 15 minutos por defecto. El runner entonces detiene la sesión y registra una línea que contiene no child output for y termina en — releasing.
2. Busca SDKStartup: SSE en el registro del runner. Estas líneas siguen a una línea finished: interrupted, unas líneas después de la del paso 1. La mayoría no tiene marca de tiempo, así que un recolector de registros puede mostrarlas en otro lugar.
3. Busca la línea en esta tabla:

​

Evitar que la sesión lo vuelva a intentar

​

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