Implantar ambientes auto-hospedados em produção

​

Endurecimento de sua implantação

• Contêineres efêmeros por sessão: execute cada processo runner em um contêiner ou VM fresco que é destruído quando o processo sai, com --capacity 1 e o padrão --drain-grace-sec 0 para que cada contêiner sirva exatamente uma sessão. Em uma capacidade mais alta, ou com uma graça de drenagem positiva, um contêiner serve múltiplas sessões do mesmo owner bloqueado; consulte Ciclo de vida do Runner. Não reutilize um sistema de arquivos entre reinicializações do runner, exceto na configuração deliberada de checkout pré-aquecido, e nunca entre owners.
  • Quando o runner interrompe uma sessão, ele não envia nenhum sinal para um processo que ainda esteja em execução depois que seu comando shell foi encerrado, como um serviço que foi daemonizado. Destruir o contêiner ou a VM encerra esse processo.
• Sem credenciais amplas na imagem: não inclua chaves SSH de longa duração, credenciais de provedor de nuvem ou tokens de acesso pessoal que concedem mais do que uma sessão precisa. Crie credenciais usadas durante uma sessão, como tokens de push ou API, por sessão a partir de seu script wrapper. O clone inicial acontece antes do wrapper ser executado, então trate-o com um hook de ciclo de vida checkout, ou com --use-anthropic-git-proxy quando todos os repositórios de uma sessão estiverem no github.com. Para ambos, consulte Configurar git.
• Mantenha as credenciais GitHub do host longe das sessões: Claude pode usar qualquer credencial GitHub que uma sessão consiga ler, com qualquer acesso que essa credencial conceda. Mantenha as próprias credenciais GitHub de escopo amplo do host runner fora de qualquer coisa que uma sessão possa ler. Tal credencial pode ser um token de acesso pessoal, o token que gh auth login salva para sua conta, ou um GH_TOKEN no ambiente do runner.
  • Com git gerenciado pela Anthropic: com tal credencial, Claude acessa o GitHub diretamente em vez de passar pelo git gerenciado pela Anthropic.
  • Sem git gerenciado pela Anthropic: uma credencial de clone pode permanecer na imagem se você restringir seu escopo tanto quanto Incluir a configuração do git em sua imagem descreve.
• Mantenha o segredo do ambiente fora dos hosts que executam sessões: o segredo do ambiente pode registrar runners e pegar qualquer sessão enfileirada no ambiente. Em uma frota fixa, ele vive em cada host runner, onde o código de qualquer sessão pode ler o arquivo secreto. Prefira runners sob demanda, onde o segredo fica no host do orquestrador, que nunca executa código do usuário, e cada runner recebe uma ordem de trabalho de uso único que registra exatamente um runner. Em uma frota fixa, trate o arquivo environment-secret como legível por cada sessão e gire o segredo após qualquer suspeita de comprometimento de sessão.
• Saída de rede padrão-negar: restrinja o tráfego de saída do contêiner runner e sessão no seu próprio limite de rede em cada ambiente; Saída padrão-negar cobre o que permitir e por quê.
• IAM de host com privilégio mínimo: a identidade de computação anexada ao host runner, como um perfil de instância ou conta de serviço de nó, deve conceder apenas o que o próprio runner precisa. As sessões devem obter suas próprias credenciais através de seu script wrapper em vez de herdar a do host.
• Bloqueie o endpoint de metadados da nuvem das sessões: manter as sessões fora da identidade do host requer bloquear seu acesso ao endpoint de metadados, e as políticas de saída no nível de sub-rede não interceptam o tráfego de metadados link-local, então bloqueie-o no próprio contêiner:
  • IMDSv2 com um limite de salto de um
  • GKE Workload Identity com ocultação de metadados
  • Uma negação explícita para 169.254.169.254 no namespace de rede do contêiner da sessão
  O bloqueio se aplica ao seu script wrapper e hooks de ciclo de vida também, já que compartilham o contêiner. Autentique qualquer troca de token com o JWT da sessão contra seu próprio serviço de token sobre saída na lista de permissões, ou use uma identidade web baseada em arquivo, como IAM Roles for Service Accounts (IRSA) no Amazon EKS.
• Isolamento de sistema de arquivos por runner: cada processo runner obtém seu próprio diretório de trabalho que nenhum outro processo no host pode ler ou escrever. Faça --hooks-dir, o script wrapper, e o ~/.claude/ do host somente leitura para a sessão, seja construído na imagem ou montado como somente leitura.
• Dispatch não tem controle de acesso por ambiente: qualquer membro de sua organização Anthropic pode enviar uma sessão para qualquer um de seus ambientes. Se um Owner rotear canais Claude Tag para o ambiente, qualquer pessoa que a configuração de acesso Claude Tag admita pode iniciar sessões de canal que são executadas lá. Por padrão, isso é qualquer pessoa no workspace Slack conectado, com ou sem uma conta Claude. Trate cada host runner como alcançável para execução de código por todos que podem enviar para ele, e coloque no host runner apenas dados e credenciais que todas essas pessoas têm permissão para ler. --lock-to-account limita qual conta as sessões de um determinado host executam, mas não reduz quem pode enviar para o ambiente. Para tornar ambientes auto-hospedados a única opção de seletor, um Owner pode ocultar ambientes hospedados pela Anthropic para toda a organização na página Cloud environments.
• Enforce the repo-settings guard: escolha o modo de guard com --confine-repo-settings. O padrão warn registra uma violação e ainda assim gera a sessão, enforce recusa a sessão, e off desabilita a varredura. O runner verifica as configurações confirmadas de cada repositório para:
  • Uma concessão que se resolve fora do workspace da própria sessão: uma entrada additionalDirectories, uma regra Edit, Write, ou NotebookEdit em permissions.allow, ou uma entrada sandbox.filesystem.allowWrite ou allowRead
  • Um bloco env não vazio
  • Uma substituição de postura do operador, como sandbox.enabled: false
  O guard é executado independentemente de --trust-workspace, e não cobre hooks de repositório, .mcp.json, ou regras Bash; consulte Permissões e aprovação de ferramentas para onde essas concessões pertencem.

​

Requisitos de rede

• statsig.anthropic.com, *.sentry.io, claude.ai e platform.claude.com: esses hosts aparecem em algumas listas de verificação de rede corporativa mais antigas, mas o runner não os alcança. As buscas de sinalizadores de recursos vão para api.anthropic.com, e o runner se autentica com o segredo do ambiente em vez de OAuth interativo.
• mcp-proxy.anthropic.com: sessões auto-hospedadas não o usam. Quando a entrega de conectores está habilitada para sua organização, os conectores claude.ai de sua organização alcançam as sessões através de api.anthropic.com. Consulte Servidores MCP.

• O instalador de uma linha: busca install.sh de claude.ai no tempo de instalação.
• claude auth login interativo: faz login através de claude.ai, claude.com e platform.claude.com. A configuração guiada, o modo com login do doctor e o dispatch de CI o usam. O navegador com o qual você faz login também carrega as verificações de navegador da página de login do claude.ai a partir de hcaptcha.com, *.hcaptcha.com e challenges.cloudflare.com. Se sua organização usa login único, esse navegador também pode ser redirecionado através de sso.claude.com.

​

Saída padrão-negar

​

Autenticar em um proxy de saída

​

Escolha de onde o valor Proxy-Authorization vem

