63 63
64| Host | Porta | Quando necessário |64| Host | Porta | Quando necessário |
65| :- | :- | :- |65| :- | :- | :- |
66| `api.github.com` | 443 | Com ou sem `--use-anthropic-git-proxy`, quando a imagem do runner inclui a [GitHub CLI](#github-api-access-with-the-github-cli) e você fornece às sessões uma credencial do github.com, como um `GH_TOKEN` |
66| `downloads.claude.ai` | 443 | No tempo de instalação, quando você instala ou atualiza Claude Code no host com o instalador nativo; o próprio script `install.sh` é servido de `claude.ai`. No tempo de execução da sessão, apenas quando as sessões instalam plugins do marketplace oficial da Anthropic. |67| `downloads.claude.ai` | 443 | No tempo de instalação, quando você instala ou atualiza Claude Code no host com o instalador nativo; o próprio script `install.sh` é servido de `claude.ai`. No tempo de execução da sessão, apenas quando as sessões instalam plugins do marketplace oficial da Anthropic. |
67| `storage.googleapis.com` | 443 | No tempo de execução da sessão, para as contagens de instalação de plugin e metadados mostrados em `/plugin`. |68| `storage.googleapis.com` | 443 | No tempo de execução da sessão, para as contagens de instalação de plugin e metadados mostrados em `/plugin`. |
68| `code.claude.com` e `claude.com` | 443 | Buscas de documentação pelo agente claude-code-guide integrado e solicitações WebFetch pré-aprovadas durante sessões. Bloquear esses hosts apenas afeta buscas de documentação. |69| `code.claude.com` e `claude.com` | 443 | Buscas de documentação pelo agente claude-code-guide integrado e solicitações WebFetch pré-aprovadas durante sessões. Bloquear esses hosts apenas afeta buscas de documentação. |
167 168
168* O runner define `GIT_TERMINAL_PROMPT=0`, para que git não peça um nome de usuário ou senha.169* O runner define `GIT_TERMINAL_PROMPT=0`, para que git não peça um nome de usuário ou senha.
169* O runner executa SSH com `BatchMode=yes`, anexado ao seu `GIT_SSH_COMMAND` se você definir um, para que SSH não peça uma frase-passe ou confirmação de host.170* O runner executa SSH com `BatchMode=yes`, anexado ao seu `GIT_SSH_COMMAND` se você definir um, para que SSH não peça uma frase-passe ou confirmação de host.
170* O runner define `GCM_INTERACTIVE=never`, para que Git Credential Manager não abra um diálogo de login.171* O runner define `GCM_INTERACTIVE=never`, para que Git Credential Manager não abra um diálogo de login. Antes da v2.1.229, a preparação do repositório podia travar em um prompt do Git Credential Manager.
171* O runner limpa `core.askPass`, então se você usar um helper askpass, defina-o através da variável de ambiente `GIT_ASKPASS` em vez disso.172* O runner limpa `core.askPass`, então se você usar um helper askpass, defina-o através da variável de ambiente `GIT_ASKPASS` em vez disso.
172 173
173Se seu host git rejeitar a credencial, ou você não configurou uma, o runner tenta novamente algumas vezes e depois falha na preparação do repositório quando o repositório é aquele para o qual a sessão envia resultados. Para um repositório que a sessão apenas lê, [Troubleshooting](#troubleshooting) cobre quando o runner o pula em vez disso. O runner não passa essas configurações para o ambiente da sessão.174Se seu host git rejeitar a credencial, ou você não configurou uma, o runner tenta novamente algumas vezes e depois falha na preparação do repositório quando o repositório é aquele para o qual a sessão envia resultados. Para um repositório que a sessão apenas lê, [Troubleshooting](#troubleshooting) cobre quando o runner o pula em vez disso. O runner não passa essas configurações para o ambiente da sessão.
287* **`jq`**: instale `jq` na imagem se você quiser que `--jq` funcione288* **`jq`**: instale `jq` na imagem se você quiser que `--jq` funcione
288* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/pt/env-vars)**: se o ambiente da sessão a define, o Claude Code não fornece o `gh` integrado, e a sessão não tem `gh`289* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/pt/env-vars)**: se o ambiente da sessão a define, o Claude Code não fornece o `gh` integrado, e a sessão não tem `gh`
289 290
290Quando a imagem inclui o GitHub CLI, as sessões o usam.291#### Acesso à API do GitHub com o GitHub CLI
292
293Se a imagem do seu runner inclui o GitHub CLI para as sessões usarem, faça com que seu [script wrapper](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#provision-credentials-scoped-to-the-session-creator) crie um `GH_TOKEN` de curta duração e escopo mínimo por sessão para o criador da sessão. Quando `gh` está no `PATH` com o qual o Claude Code inicia, a sessão tem esse `gh` e nenhum [`gh` integrado](#github-api-access-without-the-github-cli). Com o token, esse `gh` alcança o GitHub com qualquer acesso que o token conceda e fora da git gerenciada pela Anthropic, então permita [`api.github.com`](#network-requirements).
294
295Com git gerenciada pela Anthropic, deixe o GitHub CLI fora da imagem para usar o `gh` integrado em vez disso.
291 296
292#### Confie em uma autoridade de certificado privada com git gerenciada pela Anthropic297#### Confie em uma autoridade de certificado privada com git gerenciada pela Anthropic
293 298
343 348
344A reescrita de host é executada primeiro, então liste o nome do host interno em `--git-ssh-rewrite` se você precisar de ambos. Para controle total sobre checkout, use um [hook de ciclo de vida `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout).349A reescrita de host é executada primeiro, então liste o nome do host interno em `--git-ssh-rewrite` se você precisar de ambos. Para controle total sobre checkout, use um [hook de ciclo de vida `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout).
345 350
351### Inicie uma sessão em um repositório fora do GitHub
352
353Para executar uma sessão em um repositório de um host git diferente do GitHub, inicie a sessão a partir do seu terminal, em um checkout desse repositório. Primeiro, verifique as credenciais git, a rede e o proxy git do runner, o endereço do repositório e o seu branch:
354
355* **Credenciais git e rede**: [forneça credenciais](#ship-git-config-in-your-image) que [funcionem sem um prompt](#git-must-work-without-a-prompt) para `https://<host>/<owner>/<name>`, o endereço que o runner clona, e permita que o runner alcance seu host git, conforme lista [Requisitos de rede](#network-requirements). Para um host git que aceita apenas SSH, consulte [`--git-ssh-rewrite`](#rewrite-git-urls-for-private-networks).
356* **Proxy git**: se os runners do ambiente usam o proxy git da Anthropic, [desative-o](#turn-the-anthropic-git-proxy-off).
357* **Endereço do repositório**: verifique o remote `origin` do checkout. O host dele deve ser um nome de domínio como `git.example.com`, e o caminho deve ter a forma `<owner>/<name>`. Um caminho aninhado como `group/subgroup/name` não é aceito.
358* **Branch**: faça push do branch em que você está para o seu host git, porque o runner clona esse branch.
359
360No checkout, com login feito em claude.ai conforme descrito em [Autenticar a partir de CI](https://code.claude.com/docs/pt/self-hosted-environments-testing.md#authenticate-from-ci), execute `claude -p` com [`--environment`](https://code.claude.com/docs/pt/self-hosted-environments-testing#run-the-test-loop) e o ID `ccpool_...` do seu ambiente:
361
362```bash theme={null}
363claude -p "Fix the login bug" --environment ccpool_abc123 --output-format json
364```
365
366Quando a sessão é criada, o comando imprime uma linha de JSON que começa com `{"ok":true`. Se o remote `origin` não se encaixar, o comando falha com `requires a git source, but no GitHub remote was detected`.
367
368Revise e mescle no seu host git os branches para os quais as sessões [fazem push](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work).
369
346## Construir a imagem do runner370## Construir a imagem do runner
347 371
348A Anthropic não publica uma imagem de runner pré-construída. Construa a sua própria em torno do binário `claude`, camadas em qualquer toolchain que seus repositórios precisem: runtimes de linguagem, compiladores, gerenciadores de pacotes, e sidecars [MCP](https://code.claude.com/docs/pt/mcp.md).372A Anthropic não publica uma imagem de runner pré-construída. Construa a sua própria em torno do binário `claude`, camadas em qualquer toolchain que seus repositórios precisem: runtimes de linguagem, compiladores, gerenciadores de pacotes, e sidecars [MCP](https://code.claude.com/docs/pt/mcp.md).
617 641
618### Permitir que os turnos em andamento terminem antes de uma reinicialização642### Permitir que os turnos em andamento terminem antes de uma reinicialização
619 643
620Para permitir que os turnos em andamento sejam concluídos antes de uma reinicialização contínua, defina `--drain-wait-sec` e aumente seu timeout de parada para pelo menos essa espera mais 80 segundos. Com a espera padrão de `0`, uma reinicialização interrompe qualquer turno ainda em andamento, e a sessão é retomada em outro runner sem seu [trabalho não enviado](#additional-limitations).644Para permitir que os turnos em andamento sejam concluídos antes de uma reinicialização contínua, defina `--drain-wait-sec` e aumente seu timeout de parada para pelo menos essa espera mais 80 segundos. Com a espera padrão de `0`, uma reinicialização interrompe qualquer turno ainda em andamento, e a sessão é retomada em outro runner sem seu [trabalho não enviado](#resumed-sessions-lose-unpushed-work).
621 645
622* **`--drain-wait-sec`**: aproximadamente a duração dos turnos e das tarefas em segundo plano que você deseja permitir que terminem. É um máximo: a espera termina antes se eles terminarem primeiro.646* **`--drain-wait-sec`**: aproximadamente a duração dos turnos e das tarefas em segundo plano que você deseja permitir que terminem. É um máximo: a espera termina antes se eles terminarem primeiro.
623* **Seu timeout de parada**: `terminationGracePeriodSeconds` no Kubernetes, `stop_grace_period` no Docker Compose. Por exemplo, com `--drain-wait-sec 120`, substitua o `90` na receita do [Kubernetes](#kubernetes) ou do [Docker Compose](#docker-compose) por `200`.647* **Seu timeout de parada**: `terminationGracePeriodSeconds` no Kubernetes, `stop_grace_period` no Docker Compose. Por exemplo, com `--drain-wait-sec 120`, substitua o `90` na receita do [Kubernetes](#kubernetes) ou do [Docker Compose](#docker-compose) por `200`.
735 759
736Para liberar sessões ociosas, inicie todos os runners com [`--release-idle-session-min`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags) e esse tempo em minutos, como `--release-idle-session-min 30`. O runner então libera qualquer sessão que permaneça ociosa por esse tempo, seja ela iniciada por uma tarefa agendada ou por uma pessoa, a menos que você [a mantenha para os processos que ela deixou em execução](#keep-an-idle-session-while-its-processes-run).760Para liberar sessões ociosas, inicie todos os runners com [`--release-idle-session-min`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags) e esse tempo em minutos, como `--release-idle-session-min 30`. O runner então libera qualquer sessão que permaneça ociosa por esse tempo, seja ela iniciada por uma tarefa agendada ou por uma pessoa, a menos que você [a mantenha para os processos que ela deixou em execução](#keep-an-idle-session-while-its-processes-run).
737 761
738* **Trabalho não enviado**: uma sessão liberada é retomada na sua próxima mensagem, sem o trabalho que ela não havia enviado com push. Para manter seus commits, consulte [Sessões retomadas perdem trabalho não enviado](#additional-limitations).762* **Trabalho não enviado**: uma sessão liberada é retomada na sua próxima mensagem, sem o trabalho que ela não havia enviado com push. Para manter seus commits, consulte [Sessões retomadas perdem trabalho não enviado](#resumed-sessions-lose-unpushed-work).
739* **Encerramento do runner**: um runner que libera sua última sessão inicia um [encerramento normal](#when-the-runner-exits). Faça com que seu supervisor o reinicie em um sistema de arquivos novo, conforme descrito em [Proteja sua implantação](#harden-your-deployment).763* **Encerramento do runner**: um runner que libera sua última sessão inicia um [encerramento normal](#when-the-runner-exits). Faça com que seu supervisor o reinicie em um sistema de arquivos novo, conforme descrito em [Proteja sua implantação](#harden-your-deployment).
740* **Sessões que nunca ficam ociosas**: defina também [`--kill-session-after-min`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags), porque [algumas sessões não contam como ociosas](#some-sessions-don’t-count-as-idle)764* **Sessões que nunca ficam ociosas**: defina também [`--kill-session-after-min`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags), porque [algumas sessões não contam como ociosas](#some-sessions-don’t-count-as-idle)
741 765
811* Se uma vez ainda está em execução, o runner aguarda a vez terminar, ou para a sessão aguardar seu usuário em seguida, e então a libera.835* Se uma vez ainda está em execução, o runner aguarda a vez terminar, ou para a sessão aguardar seu usuário em seguida, e então a libera.
812* Se a sessão ainda estiver no runner quando a janela de graça terminar, o runner a encerra, e qualquer trabalho de uma vez em execução é perdido. Uma vez aguardando uma aprovação solicitada de dentro de uma chamada de ferramenta em execução é uma maneira de uma sessão ultrapassar a janela.836* Se a sessão ainda estiver no runner quando a janela de graça terminar, o runner a encerra, e qualquer trabalho de uma vez em execução é perdido. Uma vez aguardando uma aprovação solicitada de dentro de uma chamada de ferramenta em execução é uma maneira de uma sessão ultrapassar a janela.
813 837
814Uma sessão liberada retoma de um clone fresco, então o trabalho que ela não tinha enviado se foi de qualquer forma; consulte [Sessões retomadas perdem trabalho não enviado](#additional-limitations). Antes da v2.1.260, o runner encerrava cada sessão no limite, após aguardar no máximo a janela de graça para uma vez em execução terminar.838Uma sessão liberada retoma de um clone fresco, então o trabalho que ela não tinha enviado se foi de qualquer forma; consulte [Sessões retomadas perdem trabalho não enviado](#resumed-sessions-lose-unpushed-work). Antes da v2.1.260, o runner encerrava cada sessão no limite, após aguardar no máximo a janela de graça para um turno em execução terminar.
815 839
816Defina o sinalizador acima de sua sessão mais longa esperada, como `--kill-session-after-min 480` para 8 horas. Para liberar slots de conversas que ficam ociosas, use `--release-idle-session-min` em vez disso.840Defina o sinalizador acima de sua sessão mais longa esperada, como `--kill-session-after-min 480` para 8 horas. Para liberar slots de conversas que ficam ociosas, use `--release-idle-session-min` em vez disso.
817 841
842### Sessões retomadas perdem trabalho não enviado
843
844Uma sessão retomada em um runner novo perde o trabalho que não tinha enviado, porque esse runner clona o repositório novamente a partir de seu branch inicial.
845
846Para manter o trabalho com commit, defina [`--push-outcome-on-release`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags) em todos os runners do ambiente. Um runner com a flag faz um push de melhor esforço dos branches de resultado da sessão antes de liberá-la, e a sessão retomada começa a partir desses commits. Um runner sem ela retoma a sessão a partir de seu branch inicial. O push usa as próprias credenciais git do host do runner, inclusive em um runner que usa [git gerenciado pela Anthropic](#use-the-anthropic-git-proxy).
847
848> [!WARNING]
849>
850> Antes de definir a flag, restrinja quem pode fazer push para refs `claude/*` no remoto de origem. Na retomada, o runner busca o branch previamente enviado sem verificar quem o enviou.
851
852Mesmo com a flag definida, salve este trabalho de outra forma:
853
854* **Alterações sem commit**: estas ainda são perdidas. Consulte [Solicitar que as sessões enviem seu trabalho](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work).
855* **Repositórios obtidos por meio de um [hook de ciclo de vida `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout)**: estes não recebem push. Faça um snapshot deles a partir do [hook `post-session`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session).
856* **Commits em uma sessão que alguém arquiva ou exclui, ou cujo runner alguém libera a partir do menu da sessão**: não conte com o push da flag. Para salvá-los, faça push de `HEAD` para um branch de resgate a partir de um [hook `post-session`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session). O exemplo ali faz push apenas após um commit de snapshot, então faça o seu fazer push mesmo quando não houver nada sem commit.
857
818### Limitações adicionais858### Limitações adicionais
819 859
820* **Sessões retomadas perdem trabalho não enviado**: um runner novo clona o repositório novamente a partir de seu branch inicial, então o trabalho que a sessão não tinha enviado se foi.
821 * **Para manter trabalho com commit**: defina [`--push-outcome-on-release`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags) em todos os runners do ambiente, porque um runner sem a flag retoma a sessão a partir de seu branch inicial. Um runner com a flag faz um push de melhor esforço dos branches de resultado da sessão antes de liberá-la, e a sessão retomada começa a partir desses commits. O push usa as próprias credenciais git do host do runner, inclusive em um runner que usa [git gerenciado pela Anthropic](#use-the-anthropic-git-proxy).
822 * **Com um hook `checkout`**: repositórios obtidos por meio de um [hook de ciclo de vida `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout) não recebem push. Em vez disso, faça um snapshot deles a partir do [hook `post-session`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session).
823 * **Antes de habilitar a flag**: restrinja quem pode fazer push para refs `claude/*` no remoto de origem. Na retomada, o runner busca o branch previamente enviado sem verificar quem o enviou.
824 * **Alterações sem commit ainda são perdidas**: para solicitar que Claude faça commit e push quando terminar de responder, consulte [Solicitar que as sessões enviem seu trabalho](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)
825* **Um comando interrompido por um runner perdido pode ser executado novamente**: quando a sessão é retomada em outro runner, Claude vê a chamada de ferramenta interrompida com um resultado informando que seu desfecho é desconhecido.860* **Um comando interrompido por um runner perdido pode ser executado novamente**: quando a sessão é retomada em outro runner, Claude vê a chamada de ferramenta interrompida com um resultado informando que seu desfecho é desconhecido.
826* **Um repositório adicionado no meio da sessão pode falhar ao ser clonado**: Claude o clona com `git clone` via HTTPS. Em um runner sem [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), o clone falha com um erro de autenticação do git se nada no host puder ler o repositório. Sempre que possível, selecione cada repositório que a sessão precisa quando você a cria.861* **Um repositório adicionado no meio da sessão pode falhar ao ser clonado**: Claude o clona com `git clone` via HTTPS. Em um runner sem [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), o clone falha com um erro de autenticação do git se nada no host puder ler o repositório. Sempre que possível, selecione cada repositório que a sessão precisa quando você a cria.
827 * **Quando a sessão é retomada**: um [hook `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout) também é executado para o repositório adicionado, com [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout) vazio, então faça seu hook lidar com isso.862 * **Quando a sessão é retomada**: um [hook `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout) também é executado para o repositório adicionado, com [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout) vazio, então faça seu hook lidar com isso.
828* **Alguns conectores não aparecem em sessões auto-hospedadas**: um conector que você ainda não conectou nas Configurações do claude.ai não está listado em uma sessão auto-hospedada, e a sessão não o solicitará para conectar. Conecte-o nas Configurações primeiro, depois inicie uma sessão fresca. Adicionar um conector a uma sessão já em execução também não torna suas ferramentas disponíveis para Claude; inicie uma sessão fresca para pegar um conector recém-adicionado.863* **Alguns conectores não aparecem em sessões auto-hospedadas**: um conector que você ainda não conectou nas Configurações do claude.ai não está listado em uma sessão auto-hospedada, e a sessão não o solicitará para conectar. Conecte-o nas Configurações primeiro, depois inicie uma sessão fresca. Adicionar um conector a uma sessão já em execução também não torna suas ferramentas disponíveis para Claude; inicie uma sessão fresca para pegar um conector recém-adicionado.
829* **Quando alguém arquiva ou exclui uma sessão, ou libera seu runner a partir do menu da sessão**: não conte com o push de [`--push-outcome-on-release`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags). Para salvar commits nesses casos, faça push de `HEAD` para um branch de resgate a partir de um [hook `post-session`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session). Se você partir do exemplo ali, faça-o fazer push mesmo quando não houver nada sem commit, porque ele faz push apenas após um commit de snapshot.
830 864
831### Relatar um problema865### Relatar um problema
832 866
