Guia de início rápido de ambientes auto-hospedados
Configure seu primeiro ambiente auto-hospedado: instale Claude Code, crie o ambiente, inicie um runner e roteie uma sessão para ele.
Um ambiente auto-hospedado executa sessões na nuvem do Claude Code em infraestrutura que sua organização opera, executado por processos runner que você implanta. Este guia de início rápido configura seu primeiro, o menor que funciona: um runner em um único host, executando uma sessão de teste. Há duas etapas: criar o ambiente, iniciar um runner e rotear uma sessão para ele, depois enviar uma mensagem para essa sessão a partir do seu terminal. Você se moverá entre duas superfícies: claude.ai para criar o ambiente, verificar seu status e rotear uma sessão, e um terminal no host para tudo o que o runner faz.
Ao final, você terá um ambiente na página de administração Cloud environments, um runner pesquisando por trabalho e uma sessão em execução no seu host. Antes de conectar repositórios reais ou sistemas internos, trabalhe através de Implantar em produção, que cobre a postura de segurança, controle de egresso, credenciais git e orquestração.
Pré-requisitos
Organização e funções
O lado claude.ai precisa de:
- Permitir ambientes auto-hospedados ativado por um Proprietário na página de administração Cloud environments; o botão Novo não aparece até que esteja. Se você não tiver a função, alguém que tiver pode criar o ambiente e passar seu segredo para você; as etapas de runner e terminal nesta página não precisam de nenhuma função claude.ai, e onde uma etapa verifica o status na interface de administração, as próprias linhas de log do runner fornecem o mesmo sinal.
- Uma conexão GitHub para sua organização, para que os desenvolvedores possam escolher repositórios quando iniciarem sessões.
Host e rede
O host do runner precisa de:
- Um host ou container Linux ou macOS com HTTPS de saída para
api.anthropic.com, paraclaude.aie os hosts de download para os quais ele redireciona para a etapa de instalação abaixo, e para seu host git para o clone; a tabela de requisitos de rede tem a lista completa. Windows não é suportado como host de runner; execute o runner em um container Linux. Estações de trabalho de desenvolvedores não são afetadas, pois as sessões começam a partir de claude.ai em um navegador. - Um repositório para a sessão de teste: um público, ou um que este host já consiga clonar pela sua URL HTTPS sem que sejam solicitadas credenciais.
- Um relógio sincronizado com a hora real, por exemplo com NTP. A autenticação falha quando o relógio está mais de cinco minutos atrasado; consulte Troubleshooting.
Software no host do runner
Instale no host antes de começar:
- Claude Code v2.1.224 ou posterior, com qualquer um dos métodos de instalação padrão. O runner faz parte do binário
claudepadrão, e versões anteriores não reconhecem o subcomandoself-hosted-runner. O canallatestdo instalador nativo padrão carrega cada versão assim que é publicada; o canalstable, o cask Homebrewclaude-codee os repositórios apt, dnf e apk estáveis ficam para trás em cerca de uma semana. Para fixar a versão exata que sua frota executa, consulte Instalar uma versão específica. Para imagens de container, consulte o Dockerfile em Implantar em produção. - Git 2.24 ou mais recente. Algumas opções git na página de implantação precisam de versões mais recentes; Configurar git declara cada limite.
Confirme que o host está pronto:
claude self-hosted-runner --help
Um host pronto imprime o texto de uso do runner, listando sinalizadores como --environment-secret-file. Em versões anteriores a 2.1.224, o comando imprime a saída geral claude --help; atualize com claude update ou reinstale do canal latest.
Configurar um ambiente e runner
Use a configuração guiada ou as etapas manuais. A configuração guiada é um único comando que inicia uma sessão interativa do Claude Code e orienta você pelo restante. Use as etapas manuais em um host onde uma sessão interativa não seja possível. Use-as também quando alguém com a função Owner tiver criado o ambiente e entregado o segredo a você, já que a configuração guiada exige login de um Owner.
Executar a configuração guiada
A configuração guiada orienta você na criação do ambiente na interface de administração, inicia um runner local com o arquivo de segredo que você salva, confirma que o runner se registra e escreve uma folha de dicas em ./runner-setup/CHEAT-SHEET.md. Antes de executá-la, confirme seu login e sua versão:
- Login: execute-a em uma máquina onde você fez login com
claude auth loginusando uma conta que possui a função Owner. Com apenas uma chave de API ou um provedor de modelo de terceiros, a sessão é iniciada, mas as verificações de organização falham. - Versão: confirme que a verificação de versão passou. Em versões anteriores a 2.1.224, o comando setup inicia uma sessão Claude com as palavras como o prompt em vez da configuração guiada.
Para iniciar a configuração guiada, execute o subcomando setup no seu shell e siga os prompts:
claude self-hosted-runner setup
A configuração não inicia uma sessão de teste por conta própria: ela pede que você inicie uma em claude.ai/code. A última etapa da configuração para o runner que ela iniciou. Se você sair da configuração antes dessa etapa, o runner continua em execução. Para continuar após a última etapa, inicie o runner novamente no seu shell com o comando em ./runner-setup/CHEAT-SHEET.md e, em seguida, roteie uma sessão para o ambiente.
Configurar manualmente
Crie o ambiente em claude.ai, inicie o runner a partir de um terminal no host e depois retorne a claude.ai para confirmar que o runner aparece e rotear uma sessão para ele. Se alguém com a função Owner já tiver criado o ambiente e entregado o segredo a você, comece na etapa 2.
Criar um ambiente
Vá para a página Cloud environments nas configurações de administração. Em Ambientes auto-hospedados, selecione Novo, nomeie o ambiente e selecione Criar. Na segunda etapa do assistente, selecione Copiar chave de ambiente para copiar o segredo do ambiente, que a interface de administração rotula como uma chave de ambiente. claude.ai mostra o segredo uma vez, e você não pode recuperá-lo depois; ele expira 365 dias após a criação. O ID ccpool_... do ambiente permanece visível em seu diálogo de detalhes; você precisará dele para a verificação aud em verificação de token e para despachar sessões de teste a partir de CI.
Se você perder o segredo ou precisar rotacioná-lo, crie um novo segredo na guia Configuração do ambiente, implante o novo segredo em seus runners e revogue o antigo. Runners que possuem um segredo revogado falham em sua próxima pesquisa autenticada e saem, registrando poll auth failed, e seu orquestrador os reinicia com o novo segredo.
Iniciar um runner
Crie o diretório de segredo. Este comando e o próximo usam /etc/claude, que precisa de root, e o arquivo de segredo que eles criam é legível apenas pelo usuário que os executa. Se o runner for executado como outro usuário, ele sai com error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). Nesse caso, execute ambos os comandos como o usuário do runner, com um diretório no qual esse usuário possa escrever no lugar de /etc/claude, e passe o mesmo caminho para --environment-secret-file. Qualquer caminho que o processo do runner possa ler funciona.
mkdir -p /etc/claude
Escreva o segredo do ambiente em um arquivo. O comando abaixo lê do seu terminal para que o segredo fique fora do histórico do shell: cole o valor que você copiou, pressione Enter, depois Ctrl-D, e o umask do subshell torna o arquivo legível apenas por seu proprietário.
(umask 077 && cat > /etc/claude/environment-secret)
Escolha um diretório base, substituindo <writable-dir> no comando runner abaixo por um caminho absoluto que o runner possa escrever ou criar. O runner cria o diretório na inicialização, depois verifica repositórios e cria diretórios por sessão sob ele. Sem --base-dir ele usa /workspace, que só funciona se esse diretório já existe e é gravável ou você inicia o runner como root.
Se o runner não conseguir criar ou escrever no caminho, ele sai na inicialização com um erro nomeando o diretório em vez de se registrar. Consulte Troubleshooting.
Depois inicie o runner com --environment-secret-file e --base-dir:
claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
O runner registra Registered: runner_id=<runner-id> no log assim que se registra com seu ambiente e, em seguida, começa a pesquisar por trabalho. Se o runner sair mais tarde, reinicie-o você mesmo. Consulte Se o runner sair para saber quando isso acontece.
Verificar se o runner aparece
Retorne à página Cloud environments. O status do seu ambiente muda de Nenhum runner implantado para Saudável em alguns segundos após o runner iniciar; abra o ambiente e selecione Atividade para ver o runner em si. Se você não tiver acesso à página de administração, a linha Registered: runner_id=<runner-id> no log do runner da etapa anterior fornece o mesmo sinal.
Rotear uma sessão para o ambiente
Inicie uma sessão em claude.ai/code e selecione seu ambiente no seletor de ambiente, onde ambientes auto-hospedados aparecem ao lado dos hospedados pela Anthropic. Para o repositório, escolha o dos pré-requisitos: um repositório público ou um que este host já possa clonar. O runner clona com quaisquer credenciais git que o host já tenha.
O próximo runner disponível pega a sessão enfileirada e registra Picked up session <session-id> junto com sua contagem ativa e capacidade, para que você possa confirmar a partir da própria saída do runner qual host pegou a sessão. Observe a sessão funcionar e leia as respostas do Claude em claude.ai/code.
Se a sessão não começar a funcionar, compare com o que você vê:
- A sessão fica enfileirada: consulte Solução de problemas.
- A sessão falha ao iniciar com um erro do git: o erro aparece na sessão e no log do runner. Se ele incluir
could not read Username fordo git seguido da URL do seu host git, o runner não tinha credenciais HTTPS para esse host. Consulte Configurar git, que também cobre as opções de credencial para repositórios privados em produção.
Se o runner sair
Se o runner sair durante este guia de início rápido, inicie-o novamente com o mesmo comando. O runner pode sair por conta própria:
- Sessões concluídas: o log mostra
[runner:exit] account workload drained — exiting. O runner sai por design uma vez que suas sessões ativas terminam. Consulte Ciclo de vida do runner. - Perda de contato: o log mostra uma linha
[runner:fatal]comrunner record gone server-sideou compoll auth failed. Se o runner perder contato com a Anthropic por um tempo, por exemplo porque o host entra em suspensão, ele pode sair quando alcançar a Anthropic novamente.
Um turno concluído não encerra sua sessão de teste. Após o primeiro turno, a sessão ainda está anexada e o runner ainda está ativo, então você pode enviar uma mensagem de acompanhamento para a sessão sem reiniciar o runner primeiro.
Para produção, implante o runner sob um orquestrador que o reinicia na saída e aguarda mais tempo entre reinicializações quando o runner continua saindo logo após iniciar. Consulte Implantar em produção e Quando o runner sai.
Enviar uma mensagem de acompanhamento para uma sessão em execução
Depois que uma sessão está em execução no seu ambiente, envie um acompanhamento a partir do CLI claude em qualquer máquina onde você esteja conectado com claude auth login; o comando não precisa ser executado a partir da máquina que iniciou a sessão. O comando publica uma mensagem:
claude -p "your message" --cloud <session-id>
Para <session-id>, passe o ID session_... ou cse_... simples ou a URL claude.ai/code da sessão. Um envio bem-sucedido imprime Sent to cloud session. com o ID da sessão e um link de visualização. Formas de ID aceitas, saída JSON e os requisitos de conta e política estão em Enviar acompanhamentos a partir do CLI, pois o comando funciona da mesma forma contra sessões hospedadas pela Anthropic.
Próximos passos
- Implantar em produção: endureça a implantação, controle o egresso, configure credenciais git e execute a frota sob Kubernetes ou Compose
- Personalizar sessões: scripts wrapper, hooks de ciclo de vida, runners sob demanda, servidores MCP e permissões
- Testar de ponta a ponta: um teste de fumaça de CI que despacha uma sessão e lê as respostas do Claude