SpyBara
Go Premium

self-hosted-environments-reference.md 2026-09-27 23:59 UTC to 2026-09-28 22:01 UTC

This page contains 7 additions and 7 deletions.

2026
Sat 12 03:02 Fri 18 23:58 Sat 19 23:57 Mon 28 22:59

Referência de ambientes auto-hospedados

Referência completa para o executor e orquestrador auto-hospedados: sinalizadores CLI, variáveis de ambiente e métricas Prometheus.

Esta página é a referência para os dois processos que você executa em um ambiente auto-hospedado: o executor, que executa sessões na nuvem do Claude Code em seus hosts, e o orquestrador de dimensionamento automático opcional, que inicia executores conforme as sessões são enfileiradas. Cada um tem sua própria tabela de sinalizadores. Ambos são executados em hosts Linux ou macOS, que os padrões como /workspace e ~/.claude assumem. Execute claude self-hosted-runner --help para a lista autoritativa em sua versão instalada.

Séries de métricas e alguns campos de API ainda usam pool para o que estas páginas chamam de ambiente; ambos os termos nomeiam a mesma coisa. O ID do ambiente é o campo pool_id, com a forma ccpool_...: onde quer que estas páginas mostrem um identificador pool, ele nomeia o ambiente. Sinalizadores CLI e variáveis de ambiente o escrevem como environment, como --environment-secret-file; as grafias pool descontinuadas ainda funcionam, como a linha --environment-secret-file descreve.

Sinalizadores CLI do executor

A maioria dos sinalizadores tem uma variável de ambiente correspondente. Quando ambos estão definidos, o sinalizador tem precedência. Sinalizadores de duração usam minutos ou segundos na CLI, mas a variável de ambiente emparelhada está sempre em milissegundos, indicada pelo sufixo _MS, e a coluna Padrão mostra a unidade do sinalizador: --exit-if-unused-min 10 é equivalente a SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, e um valor Helm como SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" significa 15 milissegundos, não o padrão de 15 minutos.

