Skip to main content
Ambientes auto-hospedados estão em beta pública em planos Team e Enterprise; um Proprietário os habilita ativando Permitir ambientes auto-hospedados na página de administração Ambientes na nuvem. Esta página é a referência de sinalizadores e métricas; consulte o guia de início rápido para configuração e Implantar em produção para as receitas de frota.
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. 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:

​
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. 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:

​
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:
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: O orquestrador serve suas próprias séries em GET /metrics na mesma porta que seu /healthz: 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:
Essas regras de alerta de exemplo são um ponto de partida; ajuste os limites para o tamanho da sua frota:

​
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: 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