• --proxy-authorization-command <command>: escolha isso para um token que você gera sob demanda. O runner executa o comando shell e usa sua stdout aparada como o valor do cabeçalho, por exemplo Bearer <token>.
• --proxy-authorization-file <path>: escolha isso para um token que outro processo gira no lugar. O runner lê o arquivo e usa seu conteúdo aparado como o valor do cabeçalho.

​

Configurações que o runner se recusa a iniciar com

• Ambos os sinalizadores definidos: um sinalizador mais a variável de ambiente do outro sinalizador conta como definir ambos.
• Nenhuma URL de proxy: nem HTTPS_PROXY nem HTTP_PROXY contém uma URL http:// ou https://. O runner lê ambas as variáveis em maiúsculas ou minúsculas, e não consulta ALL_PROXY.
• Qualquer sinalizador passado para o subcomando orquestrador: self-hosted-runner orchestrator não aceita os sinalizadores ou suas variáveis de ambiente. Passe o sinalizador para cada runner que o orquestrador inicia em vez disso.

​

O que o runner muda enquanto um sinalizador de autorização de proxy está definido

• Listener: o listener é um proxy direto em 127.0.0.1. O runner inicia o listener antes de se registrar no plano de controle, e sai na inicialização se o listener não puder iniciar.
• Variáveis de proxy: o runner reescreve qual de HTTPS_PROXY e HTTP_PROXY você definiu para que aponte para o listener. Esse valor reescrito alcança o próprio runner, seus hooks de ciclo de vida, e cada sessão que ele executa.
• Rotação de token: um token girado entra em vigor sem uma reinicialização. Para cada conexão que o listener abre para seu proxy, o runner executa seu comando ou lê seu arquivo novamente e adiciona o resultado como o cabeçalho.
• Ambiente da sessão: uma sessão alcança seu proxy apenas através do listener. No ambiente de cada sessão, o runner remove ALL_PROXY, remove qualquer grafia de HTTPS_PROXY ou HTTP_PROXY que você não definiu, e fixa NO_PROXY ao próprio valor do runner.
• Logs: o runner nunca registra o valor do cabeçalho.

​

Configurar git

• Deixe o runner configurar git: inicie o runner com --configure-git para que ele escreva a mesma identidade e configuração de assinatura de commit que as sessões hospedadas pela Anthropic usam
• Envie configuração git em sua imagem: defina identidade e credenciais de push você mesmo, por exemplo para fazer commit sob sua própria identidade de bot

​

Deixe o runner configurar git

• user.name = Claude e user.email = noreply@anthropic.com, correspondendo às sessões hospedadas pela Anthropic
• Assinatura de commit e tag em formato SSH, roteada através de um shim gerenciado pelo runner que assina cada commit através do serviço de assinatura da Anthropic usando as credenciais da própria sessão. As assinaturas são verificáveis no GitHub contra a chave de assinatura SSH publicada da Anthropic.
• push.negotiate = true, para que git pergunte ao seu host git quais commits ele já possui antes de empacotar um push. Requer Claude Code v2.1.257 ou posterior.
• core.hooksPath apontando para um diretório de hooks gerenciado pelo runner. Seus hooks commit-msg e prepare-commit-msg adicionam um trailer Co-authored-by: para o criador da sessão a cada commit. O trailer é construído a partir do email em CCR_SESSION_ACCOUNT_EMAIL e omitido quando essa variável não está definida. Se sua imagem já define core.hooksPath e o runner não usa git gerenciada pela Anthropic, o runner mantém sua configuração, pula a instalação desses hooks e imprime um aviso [runner:git].

​

Envie configuração git em sua imagem

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

• Uma chave de implantação SSH limitada a um repositório com uma reescrita url.<base>.insteadOf
• Um credential.helper que retorna um token com escopo mínimo
• GIT_SSH_COMMAND apontando para uma chave com escopo restrito

• O runner define GIT_TERMINAL_PROMPT=0, para que git não peça um nome de usuário ou senha.
• O runner executa SSH com BatchMode=yes, anexado ao seu GIT_SSH_COMMAND se você definir um, para que SSH não peça uma frase-passe ou confirmação de host.
• O runner define GCM_INTERACTIVE=never, para que Git Credential Manager não abra um diálogo de login.
• O runner limpa core.askPass, então se você usar um helper askpass, defina-o através da variável de ambiente GIT_ASKPASS em vez disso.

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

​

Use o proxy git da Anthropic

• Somente github.com: a Anthropic serve uma sessão apenas quando todos os seus repositórios estão em github.com, e o proxy git ainda não suporta GitHub Enterprise Server. Em um runner com o proxy git, uma sessão com um repositório em outro host git falha ao iniciar.
• Credenciais somente para os repositórios da sessão: a Anthropic fornece credenciais git para os repositórios que fazem parte da sessão, não para outros repositórios no mesmo host git. Um submódulo privado, uma dependência que seu gerenciador de pacotes busca com git ou um marketplace de plugins em outro repositório não recebe nenhuma credencial da Anthropic. Peça às pessoas que criam sessões que adicionem todos os repositórios de que uma sessão precisa ao criá-la. Cada execução de uma tarefa agendada na nuvem é uma sessão com os repositórios da tarefa, então peça ao proprietário de cada tarefa que adicione todos os repositórios de que suas execuções precisam.
• Somente pushes de branch: um push que exclui um branch falha, assim como um push para qualquer outro tipo de ref, como uma tag. Para saber quais branches um push pode atualizar, consulte Proxy do GitHub.
• Contas do GitHub conectadas: peça a cada pessoa que cria sessões de usuário com um repositório que conecte o GitHub. Sem a própria conexão, essas sessões não iniciam.
• --capacity 1: o proxy git requer uma sessão por processo runner, então execute mais réplicas para paralelismo. Ative o proxy git da Anthropic lista os requisitos.
• Configuração git global substituída: o runner exclui e substitui a configuração git global do usuário com o qual é executado. Execute-o como um usuário dedicado ou em um contêiner.
• Credenciais do host para pushes do host: o push de --push-outcome-on-release do runner e qualquer push que seu hook post-session faça ainda usam as próprias credenciais git do host runner e seu caminho de rede até github.com. Mantenha essas credenciais fora da configuração git global e consulte Envie configuração git em sua imagem para ver formas de fornecê-las.
• Decisão por sessão: a Anthropic decide, para cada sessão no runner, se serve o git dela, e uma sessão que ela não serve falha ao iniciar. Quando as sessões falham ao iniciar em um runner com o proxy git cobre as causas.

​

Ative o proxy git da Anthropic

• Claude Code v2.1.267 ou posterior: versões anteriores aceitam a flag, mas não relatam a solicitação para que a Anthropic sirva o git nem imprimem a linha Registering as opted in, então a Anthropic não serve suas sessões.
• --capacity 1, o padrão: cada processo runner lida com uma sessão por vez, então execute mais réplicas para paralelismo.
• Git 2.32 ou mais recente: git mais antigo ignora a configuração git por sessão que o runner prepara para o proxy git.

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

​

Como a Anthropic serve git para uma sessão

• Sessões de usuário: a Anthropic usa o token OAuth do GitHub armazenado para o criador da sessão.
• Sessões de bot e agente: a Anthropic usa o token de instalação do GitHub App de sua organização.
• Reescritas de URL: --git-host-rewrite e --git-ssh-rewrite não têm efeito em um repositório que o proxy git serve.

​

Quando as sessões falham ao iniciar em um runner com o proxy git