Sinalizador Var de ambiente Padrão Descrição
--api-url <url> nenhum https://api.anthropic.com URL base da API. Substitua apenas para testes.
--base-dir <path> SELF_HOSTED_RUNNER_BASE_DIR /workspace; nenhum no Windows Diretório para checkouts de repositório e diretórios de trabalho por sessão. O executor precisa de acesso de escrita a este caminho ou seu pai. O executor cria o diretório na inicialização e sai com cannot create or write to base directory quando não consegue criar ou escrever nele. Antes da v2.1.225, o executor criava o diretório quando a primeira sessão começava, então um caminho inutilizável falhava nas sessões em vez da inicialização. No Windows, que não é um host executor suportado, não há padrão: o executor sai na inicialização a menos que você passe o sinalizador ou defina a variável. Use o mesmo valor em cada executor em um ambiente. Consulte Keep the base directory and capacity identical across runners.
--capacity <n> nenhum 1 Máximo de sessões simultâneas que este executor manipula. Todas as sessões pertencem ao mesmo proprietário bloqueado. Use o mesmo valor em cada executor em um ambiente; consulte Keep the base directory and capacity identical across runners.
--client-label <label> SELF_HOSTED_RUNNER_CLIENT_LABEL nome do host Rotule o executor que envia quando se registra. O executor também o relata como o rótulo client_label de claude_code_self_hosted_runner_info. Requer Claude Code v2.1.248 ou posterior.
--configure-git SELF_HOSTED_RUNNER_CONFIGURE_GIT=1 desligado Na inicialização, escreva identidade git global, habilite assinatura de commit Anthropic, ative negociação de push git e instale hooks de commit que anexam um trailer Co-authored-by:. A negociação de push requer Claude Code v2.1.257 ou posterior. Consulte Configure git.
--confine-repo-settings <mode> SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS warn Define o modo da proteção que sinaliza uma sessão quando as configurações confirmadas de um repositório tentam conceder acesso de escrita ou leitura fora do próprio workspace dessa sessão, definir variáveis de ambiente ou substituir a postura de sandbox ou hooks do operador, como sandbox.enabled: false ou disableAllHooks. O padrão warn registra a violação e ainda inicia a sessão, enforce recusa a sessão, e off desabilita a verificação. Consulte Harden your deployment.
--debug-token-dir <path> SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR não definido Escreva tokens ao vivo em disco para inspeção. Apenas depuração; não use em produção.
--defer-shutdown-max-min <n> SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS 0 No primeiro SIGTERM ou SIGINT, continue servindo as sessões já anexadas em vez de drená-las, depois libere o que ainda estiver anexado N minutos depois e saia. Aumente o tempo limite de parada do seu host antes de definir isso. Consulte Defer the drain past the first signal. 0 desabilita. Requer Claude Code v2.1.238 ou posterior.
--drain-grace-sec <n> SELF_HOSTED_RUNNER_DRAIN_GRACE_MS 0 Até o executor receber um sinal de desligamento ou atingir seu tempo de aposentadoria, controla quando o executor sai após suas sessões ativas terminarem: 0 sai imediatamente sem pesquisar mais, e um valor positivo mantém o executor vivo e re-pesquisando a fila do proprietário bloqueado por muitos segundos primeiro, ao custo do isolamento de contêiner por sessão descrito na seção de endurecimento. Após um primeiro sinal que você adiou com --defer-shutdown-max-min, o executor sai assim que não mantém sessões, seja qual for o que você definir aqui.
--drain-marker-file <path> SELF_HOSTED_RUNNER_DRAIN_MARKER_FILE não definido Arquivo marcador que seu host escreve para anunciar uma drenagem graciosa antes de enviar SIGTERM. Quando o arquivo existe quando a drenagem começa, o executor relata sua saída para Anthropic como uma drenagem de host em vez de um sinal de desligamento simples. A drenagem em si, incluindo a espera --drain-wait-sec, funciona da mesma forma que sem o sinalizador. Nomeie um caminho em um sistema de arquivos local que as sessões não possam escrever. Requer Claude Code v2.1.271 ou posterior.
--drain-wait-sec <n> SELF_HOSTED_RUNNER_DRAIN_WAIT_MS 0 Uma vez que a drenagem começa, que é em SIGTERM a menos que você defina --defer-shutdown-max-min, aguarde até N segundos para que cada turno em voo da sessão e tarefas em segundo plano terminem antes de encerrar o filho. Durante esta espera, o executor conta uma tarefa em segundo plano que acabou de terminar como ainda em execução até o turno de acompanhamento que lê seu resultado começar, por no máximo a janela SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS.
--environment-secret-file <path> SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET obrigatório Caminho para um arquivo contendo o segredo do ambiente, ou, para executores gerados pelo orquestrador, o JWT de ordem de trabalho de uso único. SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET carrega o valor secreto diretamente, não um caminho de arquivo. O sinalizador --pool-secret-file mais antigo e a variável SELF_HOSTED_RUNNER_POOL_SECRET ainda funcionam e imprimem um aviso de descontinuação para stderr; compilações de executor do programa de visualização mais antigas que 2.1.216 reconhecem apenas esses nomes mais antigos.
--exec-path <path> SELF_HOSTED_RUNNER_EXEC_PATH binário próprio Binário ou script wrapper para gerar para cada sessão. Consulte Wrapper scripts.
--exit-if-unused-min <n> SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS 0 Saia após N minutos de pesquisa sem trabalho nunca atribuído, para redução de escala do autoscaler. 0 desabilita.
--git-host-rewrite <from>=<to> nenhum não definido Reescreva URLs de origem https://<from>/... para https://<to>/... antes de clonar, para DNS de horizonte dividido. Repetível; apenas sinalizador.
--git-ssh-rewrite <host> nenhum não definido Reescreva URLs de origem https://<host>/... para git@<host>:... antes de clonar, para hosts git somente SSH. Repetível; apenas sinalizador.
--health-port <port> SELF_HOSTED_RUNNER_HEALTH_PORT 8080 Porta para o ouvinte /healthz e /metrics. Defina 0 para desabilitar.
--hooks-dir <path> SELF_HOSTED_RUNNER_HOOKS_DIR não definido Diretório de scripts de hook de ciclo de vida. Consulte Lifecycle hooks.
--host-config-snapshot <mode> SELF_HOSTED_RUNNER_HOST_CONFIG_SNAPSHOT disk Onde o executor mantém o snapshot de inicialização do diretório de configuração do host que semeia cada sessão a partir de. disk copia o snapshot para um diretório de propriedade do executor sob --base-dir e, no início de cada sessão, verifica cada arquivo contra um resumo na memória. Se um arquivo na cópia foi modificado, a sessão falha e o executor recusa sessões até você reiniciá-lo. memory mantém todo o snapshot no heap, limitado a 64 MiB; acima do limite, as sessões começam sem configuração de host e mostram um aviso dizendo isso. Quando o executor não consegue escrever o snapshot de disco, ele registra a falha e usa memory para essa execução. Requer Claude Code v2.1.271 ou posterior.
--kill-session-after-min <n> SELF_HOSTED_RUNNER_MAX_LIFETIME_MS 0 Limite uma sessão a N minutos de tempo real, como um limite de segurança para sessões presas. Na v2.1.260 ou posterior, o executor libera uma sessão que atinge o limite para que possa retomar na próxima mensagem do usuário, e a encerra apenas se ainda estiver no executor quando a janela de graça SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS terminar. Antes da v2.1.260, o executor encerrava a sessão no limite. Consulte Some sessions don't count as idle para os detalhes e como escolher um valor. 0 desabilita.
--lock-to-account <id> SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT não definido Pré-bloqueie o executor para uma conta específica na inicialização em vez de bloquear na primeira sessão. Aceita um endereço de email ou ID user_... na organização do ambiente. Um executor pré-bloqueado nunca pega sessões de canal Claude Tag, que não têm conta.
--log-file <path> SELF_HOSTED_RUNNER_LOG_FILE não definido Espelhe logs do executor para um arquivo além de stdout e stderr, criado com permissões 0600. Obrigatório para self-hosted-runner doctor rastrear logs localmente.
--log-level <level> nenhum info info ou debug
--post-session-hook-timeout-sec <n> SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS 60 Orçamento para o hook post-session no final de cada sessão, incluindo desligamento do executor
--proxy-authorization-command <command> SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND não definido Comando shell que o executor executa para cada conexão com seu proxy de saída, usando seu stdout aparado como o valor do cabeçalho Proxy-Authorization. Requer HTTPS_PROXY ou HTTP_PROXY, e não pode ser combinado com --proxy-authorization-file. Consulte Authenticate to an egress proxy. Requer Claude Code v2.1.238 ou posterior.
--proxy-authorization-file <path> SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE não definido Arquivo que o executor lê para cada conexão com seu proxy de saída, usando seu conteúdo aparado como o valor do cabeçalho Proxy-Authorization. Use este sinalizador para um token que outro processo rotaciona no lugar. Carrega os mesmos requisitos que --proxy-authorization-command, e não pode ser combinado com ele. Consulte Authenticate to an egress proxy. Requer Claude Code v2.1.238 ou posterior.
--push-outcome-on-release SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE desligado No final de uma sessão iniciada pelo executor, como uma drenagem ou liberação ociosa, envie branches de resultado rastreados para origin antes de excluir o workspace, para que commits em voo sobrevivam a um reinício. Melhor esforço; adiciona 30 segundos ao orçamento de desligamento, e requer git 2.29 ou mais recente para retomar do branch enviado. Restrinja o acesso de envio para refs claude/* antes de habilitar; consulte Resumed sessions lose unpushed work. Repositórios verificados via um hook de ciclo de vida checkout não são enviados; faça snapshot deles do hook post-session em vez disso.
--release-idle-session-min <n> SELF_HOSTED_RUNNER_SESSION_IDLE_MS 0 Libere um slot de sessão após N minutos de inatividade uma vez que um turno termine ou a sessão aguarde a ação do usuário. Uma sessão que ainda está no meio de um turno, incluindo uma que mantém uma tarefa em segundo plano que nunca termina ou uma aprovação solicitada de dentro de uma chamada de ferramenta em execução, não conta como ociosa; emparelhe com --kill-session-after-min como o backstop duro. Após a tarefa em segundo plano de uma sessão terminar, o executor considera a sessão ocupada até o turno de acompanhamento que lê o resultado começar, por no máximo a janela SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS. Até o executor receber um sinal de desligamento ou atingir seu tempo de aposentadoria, uma liberação que deixa o executor sem sessões ativas inicia o mesmo caminho de saída que uma drenagem normal, governada por --drain-grace-sec. Após um primeiro sinal que você adiou com --defer-shutdown-max-min, o executor sai assim que uma liberação o deixa sem sessões. 0 desabilita.
--remove-session-state [bool] SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE desligado Remova os diretórios por sessão de uma sessão sob <base-dir>/_sessions/ quando a sessão terminar neste executor, seja qual for o resultado. Reuse a pre-warmed checkout descreve o que eles contêm e quem pode lê-los quando permanecem. A remoção é melhor esforço: os diretórios por sessão permanecem no lugar quando o executor é morto ou atinge seu prazo de drenagem antes da limpeza ser executada. Com o sinalizador ativado, o log de depuração de uma sessão falhada ou interrompida não é mantido em disco. Requer Claude Code v2.1.268 ou posterior.
--retire-at <epoch-seconds> SELF_HOSTED_RUNNER_RETIRE_AT não definido Aposentar o executor em um timestamp Unix absoluto em segundos, para infraestrutura que mata o executor em um tempo conhecido; Runner lifecycle descreve a sequência de liberação e como dimensionar a margem. Valores antes de 2001 ou após o ano 5138 são rejeitados pelo sinalizador e ignorados pela variável de ambiente.
--session-stop-grace-sec <n> SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS 5 Quanto tempo aguardar para que o processo Claude saia limpo após uma sessão terminar, antes de forçar o encerramento. Aumente o valor se os hooks SessionEnd do próprio filho precisarem de mais tempo.
--startup-timeout-min <n> SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS 15 Libere um slot de sessão se o filho não tiver sinalizado que inicializou dentro de N minutos de geração. Limpo pelo sinal de inicialização do filho no canal de atividade, não por saída ordinária, após o qual --release-idle-session-min assume. 0 desabilita.
--trust-workspace [bool] SELF_HOSTED_RUNNER_TRUST_WORKSPACE ativado Semeie confiança persistida para cada caminho de repositório de sessão para que permissions.allow e additionalDirectories confirmados no repo sejam honrados. Defina false para descartar concessões de permissão confirmadas no repo e configure regras de permissão no settings.json da configuração do host em vez disso; configurações sandbox.* confirmadas no repositório ainda se aplicam de qualquer forma, é por isso que a proteção de configurações do repo as verifica independentemente deste sinalizador.
--use-anthropic-git-proxy CLAUDE_RUNNER_USE_GIT_PROXY=1 desligado Clone via proxy git da Anthropic em vez de autenticação git gerenciada pelo cliente. Requer --capacity 1 e git 2.32 ou mais recente; o executor recusa iniciar caso contrário. Substitui os sinalizadores de reescrita.

A maioria dos sinalizadores de duração tem um máximo, escolhido para manter cada tempo limite dentro do teto do temporizador de 32 bits do tempo de execução de aproximadamente 24,85 dias. Os sinalizadores --*-min limitam a 10080 minutos, 7 dias; --drain-grace-sec a 604800 segundos, também 7 dias; e --drain-wait-sec a 86400 segundos, 24 horas. --session-stop-grace-sec e --post-session-hook-timeout-sec não têm limite. Exceder um limite se comporta diferentemente por superfície:

  • Sinalizador: a inicialização falha com um erro.
  • Variável de ambiente: o executor fixa o valor ao teto do temporizador em vez de rejeitá-lo.

Sinalizadores CLI do orquestrador

O subcomando self-hosted-runner orchestrator, que gera executores sob demanda, aceita --api-url, --environment-secret-file, --hooks-dir, --health-port e --log-level com os mesmos padrões que o executor e, onde o sinalizador do executor tem um, a mesma variável de ambiente, exceto que --hooks-dir é obrigatório e deve conter um hook spawn-runner. Também usa seus próprios sinalizadores:

Sinalizador Padrão Descrição
--hook-concurrency <n> 4 Máximo de hooks spawn-runner em execução em paralelo. Também limita quantas solicitações de geração são reivindicadas por pesquisa.
--hook-timeout <sec> 60 Encerre a árvore de processos do hook após muitos segundos. O tempo limite mais sua graça de morte de 5 segundos deve ficar abaixo de --expected-spawn-seconds; o orquestrador impõe isso na inicialização.
--expected-spawn-seconds <sec> 120 Tempo de inicialização p99 esperado para executores gerados, no intervalo imposto pelo servidor de 10 a 3600. Enviado em cada pesquisa como a concessão do lado do servidor; se nenhum executor se registrar antes de decorrido, a sessão é re-oferecida com um novo ID de pedido. Todas as réplicas devem compartilhar este valor.
--min-idle <n> 0 Mantenha pelo menos N slots de sessão ociosos livres gerando executores de espera de forma proativa. 0 desabilita pré-aquecimento. Emparelhe com o --exit-if-unused-min do executor para que executores de espera em excesso se recuperem.
--debug-dir <path> não definido Escreva a ordem de trabalho de cada solicitação de geração e stderr do hook em disco. Apenas depuração; nunca defina em produção.

Sinalizadores do conector SCM

O orquestrador pode manter uma conexão WebSocket permanente com o plano de controle da Anthropic para que fluxos pré-sessão hospedados, como o seletor de repositório e o resolvedor de branch ou ref, possam alcançar um host GitHub Enterprise Server que é apenas roteável de dentro de sua rede. O conector fica desligado a menos que você defina --scm-connector-host.

Sinalizador Padrão Descrição
--scm-connector-host <host[:port]> não definido Nome do host GitHub Enterprise Server para encaminhar solicitações. A porta padrão é 443. Definir este sinalizador habilita o conector.
--scm-connector-id <n> obrigatório com --scm-connector-host O ID numérico da conexão GitHub Enterprise Server da sua organização. Entre em contato com sua equipe de conta Anthropic para o valor quando você habilitar o conector.
--scm-connector-provider <slug> ghe Segmento de caminho identificando o provedor, correspondendo a ^[a-z0-9-]{1,32}$.
--scm-connector-ca-file <path> não definido Pacote CA extra, em formato PEM, para conexões TLS com o host GitHub Enterprise Server.
--scm-connector-host-rewrite <from>=<to_host:to_port> não definido Apenas para testes de ponta a ponta: redireciona a conexão TCP mantendo o cabeçalho Host e TLS SNI como --scm-connector-host.

O conector autentica com o segredo de ambiente existente do orquestrador e se reconecta automaticamente: com backoff exponencial em uma conexão descartada, ou um atraso fixo de 30 segundos quando o plano de controle fecha a conexão porque outra réplica do orquestrador já a mantém.

Configurações somente de variável de ambiente

Essas configurações do executor são lidas apenas do ambiente e cobrem comportamento que a maioria das implantações deixa no padrão:

Var de ambiente Padrão Descrição
SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 30000 Quanto tempo o executor considera uma sessão ocupada após uma tarefa em segundo plano terminar enquanto o turno de acompanhamento que lê o resultado não começou. As linhas --drain-wait-sec e --release-idle-session-min descrevem onde a retenção se aplica na drenagem e liberação ociosa, e Runner lifecycle descreve onde se aplica na aposentadoria --retire-at. 0 ou um valor inutilizável volta ao padrão, para que a retenção não possa ser desligada. Requer Claude Code v2.1.228 ou posterior.
SELF_HOSTED_RUNNER_HOST_CONFIG_DIR ~/.claude Diretório capturado no snapshot de inicialização do executor e semeado no CLAUDE_CONFIG_DIR de cada sessão; mudanças em disco se aplicam após um reinício do executor. Definir a variável também move onde o executor lê .claude.json para seeding MCP, então defini-la, incluindo seu próprio padrão, realoca essa pesquisa; aponte para um diretório vazio para desabilitar o seeding inteiramente.
SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS 900000 Quanto tempo o executor aguarda após uma sessão atingir seu limite --kill-session-after-min, para um turno em execução terminar ou a liberação ser concluída, antes de encerrar a sessão
SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS 7000 Limite superior de quanto tempo o executor conta uma sessão como ocupada para a drenagem --drain-wait-sec após um turno terminar, enquanto o processo da sessão relata o fim do turno para a Anthropic. 0 ou um valor inutilizável volta ao padrão, para que a retenção não possa ser desligada. Requer Claude Code v2.1.275 ou posterior.
SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS 30000 Quanto tempo o executor aguarda o SO entregar SIGKILL para um filho preso em I/O não interruptível antes de sair ele mesmo. Limitado a --post-session-hook-timeout-sec mais 15 segundos, e 30 mais quando --push-outcome-on-release está definido, então o mínimo efetivo é 75 segundos nos padrões.
CLAUDE_RUNNER_FETCH_DEPTH 50 Profundidade de busca git para clones frescos. Defina um inteiro positivo, ou full ou 0 para uma busca completa. Repositórios já presentes no workspace mantêm sua profundidade existente.
CLAUDE_RUNNER_SKIP_GIT_VERIFY não definido Quando 1, pule a verificação de presença .git após um hook checkout ser executado. Defina isso quando seu hook materializa uma fonte não-git.
FORCE_AUTOUPDATE_PLUGINS não definido Quando 1, deixe marketplaces de plugin se atualizarem automaticamente mesmo que o binário esteja fixado
CLAUDE_CODE_DISABLE_ARTIFACT não definido Quando 1, desabilite a ferramenta Artifact em sessões independentemente da configuração de administrador da organização, e solte o requisito de saída *.frame.claudeusercontent.com

Telemetria

Filhos de sessão enviam telemetria operacional para Anthropic a menos que você a desative. Nenhum código ou conteúdo de repositório é enviado. Defina variáveis de telemetria no processo do executor; o executor as re-afirma após aplicar variáveis de ambiente fornecidas pelo servidor, então a configuração do operador sempre tem precedência.

Um controle é específico para ambientes auto-hospedados: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 opta por métricas operacionais Datadog, que estão desligadas por padrão em ambientes auto-hospedados. Os controles gerais de telemetria Claude Code, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING e CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, se aplicam a filhos de sessão conforme documentado na referência de variável de ambiente. DISABLE_GROWTHBOOK é relacionado mas diferente: definir DISABLE_GROWTHBOOK=1 desabilita a busca de sinalizador de recurso, e a telemetria permanece ativada a menos que DISABLE_TELEMETRY também esteja definido.

CLAUDE_CODE_ENABLE_TELEMETRY não está relacionado: habilita a exportação OpenTelemetry para seu próprio coletor, conforme descrito em Monitoring, e não controla a análise da Anthropic.

Ponto de extremidade de saúde

O executor serve GET /healthz na porta de saúde configurada. A resposta é 200 OK sempre que o processo está vivo, seja qual for o estado do loop de pesquisa, então uma sonda HTTP neste ponto de extremidade detecta apenas um processo morto. O corpo JSON descreve o estado atual:

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

Use last_poll_age_ms como um sinal de vivacidade em sondas personalizadas; um valor que cresce sem limite indica que o loop de pesquisa está preso. Tanto last_poll_at quanto last_poll_age_ms são null até a primeira pesquisa ser concluída.

O orquestrador serve seu próprio /healthz em sua porta de saúde. Seu ponto de extremidade sempre retorna 200, e o corpo carrega um campo connected relatando se a pesquisa mais recente foi bem-sucedida, mais contagens de fila de geração por estado em queue_counts. Controle prontidão e alertas em connected em vez do código de status.

Quando o conector SCM está configurado, o corpo /healthz do orquestrador também carrega scm_connector_connected e um objeto scm_connector com connected, last_connected_at, last_error, reconnects e requests_forwarded. Ambos os campos são null quando --scm-connector-host não está definido.

Métricas Prometheus

Cada executor serve métricas Prometheus em GET /metrics na mesma porta que /healthz. Séries principais:

Série Notas
claude_code_self_hosted_runner_info{runner_id,version,client_label} Sempre 1; útil para inventário de frota e detecção de desvio de versão
claude_code_self_hosted_runner_capacity --capacity configurado
claude_code_self_hosted_runner_active_sessions Sessões em execução no momento
claude_code_self_hosted_runner_locked_account{email} Presente uma vez que o executor tenha bloqueado para um usuário e um token de sessão carregando uma reivindicação act.email tenha sido emitido. A série está ausente em um executor bloqueado para um agente Claude Tag, cujos tokens de sessão não carregam act.email. O valor do rótulo é o email da conta; se sua loja de métricas for amplamente legível, solte ou hash o rótulo no tempo de raspagem, por exemplo com metric_relabel_configs do Prometheus.
claude_code_self_hosted_runner_last_poll_age_seconds Segundos desde a última pesquisa bem-sucedida. Alerte se acima de 60.
claude_code_self_hosted_runner_poll_errors_total{error_kind} Falhas cumulativas de PollWork por tipo: transport, timeout, 5xx, 429 ou 4xx. Todas as cinco séries estão presentes desde o início do processo; alerte em rate(...[5m]) > 0.
claude_code_self_hosted_runner_sessions_started_total{client_platform} Processos filhos de sessão gerados durante a vida útil do executor, uma série por origem de sessão como web_claude_ai, ios, android, desktop_app ou claude_code_cli, ou unknown quando o servidor não enviou um. Sessões Slack carregam claude_in_slack ou claude-in-slack dependendo de qual integração Slack as criou, então combine ambas com um seletor regex como {client_platform=~"claude[-_]in[-_]slack"}. Use sum() para o total da frota.
claude_code_self_hosted_runner_sessions_completed_total{client_platform} Sessões que terminaram limpo, rotuladas da mesma forma. Mais amplo que uma saída limpa simples: consulte semântica do contador de ciclo de vida da sessão para o que conta.
claude_code_self_hosted_runner_sessions_failed_total{client_platform} Sessões que terminaram em falha, rotuladas da mesma forma. Mesma ressalva: consulte semântica do contador de ciclo de vida da sessão.
claude_code_self_hosted_runner_sessions_interrupted_total{client_platform} Sessões que o executor encerrou por um motivo operacional em vez de um resultado de sessão, rotuladas da mesma forma. Consulte semântica do contador de ciclo de vida da sessão.
claude_code_self_hosted_runner_initializing_sessions Sessões atualmente na fase de inicialização, da atribuição até o evento de inicialização do filho
claude_code_self_hosted_runner_session_init_duration_seconds Histograma de durações de inicialização de sessão
claude_code_self_hosted_runner_session_init_errors_total Sessões que falharam antes de atingir a inicialização: falha de hook de checkout, preparação git, problema de token ou falha de filho pré-inicialização
claude_code_self_hosted_runner_session_start_hook_errors_total Hooks SessionStart que relataram um resultado de erro, um por execução de hook falhando
claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform} Medidor por sessão de segundos desde que a sessão ficou ociosa. Útil para encerrar sessões presas em um prompt de permissão sem resposta.

O orquestrador serve suas próprias séries em GET /metrics na mesma porta que seu /healthz:

Série Notas
claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname} Sempre 1
claude_code_self_hosted_orchestrator_connected 1 quando a pesquisa mais recente foi bem-sucedida; cai para 0 após qualquer pesquisa falhada, seja qual for o tipo de falha
claude_code_self_hosted_orchestrator_last_poll_age_seconds Segundos desde a última tentativa de pesquisa, sucesso ou falha, diferentemente da métrica identicamente nomeada do executor, que mede desde o último sucesso; emparelhe com connected para capturar pesquisas falhadas. O loop de pesquisa do orquestrador aguarda a execução do hook, então alerte acima de --hook-timeout mais uma margem, cerca de 90 segundos nos padrões, em vez de um 60 fixo.
claude_code_self_hosted_orchestrator_poll_errors_total{error_kind} Falhas cumulativas de PollSpawnHints por tipo: transport, timeout, 5xx, 429 ou 4xx. Todas as cinco séries estão presentes desde o início do processo; alerte em rate(...[5m]) > 0.
claude_code_self_hosted_orchestrator_queue_pending_sessions Solicitações de geração reivindicáveis agora
claude_code_self_hosted_orchestrator_queue_backing_off_sessions Solicitações de geração em backoff de repetição após uma falha de hook retentável
claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions Solicitações de geração bloqueadas até que um Owner as tente novamente na aba Activity do ambiente; alerte se acima de zero
claude_code_self_hosted_orchestrator_pool_pending_sessions Total de sessões aguardando um executor para este ambiente. Agregado em toda a organização, idêntico em cada instância do orquestrador: use MAX em vez de SUM entre instâncias.
claude_code_self_hosted_orchestrator_pool_active_sessions Sessões atualmente atribuídas a um executor vivo neste ambiente. Agregado em toda a organização, idêntico em cada instância do orquestrador: use MAX em vez de SUM entre instâncias.
claude_code_self_hosted_orchestrator_spawn_hooks_total{result} Resultados cumulativos de hook spawn-runner: ok, retryable, non_retryable. Conta invocações de hook do orquestrador, não filhos de sessão que os executores geram: não comparável a sessions_started_total, já que capacidade acima de um, pools quentes e executores gerados novamente para a mesma sessão divergem os dois.
claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds Histograma de durações de hook
claude_code_self_hosted_orchestrator_warm_hints_dispatched_total Solicitações de geração de espera despachadas desde o início do processo
claude_code_self_hosted_orchestrator_session_queue_wait_seconds Histograma de segundos que cada sessão aguardou na fila antes do orquestrador reivindicá-la para geração, registrado do timestamp de espera de fila que o plano de controle envia com cada solicitação de geração de sessão. Use para alertas de tempo de fila p50/p99. Gerações de pré-aquecimento não são amostradas.
claude_code_self_hosted_orchestrator_clock_skew_seconds Desvio de relógio local menos servidor; diagnóstico, presente uma vez medido
claude_code_self_hosted_orchestrator_scm_connector_connected 1 quando o WebSocket do conector SCM está aberto; 0 enquanto disca ou faz backoff. Ausente quando --scm-connector-host não está definido.
claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total Solicitações HTTP cumulativas proxied para o host SCM configurado desde o início do processo. Ausente quando --scm-connector-host não está definido.

Para dimensionamento automático, escolha a série que corresponde ao seu estilo de dimensionamento e controle-a antes de alimentar o escalador:

  • Dimensionamento de profundidade de fila: alimente claude_code_self_hosted_orchestrator_pool_pending_sessions em seu escalador HPA ou KEDA, não queue_pending_sessions.
  • Dimensionamento de capacidade: dimensione na proporção de active_sessions do executor para capacity.
  • Controle em connected: filtre a consulta com claude_code_self_hosted_orchestrator_connected == 1 por instância, para que o valor obsoleto de uma réplica desconectada não alimente o escalador.

Durante uma interrupção completa de pesquisa, cada réplica desconectada, a consulta controlada não retorna dados. HPA mantém a contagem de réplica atual em uma métrica ausente, mas o escalador Prometheus do KEDA em seu padrão ignoreNullValues: "true" lê o resultado vazio como zero e reduz; defina ignoreNullValues: "false" no ScaledObject, opcionalmente com um piso de réplica fallback.

O seguinte PodMonitor do Prometheus Operator cobre ambos os processos. Ele seleciona pods pelo rótulo app.kubernetes.io/part-of: claude-code-self-hosted-runner e a porta nomeada health que a receita Kubernetes define; ajuste os namespaces para corresponder à sua implantação:

# Exemplo de PodMonitor do Prometheus Operator para o executor +
# orquestrador auto-hospedado Claude Code. Ajuste o namespace e os seletores
# de rótulo para corresponder à sua implantação. Tanto o executor quanto o
# orquestrador servem /metrics em seu --health-port (padrão 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Corresponde ao Deployment do executor da receita Kubernetes, mais
      # qualquer Job de executor sob demanda e pods do orquestrador que você
      # rotula da mesma forma e dá uma containerPort 'health' nomeada.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Essas regras de alerta de exemplo são um ponto de partida; ajuste os limites para o tamanho da sua frota:

# Exemplo de regras de alerta Prometheus para o executor + orquestrador
# auto-hospedado Claude Code. Ajuste os limites para o tamanho da sua frota
# e SLOs.
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Executor {{ $labels.pod }} não pesquisou em >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Executores estão executando versões mistas"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Executor {{ $labels.pod }}: >3 falhas de inicialização de sessão em 10m (hook de checkout / git / token / falha pré-inicialização)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Executor {{ $labels.pod }}: PollWork falhando ({{ $value | humanize }}/s em 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Executor {{ $labels.pod }}: >3 falhas de hook SessionStart em 10m"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orquestrador {{ $labels.pod }} não consegue alcançar o plano de controle Anthropic"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orquestrador {{ $labels.pod }} não pesquisou em >90s (loop de pesquisa aguarda execução de hook)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "{{ $value }} sessões com circuito aberto — hook spawn-runner é repetidamente não retentável; corrija a infraestrutura e tente novamente na aba Activity"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orquestrador {{ $labels.pod }}: PollSpawnHints falhando ({{ $value | humanize }}/s em 5m)"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Orquestrador {{ $labels.pod }}: >3 falhas de hook spawn-runner em 5m"

Passar através de métricas de filho de sessão

Cada sessão é executada em seu próprio processo filho com suas próprias métricas OpenTelemetry; em --capacity acima de um, o executor reescreve como essas métricas de filho são expostas. Definir OTEL_METRICS_EXPORTER=prometheus no host do executor e CLAUDE_CODE_ENABLE_TELEMETRY=1 no ambiente da sessão, por exemplo a partir de seu script wrapper ou do próprio ambiente do executor, que as sessões herdam, re-expõe cada instrumento de contador e medidor do filho no ponto de extremidade /metrics do próprio executor, ao lado das séries do executor. O executor reescreve o exportador do filho para enviar por OTLP para um receptor somente de loopback na porta de saúde, marca cada série com rótulos session_id e client_platform, e remove as séries de uma sessão quando essa sessão termina. Histogramas não passam, e uma métrica de filho cujo nome colidiria com o prefixo do próprio executor é descartada.

No padrão --capacity 1, a reescrita não se aplica: o filho da sessão vincula seu próprio ponto de extremidade Prometheus na porta 9464 como usual.

Semântica do contador de ciclo de vida da sessão

Os contadores sessions_started_total, sessions_completed_total, sessions_failed_total e sessions_interrupted_total classificam cada sessão por como terminou. Cada filho de sessão gerado incrementa sessions_started_total no tempo de geração, e exatamente um dos outros três incrementa na saída, então sessions_started_total menos a soma dos outros três é igual ao número de filhos de sessão em execução no momento.

  • completed: a sessão terminou limpo. Isso cobre o filho saindo por conta própria com código 0, a sessão sendo arquivada ou excluída enquanto o filho ainda estava conectado, e o executor devolvendo o slot de forma limpa: a liberação da sessão no tempo limite de ociosidade, no tempo de aposentadoria ou no limite --kill-session-after-min; um tempo limite de inicialização; ou uma desatribuição do lado do servidor que o loop de pesquisa notou antes do filho sair. Incrementa sessions_completed_total.
  • failed: o filho saiu por conta própria com um código diferente de zero, seja um crash ou uma falha de configuração após geração. Incrementa sessions_failed_total.
  • interrupted: o executor encerrou o filho por um motivo operacional que não é nem um sucesso de sessão nem uma falha do executor, como uma drenagem ou o encerramento de uma sessão que ainda estava no executor quando a janela de graça SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS após seu limite --kill-session-after-min terminou. Um reinício de rolagem Kubernetes enviando SIGTERM é um exemplo de uma drenagem. Incrementa sessions_interrupted_total.

Antes da v2.1.260, o executor encerrava cada sessão que atingia seu limite --kill-session-after-min e a contava em sessions_interrupted_total.

O CLAUDE_RUNNER_EXIT_REASON do hook post-session classifica entregas limpas de forma diferente. O hook relata uma liberação, um tempo limite de inicialização e uma desatribuição do servidor como interrupted, porque o executor parou o filho. Esses contadores registram os mesmos eventos como completed, porque o slot foi devolvido limpo.

Se você reconciliar recebimentos de hook contra sessions_completed_total diretamente, você subestima as conclusões. Use o hook para garantias por sessão e os contadores para taxas agregadas.

Em um ambiente único, --capacity 1 com o padrão --drain-grace-sec 0, cada processo executor sai momentos após sua única sessão terminar. sessions_completed_total, sessions_failed_total e sessions_interrupted_total incrementam apenas no final da sessão, logo antes dessa saída, então uma raspagem Prometheus a cada 15 a 60 segundos raramente captura o incremento antes das séries do executor desaparecerem; esses três contadores de final de sessão são os contadores terminais que o resto desta seção se refere. sessions_started_total incrementa na geração e permanece visível pela vida da sessão, então aparece de forma confiável, mas em um ambiente único lê mais perto de "sessões em execução no momento" do que uma contagem cumulativa.

Use a série nesta tabela para o objetivo correspondente em vez dos contadores terminais:

Objetivo Use
Throughput claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}, um contador no orquestrador de longa vida que incrementa uma vez por hook spawn-runner bem-sucedido e permanece significativo sob rate(). Conta invocações de hook em vez de sessões, então pré-aquecimento e gerações repetidas para a mesma sessão divergem de contagens de sessão.
Utilização sum(claude_code_self_hosted_runner_active_sessions) contra sum(claude_code_self_hosted_runner_capacity), ambos medidores válidos em cada raspagem independentemente da vida útil do executor
Backlog claude_code_self_hosted_orchestrator_pool_pending_sessions para profundidade de fila, e claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions, alertando se acima de zero
Falhas claude_code_self_hosted_runner_sessions_failed_total, melhor esforço: crashes reais após geração incrementam, e rate() é significativo em executores que sobrevivem suas sessões com --drain-grace-sec acima de 0. Um ambiente único tem o mesmo problema de janela de raspagem que os outros contadores terminais, então trate qualquer valor diferente de zero que você veja como digno de investigação. Falhas antes de geração, como falha de hook de checkout, preparação git ou problema de token, aparecem apenas em session_init_errors_total.

As linhas orchestrator_* existem apenas em ambientes executando o orquestrador sob demanda. Em uma frota fixa cujos executores sobrevivem suas sessões, com --drain-grace-sec acima de 0, use sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) para throughput; em uma frota única essa série tem o mesmo problema de janela de raspagem que os contadores terminais, então confie na contagem de sessões enfileiradas em vez disso. Verifique backlog na aba Activity do ambiente, na página de administração Cloud environments: os executores não exportam uma série de profundidade de fila.

Para relatório de resultado por sessão, use o hook post-session em vez disso: ele dispara no final de cada sessão onde um processo filho foi gerado, exceto em caso de encerramento abrupto do executor, como uma preempção de VM, por contrato do próprio hook.

Próximos passos