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.
  • 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, 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 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. O canal latest do instalador nativo padrão carrega cada versão assim que é publicada; o canal stable, o cask Homebrew claude-code e 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:
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

Claude Code inclui uma configuração guiada: uma sessão Claude Code interativa que o orienta 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. Execute-o em uma máquina onde você se conectou com claude auth login usando uma conta que possui uma função de Proprietário; não está disponível com chaves de API ou provedores de modelo de terceiros. Em hosts onde uma sessão interativa não é possível, use as etapas manuais abaixo. Confirme que a verificação de versão passou primeiro: em versões anteriores a 2.1.224, este comando inicia uma sessão Claude comum com as palavras como o prompt em vez da configuração guiada. Para iniciar a configuração guiada, execute o subcomando setup e siga os prompts:
Para configurar manualmente:
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. Esta etapa e a próxima precisam de root para o caminho /etc/claude; qualquer caminho que o processo runner possa ler funciona, então ajuste ambos os comandos e o valor --environment-secret-file juntos se você usar um diferente.
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.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. O runner se registra com seu ambiente e começa a pesquisar por trabalho. Se o runner sair, reinicie-o manualmente. Implantações de produção executam o runner sob um orquestrador que reinicia runners que saíram, normalmente com um sistema de arquivos fresco por reinicialização; Reutilizar um checkout pré-aquecido cobre a configuração de disco persistente suportada.
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.
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. O runner clona com quaisquer credenciais git que o host já tenha, então escolha um repositório que este host já possa clonar, ou um público; as opções de credencial para repositórios privados em produção estão em Configurar git. 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 ficar enfileirada, consulte Troubleshooting.
O runner sai por design uma vez que suas sessões ativas terminam; consulte Ciclo de vida do runner. Para produção, implante-o sob um orquestrador que o reinicia na saída. Consulte Implantar em produção.

​
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, requisitos de conta e política e a referência de erro 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