• Nem governed git ACTIVE nem a linha withheld: um runner anterior ao Claude Code v2.1.267 não registra nenhuma das linhas, e a Anthropic não serve suas sessões. Atualize o runner para a v2.1.267 ou posterior seguindo Fixe a versão.
• A linha withheld: a Anthropic não serviu a sessão. Um runner que funcionava antes com o proxy git pode falhar dessa forma sem nenhuma mudança do seu lado.
  • Um repositório não está em github.com: uma sessão com mesmo um único repositório em outro host git, como GitHub Enterprise Server, não é servida, incluindo seus repositórios em github.com. Desative o proxy git da Anthropic para os runners desse ambiente.
  • Todos os repositórios estão em github.com: relate a falha à sua equipe de conta da Anthropic com o ID da sessão da linha withheld. A Anthropic registra o motivo do lado dela.
• Uma linha contendo remote: access denied by the git proxy: uma sessão que a Anthropic serve ainda pode ser recusada, por exemplo quando a política da organização nega acesso git para a sessão, ou a sessão não está autorizada para o repositório. O log do runner então mostra uma linha contendo remote: access denied by the git proxy, e o restante dessa linha diz o motivo.
• GitHub authentication required: isso aparece quando o criador da sessão não tem uma conexão funcional com o GitHub em claude.ai. O clone da sessão falha, e o erro git contém GitHub authentication required. Please reconnect your GitHub account. Peça a essa pessoa que conecte ou reconecte o GitHub nas configurações do claude.ai.

​

Desative o proxy git da Anthropic

unset CLAUDE_RUNNER_USE_GIT_PROXY

​

Acesso à API do GitHub sem o GitHub CLI

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

• Credenciais: o gh integrado envia suas requisições REST através da git gerenciada pela Anthropic, que fornece a credencial do GitHub do lado da Anthropic, então a imagem não precisa de nenhum token do GitHub para ele
• Quais sessões o recebem: a Anthropic decide por sessão se a git gerenciada pela Anthropic atende o gh da sessão. Quando atende, a linha [runner:session] governed git ACTIVE que o runner registra para a sessão mostra gh_path_shim=true. Quando não atende, a sessão não tem gh
• jq: instale jq na imagem se você quiser que --jq funcione
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: se o ambiente da sessão a define, o Claude Code não fornece o gh integrado, e a sessão não tem gh

​

Confie em uma autoridade de certificado privada com git gerenciada pela Anthropic

• Armazenamento de certificado do sistema: instale sua CA no armazenamento de certificado do sistema do host runner, e git confia nela sem nenhuma variável.
• GIT_SSL_CAINFO: defina-a para um arquivo PEM de suas CAs, por exemplo GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem.
• GIT_SSL_NO_VERIFY: não ajuda atrás de um proxy de re-assinatura. O clone do runner através de git gerenciada pela Anthropic verifica certificados mesmo quando a variável está definida, então esse clone falha até que git confie em sua CA através de uma das outras duas abordagens.

• GIT_SSL_CAINFO: o que git verifica git gerenciada pela Anthropic depende de onde git é executado:
  • Clone e fetches do runner: executados sem a variável e verificam git gerenciada pela Anthropic contra um arquivo de certificado por sessão que o runner escreve. O runner constrói esse arquivo a partir do pacote de CA do sistema do host runner e dos certificados do seu arquivo.
  • Git dentro da sessão: obtém configuração http.sslCAInfo nomeando seu arquivo no lugar da variável, mais entradas http.<url>.sslCAInfo que verificam git gerenciada pela Anthropic contra o arquivo por sessão.
  • Hooks checkout e post-session: herdam a variável inalterada.
• GIT_SSL_NO_VERIFY: quais verificações de certificado permanecem desligadas depende de onde git é executado:
  • Clone e fetches do runner: executados sem a variável e verificam o certificado que lhes é apresentado.
  • Git dentro da sessão: obtém configuração http.sslVerify=false no lugar da variável, então as verificações permanecem desligadas para outros hosts. Ele também obtém entradas http.<url>.sslVerify=true que mantêm as verificações ligadas para git gerenciada pela Anthropic.
  • Hooks checkout e post-session: quando a sessão tem um repositório em git gerenciada pela Anthropic, obtêm configuração http.sslVerify=false no lugar da variável. Eles também obtêm entradas http.<url>.sslVerify=true que mantêm as verificações ligadas para git gerenciada pela Anthropic.

​

Adicione repositórios do github.com a sessões de canal do Claude Tag

​

Reescrever URLs git para redes privadas

• --git-host-rewrite <from>=<to>: para DNS de horizonte dividido, onde a Anthropic alcança seu host git através de um nome do host externo, mas runners devem usar um interno
• --git-ssh-rewrite <host>: para hosts git que apenas aceitam SSH, ou um host runner que tem apenas uma chave SSH. Por exemplo, para clonar repositórios do github.com via SSH, adicione --git-ssh-rewrite github.com ao comando do runner. O runner então reescreve https://github.com/owner/repo para git@github.com:owner/repo. O SSH deve conectar sem um prompt.

​

Construir a imagem do 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 .

​

Dimensionar CPU e memória para sessões

• Memória: uma requisição e um limite de 4 GiB cada, que atende ao mínimo de 4 GB nos requisitos do sistema do Claude Code. Mantenha os dois iguais para que o agendador contabilize a memória completa do contêiner. Quando o contêiner atinge seu limite de memória, o kernel mata processos dentro dele, o que pode encerrar uma sessão no meio da tarefa.
• CPU: uma requisição de 2 CPUs e um limite de 4 CPUs, para que uma sessão possa explodir acima da requisição durante builds. O kernel limita um contêiner em seu limite de CPU em vez de matar processos nele, então sessões no limite são executadas mais lentamente, mas continuam sendo executadas.

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

• Uma sessão por runner: dê a cada contêiner os valores de uma sessão. Use este dimensionamento em --capacity 1, que a seção de endurecimento recomenda, e para runners sob demanda, onde você define os valores na carga de trabalho que seu hook spawn-runner submete, como um modelo de pod de um Kubernetes Job.
• Várias sessões por runner: em um --capacity acima de um, multiplique os valores de uma sessão pela capacidade, porque até muitas sessões podem ser executadas no contêiner ao mesmo tempo. As receitas Kubernetes e Docker Compose executam --capacity 4 sem limites de CPU ou memória, então adicione limites dimensionados para a capacidade que você executa.
• Vários contêineres de runner em um host: dimensione o host para a soma das capacidades dos runners, porque cada runner conta apenas suas próprias sessões em relação ao --capacity:
  • Memória: multiplique a memória de uma sessão pela soma e, em seguida, adicione o que os próprios processos do host usam
  • CPU: multiplique a requisição de CPU de uma sessão pela soma. Para permitir que todas as sessões explodam ao mesmo tempo, multiplique o limite de CPU em vez disso.
  Dê a cada runner seu próprio contêiner. Use o mesmo caminho --base-dir em cada um, em um armazenamento que nenhum outro contêiner de runner monte, para que cada runner tenha seu próprio diretório de trabalho.

​

Dar a cada sessão seu próprio limite de memória

• Em um contêiner: execute um runner por contêiner e defina o limite de memória do contêiner, como limits.memory no Kubernetes, --memory no Docker ou mem_limit em um arquivo Compose. Mantenha a soma dos limites dos contêineres abaixo da memória do host, porque quando o próprio host fica sem memória, o kernel pode matar processos em qualquer lugar do host.
• Sob systemd sem contêiner: defina MemoryMax na unit do runner e execute um runner por host, porque runners que usam o mesmo --base-dir em um sistema de arquivos compartilham os repositórios clonados ali. Por exemplo, em --capacity 1 sem hook checkout, as sessões deles em um repositório podem trabalhar no mesmo checkout ao mesmo tempo. Para executar vários runners em um host, dê a cada um deles um contêiner.

