Skip to main content
Ambientes auto-hospedados estão em beta público em planos Team e Enterprise; Disponibilidade e limitações cobre o caminho de habilitação. Esta página coloca sua primeira sessão em execução; consulte Ambientes auto-hospedados para saber o que são e Implantar em produção para endurecimento e receitas de frota.
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.
  • O conector GitHub ativado por um Owner, e a própria conexão GitHub de cada desenvolvedor, para que possam escolher repositórios do github.com 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, para claude.ai e 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. Uma chave SSH sozinha não é suficiente, porque o runner clona a URL https:// do repositório. Para clonar via SSH, consulte Reescrever URLs git para redes privadas.
  • 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 claude padrão, e versões anteriores não reconhecem o subcomando self-hosted-runner. Um runner que atende sessões do Claude Tag precisa da v2.1.229 ou posterior e de python3 no seu PATH, já que os hooks que o plano de controle fornece para essas sessões executam python3. 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:
Um host pronto imprime o texto de uso do runner, listando flags como --environment-secret-file. Em versões anteriores a 2.1.224, o comando imprime a saída geral claude --help. Se você vir essa saída, atualize o Claude Code. Se você executa claude a partir de uma imagem de container, reconstrua a imagem com a versão 2.1.224 ou posterior.

​
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 login usando 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:
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.
1

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

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.
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.
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.
Use um diretório dedicado ao runner, não o seu diretório pessoal nem um diretório com seus próprios clones. O runner trata o que encontrar em <writable-dir>/<repo-owner>/<repo> como seu próprio clone e pode redefini-lo e sobrescrever ou excluir arquivos nele.
Se o runner não conseguir criar ou escrever no diretório base, ele sai na inicialização com um erro nomeando o diretório em vez de se registrar. Consulte Solução de problemas.Depois inicie o runner com --environment-secret-file e --base-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. Iniciado com este comando, ele sai por design após atender uma sessão, e não após cada turno. Para atender mais sessões, inicie o runner novamente cada vez que ele sair. Consulte Se o runner sair para saber quando isso acontece e o que o runner registra no log.
3

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

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 pela URL HTTPS sem que sejam solicitadas credenciais.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: se o erro incluir could not read Username for do git seguido da URL do seu host git, o runner não tinha credenciais HTTPS para esse host.
    • Fornecer credenciais HTTPS: consulte Configurar git
    • Clonar via SSH: se o host do runner já tiver uma chave SSH, consulte Reescrever URLs do git para redes privadas
    • Após qualquer uma das correções: inicie o runner novamente e observe a sessão que falhou em vez de iniciar uma nova. Se ela tiver falhado várias vezes, aguarde alguns minutos até que o runner registre Picked up session no log.
    • Para usar um repositório diferente: arquive ou exclua a sessão que falhou, depois inicie o runner novamente e inicie uma nova sessão. Caso contrário, o runner pode pegar a sessão que falhou em vez da nova.

​
Se o runner sair

Se o runner sair durante este guia de início rápido, inicie-o novamente. O runner pode sair por conta própria:
  • Nada mais em execução: o log mostra [runner:exit] account workload drained — exiting. O runner sai por design quando não está mais executando nenhuma sessão, por exemplo:
    • Você arquivou ou excluiu a sessão: inicie o runner novamente
    • A sessão falhou ao iniciar: corrija a causa e inicie o runner novamente
  • Perda de contato: o log mostra uma linha [runner:fatal] com runner record gone server-side ou com poll 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:
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