​

Deixar espaço sob os limites de processos e threads

​

Onde definir cada limite

​

Medir o pico de uma sessão

​

Verificar um limite pids.max

• Verifique se pids.max foi atingido: pesquise no log do kernel do host, por exemplo com dmesg, uma linha que contenha cgroup: fork rejected by pids controller in e o caminho de um cgroup. O kernel a registra em log apenas na primeira vez que recusa um processo ou thread nesse cgroup, então pesquise o log inteiro.
• Veja o limite em vigor: leia pids.max no diretório cgroup do runner e em cada diretório acima dele. O menor valor é o limite em vigor, e max significa nenhum limite nesse nível.

​

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

​

Tempo de encerramento

1. O runner aguarda até --drain-wait-sec segundos, 0 por padrão, para que os turnos ainda em andamento sejam concluídos.
2. Ele encerra a árvore de processos de cada sessão, incluindo qualquer comando que Claude ainda estava executando, mas não um processo ainda em execução após o término do seu comando de shell.
3. Ele executa o hook de ciclo de vida post-session.

• --drain-wait-sec para a etapa 1, 0 segundos por padrão
• --session-stop-grace-sec para a etapa 2, 5 segundos por padrão
• --post-session-hook-timeout-sec para a etapa 3, 60 segundos por padrão
• Uma margem fixa de 15 segundos
• Mais 30 segundos quando --push-outcome-on-release está definido

• Com --retire-at: deixe tempo suficiente entre o tempo de aposentadoria e o tempo de parada do host para que turnos típicos sejam concluídos, mais a espera por tarefas em segundo plano que Ciclo de vida do Runner descreve, mais o tempo registrado. Calcule o tempo de aposentadoria em cada inicialização, por exemplo date +%s mais o tempo de vida pretendido do runner.
• Com --defer-shutdown-max-min: o timeout de parada também deve cobrir os minutos que você configura e uma espera adicional antes do início da drenagem, 75 segundos nas configurações padrão. Adiar a drenagem após o primeiro sinal explica ambos. O runner também registra esse tempo maior na inicialização.

​

Permitir que os turnos em andamento terminem antes de uma reinicialização

• --drain-wait-sec: aproximadamente a duração dos turnos e das tarefas em segundo plano que você deseja permitir que terminem. É um máximo: a espera termina antes se eles terminarem primeiro.
• Seu timeout de parada: terminationGracePeriodSeconds no Kubernetes, stop_grace_period no Docker Compose. Por exemplo, com --drain-wait-sec 120, substitua o 90 na receita do Kubernetes ou do Docker Compose por 200.
• Se você alterou outras configurações de encerramento: os 80 segundos são para as configurações padrão. Inicie um runner com suas flags e use pelo menos o número na linha de inicialização This runner needs up to, que inclui a espera. Com --defer-shutdown-max-min definido, use o número maior na linha de inicialização seguinte, após Size the stop timeout to at least. Tempo de encerramento lista o que aumenta esses números.

​

Publicar uma mensagem de status antes de uma reinicialização

​

Adiar a drenagem após o primeiro sinal

​

O que acontece com as sessões que o runner mantém após o primeiro sinal

• Pelos primeiros n minutos: o runner serve suas sessões normalmente e continua aplicando --startup-timeout-min e --kill-session-after-min. Se você também definir --release-idle-session-min, o runner libera qualquer sessão cujo usuário tenha estado ocioso por esse tempo; sem isso, as sessões ociosas permanecem no runner.
• Quando os n minutos se esgotam: o runner libera todas as sessões que ainda mantém, ociosas ou não. O runner aguarda o término do turno de uma sessão no meio do turno e até 60 segundos adicionais para as tarefas de fundo de um turno, antes de liberar essa sessão.
• Quando a carência pós-lançamento se esgota: o runner drena todas as sessões que ainda mantém, e o plano de controle recoloca cada sessão drenada na fila para outro runner imediatamente. A carência pós-lançamento começa quando os n minutos se esgotam e é 75 segundos nos padrões. Se você definir --drain-wait-sec acima de 60 segundos, a carência pós-lançamento será --drain-wait-sec mais 15 segundos.

​

Dimensionar o tempo limite de parada

​

O que atinge um hook post-session em execução

• Um SIGTERM enquanto o runner já está drenando: força a saída do runner imediatamente, pulando o que resta da drenagem. Sem --defer-shutdown-max-min, esse é o segundo SIGTERM que o runner recebe. Nada sinaliza um hook post-session em execução no meio, portanto em um host simples onde um processo init adota órfãos, ele termina por conta própria, mas sem supervisão: seu orçamento de timeout não se aplica mais, e uma escrita no pipe de log fechado pode matá-lo com SIGPIPE, portanto um hook que precisa sobreviver a uma saída forçada lá deve redirecionar sua própria saída para um arquivo. Nas receitas de contêiner nesta página, o runner é o PID 1 do contêiner e sua saída encerra o contêiner, e sob o padrão KillMode=control-group do systemd, a morte em nível de cgroup atinge o hook também, conforme a entrada Cgroup-wide kills descreve; em ambos, trate uma saída forçada como fatal para o hook e confie no período de carência.
• Sinais em nível de grupo de processos, como kill -- -<pid> em um script wrapper, controle de trabalho de shell ou um watchdog em nível de grupo: alcançam o runner e um subprocesso de hook checkout no meio, que permanece anexado ao grupo deliberadamente, mas não um hook post-session em execução no meio ou o filho da sessão.
• Mortes em nível de cgroup, como o padrão KillMode=control-group do systemd ou o SIGKILL que o Kubernetes entrega para todo o contêiner quando terminationGracePeriodSeconds expira: alcançam tudo, incluindo o hook. O isolamento de grupo de processos não protege contra esses, razão pela qual o período de carência deve cobrir a drenagem completa.
• O tempo limite próprio do hook: quando um hook excede --post-session-hook-timeout-sec, o runner envia SIGTERM para todo o grupo de processos do hook, depois SIGKILL dois segundos depois, portanto um worker que o hook bifurcou, como tar, rsync ou git, termina com o shell wrapper em vez de sobreviver como um órfão. A supervisão do runner termina uma vez que o stdio do hook fecha: um worker que redirecionou sua própria saída para um arquivo e sobrevive ao estágio SIGTERM está além do alcance do runner.

​

Mantenha o diretório base e a capacidade idênticos entre runners

​

Reuse a pre-warmed checkout

• Em --capacity 1: o runner busca a ref solicitada, destaca HEAD e redefine duramente para ela, o que é quase instantâneo quando pouco mudou.
• Em um --capacity acima de um: o runner busca nesse clone e, em seguida, faz o checkout de um worktree separado a partir dele para cada sessão. Um clone pré-aquecido economiza o download, mas não o checkout.

• Clone na imagem: construa o clone em sua imagem de runner naquele caminho. Cada contêiner fresco então começa com o clone quente sem reutilizar um disco.
• Clone em um volume persistente: em runners que você pré-bloqueia para a conta de um usuário com --lock-to-account, aponte --base-dir para um volume persistente, para que o disco apenas sirva essa conta. Um runner pré-bloqueado nunca pega sessões de canal Claude Tag, então essa opção não se aplica a runners que as servem.

• Profundidade do clone: crie o clone sem --depth, com ou sem --single-branch. O runner nunca passa --depth ao buscar em um clone com um remote origin, mesmo que você defina CLAUDE_RUNNER_FETCH_DEPTH. Com um clone completo, cada sessão baixa apenas os commits que faltam ao clone. Com um clone raso, uma sessão em um branch que divergiu antes do commit mais antigo do clone baixa todo o histórico desse branch.
• Mudanças rastreadas redefinem, arquivos não rastreados persistem: em --capacity 1, cada sessão começa a partir de uma redefinição dura que limpa as modificações rastreadas da sessão anterior, mas o runner nunca executa git clean, então arquivos não rastreados das sessões anteriores do owner bloqueado permanecem na árvore.
• Diretórios por sessão também persistem: ao lado do checkout, o runner cria entradas por sessão sob <base-dir>/_sessions/ para cada sessão que executa. O diretório de configuração Claude da sessão contém uma cópia local da transcrição da conversa. Ao lado dele ficam os arquivos carregados da sessão, quando a sessão tem algum. O diretório da sessão também fica lá: ele contém quaisquer worktrees por sessão e checkouts do hook checkout enquanto a sessão é executada, e mantém tudo mais que Claude escreveu nele. Por padrão, o runner deixa esses em vigor quando a sessão termina, então em um disco que sobrevive ao processo do runner eles se acumulam. Cada sessão é executada como o próprio usuário do runner, então qualquer sessão posterior que o disco servir pode lê-los. Se você manter um --base-dir persistente, dimensione o volume para esse crescimento. O mesmo se aplica a qualquer configuração que reinicie o runner no mesmo sistema de arquivos, incluindo a receita Docker Compose.
• Com --remove-session-state, diretórios por sessão não persistem: inicie o runner com --remove-session-state para que ele delete os diretórios por sessão de cada sessão conforme a sessão termina. A exclusão é do melhor esforço: os diretórios permanecem quando o runner é morto antes de sua limpeza ser executada. O clone canônico e arquivos que uma sessão escreveu em outro lugar no host, como o diretório temporário, permanecem independentemente.
• Com o proxy git, a redefinição se torna um checkout: com --use-anthropic-git-proxy, o runner sanitiza o .git/ do clone antes de cada sessão. Ele mantém o armazenamento de objetos e o estado raso, e deleta o índice. Sem o índice, cada sessão começa com um checkout completo do diretório de trabalho em vez de uma redefinição quase instantânea. O runner ainda busca no clone existente em vez de clonar o repositório novamente. Pré-aquecimentos de submódulo não são suportados sob o proxy.
• Com o proxy git, um pré-aquecimento reftable perde suas refs: quando o runner sanitiza o .git/ antes de cada sessão, ele mantém .git/refs/ e remove o diretório .git/reftable/. Um clone pré-aquecido no formato de ref reftable do git perde suas refs dessa forma, então pré-aqueça o clone no formato de ref files do git.
• Clones longos não precisam de workaround: o runner limita cada operação git com um watchdog de 120 segundos sem progresso e um limite duro de 30 minutos, não um tempo limite fixo, então um clone frio lento que continua relatando progresso é concluído.

​

Confirmar que o runner usa seu clone

​

Pin the version

• Antes de fixar uma versão: verifique as versões do Claude Code que os modelos exigem para cada modelo que suas sessões usam. Se um modelo exigir uma versão mais recente do que aquela que suas sessões executam, o servidor rejeita requisições para esse modelo com Claude Code does not support this model.
• Para manter uma frota em uma versão: construa a imagem com uma versão fixada, ou em um host nu instale uma versão específica e desabilite auto-updates
• Para atualizar uma frota fixa: leia as entradas do changelog entre a sua versão e a que você está instalando, depois instale a versão mais recente ou recrie a imagem e reinicie os runners
• Para atualizar runners sob demanda: leia as entradas do changelog entre a sua versão e a que você está instalando, depois altere a imagem que o seu hook spawn-runner inicia. Cada novo runner recebe a nova versão. Um runner que já está em execução, incluindo um runner de reserva que --min-idle iniciou, mantém sua versão até encerrar. Não o reinicie, porque sua ordem de trabalho é de uso único.
• Se as sessões iniciarem um binário diferente: se você usar --exec-path ou um hook command para iniciar um binário do Claude Code diferente do próprio binário do runner, as sessões executam a versão desse binário. Atualize esse binário quando atualizar o runner.
• Plugins: marketplaces de plugin também não auto-atualizam; defina FORCE_AUTOUPDATE_PLUGINS=1 no ambiente do runner para deixar plugins auto-atualizarem enquanto o binário permanece fixado

​

Scale the fleet

• Frota fixa: execute um conjunto estático de réplicas de runner e dimensione nas métricas Prometheus que cada runner serve
• Runners sob demanda: execute o subcomando claude self-hosted-runner orchestrator, que faz polling na Anthropic para sessões que estão enfileiradas sem runner disponível e invoca seu hook spawn-runner para iniciar um por sessão. Consulte Runners sob demanda.

​

Liberar sessões ociosas em uma frota fixa

• Séries acima desse tempo, como 1800 para 30 minutos: sessões ociosas mantêm esses slots, então defina --release-idle-session-min
• Todas as séries abaixo dele: nenhuma sessão ficou ociosa por tanto tempo. Adicione runners ou defina --kill-session-after-min para sessões que nunca ficam ociosas.
• Um runner sem séries: nenhuma sessão o mantém. Consulte As sessões permanecem enfileiradas em Solução de problemas.
• Um runner cujas métricas não respondem: seu processo pode ter sido encerrado. Consulte Um ambiente que parece saudável em Quando o runner é encerrado.

• Trabalho não enviado: uma sessão liberada é retomada na sua próxima mensagem, sem o trabalho que ela não havia enviado com push. Para manter seus commits, consulte Sessões retomadas perdem trabalho não enviado.
• Encerramento do runner: um runner que libera sua última sessão inicia um encerramento normal. Faça com que seu supervisor o reinicie em um sistema de arquivos novo, conforme descrito em Proteja sua implantação.
• Sessões que nunca ficam ociosas: defina também --kill-session-after-min, porque algumas sessões não contam como ociosas

​

Problemas conhecidos e limitações

​

Tráfego de conector sai de sua rede

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

​

Algumas sessões não contam como ociosas

• Se a sessão está aguardando seu usuário, o runner a libera. Se sua vez terminou e ela mantém apenas tarefas de fundo, o runner aguarda até 60 segundos para que essas tarefas terminem e então a libera. A sessão retoma quando seu usuário envia sua próxima mensagem.
• Se uma vez ainda está em execução, o runner aguarda a vez terminar, ou para a sessão aguardar seu usuário em seguida, e então a libera.
• Se a sessão ainda estiver no runner quando a janela de graça terminar, o runner a encerra, e qualquer trabalho de uma vez em execução é perdido. Uma vez aguardando uma aprovação solicitada de dentro de uma chamada de ferramenta em execução é uma maneira de uma sessão ultrapassar a janela.

​

Limitações adicionais

• Sessões retomadas perdem trabalho não enviado: um runner novo clona o repositório novamente a partir de seu branch inicial, então o trabalho que a sessão não tinha enviado se foi.
  • Para manter trabalho com commit: defina --push-outcome-on-release em todos os runners do ambiente, porque um runner sem a flag retoma a sessão a partir de seu branch inicial. Um runner com a flag faz um push de melhor esforço dos branches de resultado da sessão antes de liberá-la, e a sessão retomada começa a partir desses commits. O push usa as próprias credenciais git do host do runner, inclusive em um runner que usa git gerenciado pela Anthropic.
  • Com um hook checkout: repositórios obtidos por meio de um hook de ciclo de vida checkout não recebem push. Em vez disso, faça um snapshot deles a partir do hook post-session.
  • Antes de habilitar a flag: restrinja quem pode fazer push para refs claude/* no remoto de origem. Na retomada, o runner busca o branch previamente enviado sem verificar quem o enviou.
  • Alterações sem commit ainda são perdidas: para solicitar que Claude faça commit e push quando terminar de responder, consulte Solicitar que as sessões enviem seu trabalho
• Um comando interrompido por um runner perdido pode ser executado novamente: quando a sessão é retomada em outro runner, Claude vê a chamada de ferramenta interrompida com um resultado informando que seu desfecho é desconhecido.
• Um repositório adicionado no meio da sessão pode falhar ao ser clonado: Claude o clona com git clone via HTTPS. Em um runner sem --use-anthropic-git-proxy, o clone falha com um erro de autenticação do git se nada no host puder ler o repositório. Sempre que possível, selecione cada repositório que a sessão precisa quando você a cria.
• Alguns conectores não aparecem em sessões auto-hospedadas: um conector que você ainda não conectou nas Configurações do claude.ai não está listado em uma sessão auto-hospedada, e a sessão não o solicitará para conectar. Conecte-o nas Configurações primeiro, depois inicie uma sessão fresca. Adicionar um conector a uma sessão já em execução também não torna suas ferramentas disponíveis para Claude; inicie uma sessão fresca para pegar um conector recém-adicionado.
• Quando alguém arquiva ou exclui uma sessão, ou libera seu runner a partir do menu da sessão: não conte com o push de --push-outcome-on-release. Para salvar commits nesses casos, faça push de HEAD para um branch de resgate a partir de um hook post-session. Se você partir do exemplo ali, faça-o fazer push mesmo quando não houver nada sem commit, porque ele faz push apenas após um commit de snapshot.

​

Relatar um problema

​

Troubleshooting

claude self-hosted-runner doctor

• Runner não aparece no ambiente: confirme que o host pode alcançar api.anthropic.com via HTTPS, o segredo do ambiente está atual e o relógio do host está dentro de cinco minutos da hora real; desvios maiores causam falha na autenticação. O runner registra [runner:fatal] com o motivo da rejeição em caso de falha de autenticação.
• Runner sai na inicialização com cannot create or write to base directory: o runner não consegue criar ou escrever em --base-dir, que padrão é /workspace. Corrija a propriedade do diretório ou aponte --base-dir para um caminho gravável, conforme descrito em Keep the base directory and capacity identical across runners. Se o runner registrar [runner:fatal] dizendo que a verificação do diretório base expirou, o diretório está em uma montagem NFS ou CSI travada. Verifique a saúde da montagem em vez de permissões. O runner imprime ambas essas falhas de inicialização para stderr antes de abrir --log-file, então procure por elas no terminal ou nos logs do contêiner da sua plataforma em vez do arquivo de log. Antes da v2.1.225, o runner não verificava o diretório base na inicialização, e essa configuração incorreta falhava nas sessões após a coleta.
• O runner sai na inicialização com RegisterRunner failed: e um erro de certificado TLS: o erro pode ser self signed certificate in certificate chain, por exemplo. O runner não confia na autoridade certificadora (CA) por trás do certificado que recebeu, como acontece atrás de um proxy que inspeciona TLS. Defina NODE_EXTRA_CA_CERTS no ambiente do runner para um arquivo PEM com a CA raiz do proxy. Você não precisa defini-la novamente para as sessões, que a herdam. O Git não a lê: para clones através desse proxy, defina também GIT_SSL_CAINFO.
• Seu script de inicialização imprime um erro de escrita contendo Resource temporarily unavailable e sai: seu script compartilha seu stdout ou stderr com o processo claude self-hosted-runner ou do orquestrador que ele inicia, o qual mudou esse pipe ou socket compartilhado para o modo não bloqueante. Quando o pipe está cheio, uma escrita do seu script falha com esse erro do sistema operacional em vez de aguardar, e sob set -e o script sai. Para eliminar o erro, envie a saída do runner ou do orquestrador para um arquivo que o usuário do seu script possa criar. Acrescente >> "$HOME/claude-runner.log" 2>&1 ao comando que o inicia, antes de qualquer & que o coloque em segundo plano:
  claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1
  
  A saída do próprio script continua indo para onde ia antes, enquanto o que o runner escreve em stdout e stderr, incluindo seus erros de inicialização, vai para esse arquivo. Use esse redirecionamento do shell em vez de apenas --log-file, que espelha o log em um arquivo enquanto o runner continua escrevendo em stdout e stderr. Se você já passa --log-file, mantenha-a também, porque o redirecionamento não altera o que esse arquivo recebe.
• O orquestrador registra poll failed: com um erro de certificado TLS e continua tentando novamente: o orquestrador não confia na CA por trás do certificado que recebeu, como acontece atrás de um proxy que inspeciona TLS. Defina NODE_EXTRA_CA_CERTS no ambiente do orquestrador para um arquivo PEM com a CA raiz do proxy. Defina-a também para os runners que seu hook spawn-runner inicia. Por exemplo, uma linha pode terminar com poll failed: self signed certificate in certificate chain — retrying in 1s, com as palavras da biblioteca TLS entre os dois-pontos e o travessão. Para confirmar a correção, verifique se connected é true no corpo de /healthz do orquestrador.
• Sessions stay queued: cada runner online pode estar bloqueado para um proprietário diferente. Verifique a métrica claude_code_self_hosted_runner_locked_account metric de cada runner ou o campo locked_account de sua linha de log [runner:health] para ver quem a mantém. Ambos mostram o email do proprietário apenas depois que o runner recebeu um token de sessão com uma reivindicação act.email, que as sessões de um agente Claude Tag nunca fazem. Sem a reivindicação, o runner não emite nenhuma série locked_account e registra locked_account=yes, o que informa que o runner está bloqueado, mas não para qual proprietário. Adicione réplicas ou aguarde um runner existente drenar e reiniciar. Se o ambiente usar runners sob demanda, verifique o orquestrador; consulte On-demand runners.
• As sessões falham imediatamente após a coleta: abra a sessão em claude.ai/code para ver o erro. Se o erro mostrar que o git não conseguiu se autenticar, verifique as credenciais git do runner. Em um runner iniciado com --use-anthropic-git-proxy, consulte Quando as sessões não iniciam em um runner com o proxy git. Um diretório base não gravável interrompe o runner na inicialização em vez de fazer as sessões falharem. Consulte a entrada O runner sai na inicialização com cannot create or write to base directory nesta lista.
• Uma sessão é coletada, mas o Claude nunca responde à primeira mensagem: se seus runners alcançam api.anthropic.com através de um proxy, configure-o para repassar a resposta /worker/events/stream da sessão à medida que ela chega. Aumentar os timeouts do runner não ajuda. Para confirmar a causa no log do runner, consulte Uma sessão é coletada, mas o Claude nunca responde à primeira mensagem.
• As sessões não iniciam em um runner que definiu --use-anthropic-git-proxy: procure no log do runner por access denied by the git proxy, ou por um erro do git que mencione um endereço de api.anthropic.com contendo /git_proxy/. Para saber se a Anthropic atendeu a sessão e corrigir a causa, consulte Quando as sessões não iniciam em um runner com o proxy git.
• Sessions can’t reach the network through an authenticating egress proxy: quando a fonte que você definiu com --proxy-authorization-command ou --proxy-authorization-file falha, expira após 30 segundos ou produz um valor vazio, o runner responde essa conexão com 502 Bad Gateway e registra o motivo. O runner redige o stderr do comando nesse log e nunca registra o valor do cabeçalho. Com --proxy-authorization-command, execute o comando você mesmo no host para confirmar que ele imprime o valor do cabeçalho inteiro em stdout. Se o runner sair na inicialização com could not start the proxy-authorization listener, ele não conseguiu abrir seu listener de loopback.
• O runner registra linhas Poll failed contendo rejecting the malformed poll response: o runner recebeu uma resposta de work-poll cujo corpo não é o JSON esperado da fila. Uma causa é um proxy interceptador ou um portal cativo respondendo com sua própria página. Se o runner se conecta através de um proxy, configure o proxy para passar as respostas de api.anthropic.com inalteradas. O runner rejeita a resposta malformada, a contabiliza sob o tipo transport da métrica claude_code_self_hosted_runner_poll_errors_total e tenta novamente no cronograma de poll com falha descrito em Ciclo de vida da sessão. O runner continua servindo suas sessões ativas. Antes da v2.1.246, o runner lia tal resposta como uma fila de trabalho vazia, o que poderia encerrar suas sessões ativas ou fazer com que ele saísse.
• Uma sessão falha com no longer exists on the remote ou couldn't find remote ref: o runner interpreta o couldn't find remote ref do git como um branch excluído. O branch ainda pode existir. Procure por ele no seu host git, exatamente com o nome que aparece na mensagem, e então verifique cada causa que se aplica:
  • O branch não existe mais: restaure-o, como a mensagem pede.
  • O branch existe e você não administra o runner: envie ao administrador do runner a mensagem completa e informe que o branch existe.
  • O branch existe e o runner tem um hook checkout: um comando git no seu hook pode imprimir couldn't find remote ref em stderr antes de o hook sair com um código diferente de zero. Encontre esse comando e corrija a ref que ele solicita ou o remoto do qual ele busca. O runner passa ao seu hook a revisão que a sessão solicitou como CLAUDE_RUNNER_REPO_REF.
  • O branch existe e o runner não tem um hook checkout: o próprio runner busca o branch. Se um --git-host-rewrite se aplicar ao repositório, confirme que o host para o qual ele reescreve tem o branch com o mesmo nome e envie o branch para lá se não tiver.
  • O branch existe e o runner é anterior à v2.1.301: atualize o runner conforme descrito em Fixe a versão, para que uma falha diferente mostre seu próprio erro. Antes da v2.1.301, outras falhas com couldn't find remote ref na saída de erro também eram relatadas como um branch excluído.
  Depois que o runner for atualizado ou a causa for corrigida, tente novamente a sessão ou inicie uma nova. Se nenhuma dessas verificações encontrar a causa, relate um problema. Para a fonte para a qual a sessão envia resultados, um branch excluído faz a sessão falhar. Para uma fonte git que a sessão apenas lê, o runner pula essa fonte e continua nas restantes. O runner faz a sessão falhar quando pular a deixaria sem nenhum repositório. Antes da v2.1.228, tal sessão começava em um diretório vazio.
• O Claude Tag às vezes não publica sua resposta no Slack: o lembrete de resposta é um hook que o plano de controle fornece. Confirme que o runner é o Claude Code v2.1.229 ou posterior com claude --version, já que runners mais antigos ignoram os hooks fornecidos; confirme que python3 --version é bem-sucedido dentro da imagem do runner, já que os hooks executam python3; e confirme que nenhum arquivo de configurações desativa os hooks, seja disableAllHooks em managed-settings.json, no ~/.claude/settings.json do usuário do runner ou no .claude/settings.json ou .claude/settings.local.json do repositório, ou allowManagedHooksOnly ou um strictPluginOnlyCustomization que abranja hooks nas configurações gerenciadas.
• Uma sessão inicia sem um de seus repositórios: em um runner sem um hook checkout, o host git pode recusar a verificação de acesso do runner para um repositório que a sessão apenas lê. O runner então pula esse repositório, registra uma linha [runner:warn] could not access context source nomeando a recusa e inicia a sessão nos restantes. O runner pula apenas uma recusa clara: o host responde que o repositório não foi encontrado, git não encontra credenciais para o host, ou a autenticação falha. Uma falha de rede, um timeout ou um HTTP 403 ainda falha no início da sessão, assim como uma recusa para um repositório para o qual a sessão envia resultados. O runner ainda falha em uma sessão que pular deixaria sem nenhum repositório. Com --use-anthropic-git-proxy, o runner pula apenas um repositório que o proxy git em si nega. A verificação de acesso é executada novamente cada vez que a sessão é iniciada em um runner, portanto, uma vez que a identidade git do runner tenha acesso de leitura, o próximo início clona o repositório. Antes da v2.1.274, cada uma dessas recusas falhava no início da sessão.
• Uma sessão não inicia com This runner couldn't read: o runner solicitou um repositório ao host git com suas credenciais git e recebeu uma resposta de não encontrado. O repositório não existe, ou essas credenciais não conseguem alcançar o repositório.
  • Se você administra o runner: conceda às credenciais git dele acesso de leitura ao repositório e, em seguida, inicie uma nova sessão.
  • Se você iniciou a sessão: se o repositório não existir, inicie uma nova sessão com o repositório correto. Se o runner não conseguir alcançar o repositório, peça ao administrador do runner que conceda acesso e, em seguida, inicie uma nova sessão.
• As sessões levam minutos para iniciar ou retomar: uma causa é um clone novo. Em uma frota que inicia cada runner em um disco vazio, sem hook checkout, o runner clona os repositórios da sessão do zero antes de iniciar o Claude Code. Uma sessão que é retomada em um disco vazio aguarda o mesmo clone novamente. Para evitar o clone novo, forneça um checkout pré-aquecido. Se você já fornece um, confirme que o runner o usa. Onde o próprio runner faz o clone e sai após uma sessão, reduza CLAUDE_RUNNER_FETCH_DEPTH do seu padrão de 50 commits para buscar menos histórico. Se você usa um hook, ele é executado no lugar do clone do runner, então verifique o que seu hook faz. Observe a métrica claude_code_self_hosted_runner_session_init_duration_seconds para ver quanto tempo os inícios levam.
• Os turnos falham com um 401: quando um turno termina com um 401 ou 403 da API da Anthropic, o runner busca um CLAUDE_CODE_OAUTH_TOKEN novo da Anthropic e o passa para a sessão. O turno com falha não é tentado novamente. Esse token é de curta duração, e o runner o rotaciona pelo stdin da sessão. Quando uma busca falha, o runner registra uma linha inference_token refresh failed que diz quando tentará novamente, e continua tentando novamente enquanto a sessão estiver em execução. Se cada chamada começar a falhar cerca de 30 minutos em uma sessão, um script wrapper provavelmente sevrou o stdin da sessão, então as rotações de token não conseguem alcançá-lo; consulte Keep stdin and file descriptor 3 attached. Antes da v2.1.274, o runner parou de tentar novamente uma busca com falha após algumas tentativas e aguardou a próxima agendada. Uma volta com falha não acionou uma busca, então cada volta falhou com um 401 até a próxima busca agendada.
• Um turno falha em claude.ai/code com This model needs a newer version of Claude Code: a versão do Claude Code com a qual seus runners iniciam as sessões é mais antiga do que o modelo da sessão exige, então a API rejeita a requisição. Atualize os runners para a versão que a mensagem pede, ou uma posterior, conforme descrito em Fixe a versão. Até lá, as pessoas podem escolher um modelo diferente na sessão.
• Pod is killed mid-drain: aumente terminationGracePeriodSeconds para pelo menos o valor que o runner registra na inicialização. Consulte Shutdown timing.

​

When the runner exits

• A normal exit: o runner terminou suas sessões e drenagem, atingiu seu tempo de aposentadoria ou foi instruído a parar. Reinicie-o para que o ambiente tenha capacidade novamente. Runner lifecycle descreve essas saídas.
• A failed start: o runner não consegue iniciar com a configuração ou host que foi dado, então sai segundos depois de iniciar, e sai da mesma forma toda vez que você o reinicia. Reiniciá-lo mais rápido não ajuda. Alguém precisa ler sua saída e corrigir a causa.
• Perda de contato: um runner que não consegue alcançar a Anthropic por mais tempo do que seu lease, por exemplo enquanto seu host está em suspensão, pode ser removido do ambiente. Quando um runner removido se reconecta, ele sai. Seu log pode mostrar uma linha [runner:fatal] que contém runner record gone server-side ou, após uma interrupção mais longa, poll auth failed. O runner não se registra novamente por conta própria, então reinicie-o.

​

Recognize a failed start

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

• No line at all: um runner que o host mata não imprime nenhum. Se a saída terminar sem nenhuma linha [runner:fatal] e nenhuma linha error:, verifique se o host ou seu orquestrador parou o processo, por exemplo por exceder um limite de memória.
• The exit code: o runner não reserva um código de saída para erros que se repetem a cada início. Ele sai com o mesmo código para um erro de configuração, como uma combinação não suportada de sinalizadores, e para uma falha que pode se limpar por si mesma, como a API permanecendo inacessível através das próprias tentativas do runner. Baseie a decisão de aguardar mais tempo em quão rápido o runner saiu e leia a saída do runner para aprender por quê.
• An environment that looks healthy: alguns passos de inicialização são executados depois que o runner se registra com seu ambiente, como --configure-git e a configuração de credenciais do proxy git da Anthropic. Se uma dessas etapas falhar, o ambiente pode continuar listando esse runner por alguns minutos após o processo ter saído, e a página Cloud environments pode ler Healthy enquanto nenhum runner está pegando trabalho. Se as sessões ficarem enfileiradas em um ambiente que parece saudável, verifique se seu supervisor está reiniciando o runner.

​

Restart with a wait that grows

• Kubernetes: o Deployment nesta página não precisa de alteração. Depois que um contêiner sai, o kubelet por padrão aguarda antes de reiniciar o contêiner, e a espera cresce a cada reinicialização até um teto. A espera recomeça uma vez que o contêiner tenha sido executado por um tempo sem sair. O kubelet aplica a mesma espera após uma saída normal quando o contêiner foi executado apenas brevemente. Um runner que drena frequentemente pode, portanto, também mostrar o status CrashLoopBackOff, então leia a saída antes de concluir que o runner não consegue iniciar. O comando abaixo lê a saída da última execução de um pod do Deployment:
  kubectl logs --previous -n claude-runners deploy/claude-runner
  
  Quando a última execução foi um início com falha, a linha [runner:fatal] ou error: está entre as últimas linhas da saída. Para ler a última execução de outro pod, nomeie esse pod no lugar de deploy/claude-runner.
• Docker and Docker Compose: a Compose recipe nesta página não precisa de alteração. Com restart: always, o Docker aguarda mais tempo antes de cada reinicialização de um contêiner que continua saindo, até um teto. Substitua <container> pelo nome do contêiner no comando abaixo, que lê quantas vezes o Docker reiniciou o contêiner:
  docker inspect --format '{{.RestartCount}}' <container>
  
  O comando imprime um número. Um número que continua subindo significa que o Docker continua reiniciando o runner.
• A systemd unit: por padrão, systemd aguarda o mesmo RestartSec antes de cada reinicialização e não o alonga, então uma unidade com Restart=always reinicia um runner que não consegue iniciar nesse mesmo intervalo cada vez. Quando os inícios vêm rápido o suficiente para atingir o limite de taxa de início da unidade, cinco inícios em 10 segundos por padrão, systemd para de reiniciar a unidade. A unidade permanece parada até que alguém a inicie novamente, o que systemd permite uma vez que o intervalo do limite de taxa tenha passado ou após systemctl reset-failed. Como RestartSec se aplica a cada reinicialização, um valor mais longo também atrasa a reinicialização após uma saída normal. Escolha um valor que equilibre os dois e alerte sobre a contagem de reinicializações da unidade.
• A shell loop or your own supervisor: aplique a mesma regra você mesmo. Comece com uma espera de cinco segundos. Após cada execução que terminou dentro de um minuto, dobre a espera para a próxima reinicialização, até cinco minutos. Após uma execução que durou um minuto ou mais, volte para cinco segundos.

​

Check why the runner keeps exiting

• The last [runner:fatal] or error: line: ela diz por que o runner parou. Troubleshooting lista as causas comuns.
• The combination of flags: o Anthropic git proxy requer --capacity 1. As receitas nesta página usam uma capacidade mais alta, então baixe-a quando adicionar o proxy a uma delas.
• What the service’s environment can reach: se o runner inicia manualmente e falha sob seu supervisor, compare o usuário, o diretório inicial, o PATH e o limite de memória. --configure-git e o proxy git da Anthropic precisam de git no PATH e um ~/.gitconfig gravável.
• The environment secret: se você revogou o segredo ou digitou errado, o runner imprime uma linha que contém RegisterRunner auth failed.
• The environment’s Activity tab: abra o ambiente e selecione Activity. Se novos runners continuarem aparecendo lá e nenhum pega trabalho, seu supervisor está reiniciando o runner.

​

Uma sessão é coletada, mas o Claude nunca responde à primeira mensagem

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

• Não armazene a resposta em buffer: repasse-a à medida que ela chega. Seu tipo de conteúdo é text/event-stream.
• Deixe a resposta permanecer aberta: ela pode ficar aberta por até uma hora. Se o proxy tiver um timeout de inatividade, mantenha-o bem acima de 15 segundos, porque a Anthropic envia um keep-alive pelo menos com essa frequência por padrão.

​

Confirme a causa no log do runner

1. Aguarde --startup-timeout-min passar, 15 minutos por padrão. O runner então interrompe a sessão e registra uma linha que contém no child output for e termina com — releasing.
2. Pesquise no log do runner por SDKStartup: SSE. Essas linhas vêm depois de uma linha finished: interrupted, algumas linhas após a da etapa 1. A maioria não tem timestamp, então um coletor de logs pode exibi-las em outro lugar.
3. Encontre a linha nesta tabela:

​

Impeça que a sessão tente novamente

​

O que vem a seguir

• Customize sessions: wrapper scripts, lifecycle hooks, on-demand runners, MCP servers, and permissions
• Test end to end: verify a new runner image from CI before promoting it
• Reference: every CLI flag, environment variable, and metric