Configurar ambientes na nuvem

• O aplicativo Desktop
• O aplicativo móvel Claude
• Seu navegador em claude.ai/code
• O terminal com claude --cloud
• Tarefas agendadas na nuvem
• Claude Tag

​

O ambiente Default

• Fluxos CLI como /web-setup: criam Default para você
• Integração web em Pro e Max: cria Default para você
• Integração web em Team e Enterprise: mostra um formulário Criar seu primeiro ambiente na nuvem a menos que um Proprietário tenha ativado a Configuração rápida; mantenha os padrões do formulário e clique em Criar e concluir para obter o mesmo ambiente Default

• Acesso à rede Trusted: as sessões alcançam registros de pacotes e outros domínios na lista de permissões, e nada mais através da rede da sessão.
• Nenhuma outra configuração: Default não define variáveis de ambiente ou script de configuração, portanto as sessões começam apenas com as ferramentas pré-instaladas.

• No aplicativo Desktop, no aplicativo móvel e em claude.ai/code, as sessões que você inicia usam o ambiente mostrado no seletor. Um padrão da organização definido por um Proprietário preenche a seleção quando você não escolheu um. Threads em um projeto usam o ambiente definido nas configurações do projeto.
• A partir da CLI, Claude Code usa sua escolha /remote-env, ou volta para o ambiente hospedado pela Anthropic quando sua lista tem um, e caso contrário para o primeiro ambiente em sua lista que não é um ambiente bridge, uma entrada Remote Control registra para representar sua própria máquina em vez de um ambiente na nuvem. Para um ambiente auto-hospedado, passar --environment <environment-id> com seu ID ccpool_ quando você despacha uma sessão substitui a escolha /remote-env e o fallback para essa invocação. Claude Code rejeita IDs env_ hospedados pela Anthropic passados para a flag, portanto use /remote-env para direcioná-los. A flag requer Claude Code v2.1.224 ou posterior.

​

Configure seu ambiente

​

Defina variáveis de ambiente

NODE_ENV=development
LOG_LEVEL=debug
DATABASE_URL=postgres://localhost:5432/myapp

• A VM é restaurada após estar ociosa: após alguns minutos sem atividade, a VM de uma sessão pausa com seus arquivos salvos. Sua próxima mensagem restaura a mesma VM e inicia Claude Code novamente.
• A VM foi recuperada e é reconstruída: se a VM pausada foi recuperada, reabrindo a sessão provisiona uma VM nova.

​

Adicione segredos de rede

​

Requisitos

• Função: em planos Pro, Max e Team, você pode adicionar e excluir segredos em seus próprios ambientes, qualquer que seja sua função. Em Team e Enterprise, Proprietários têm uma função de administrador da organização em sua organização claude.ai e Administradores não, o que muda o que você vê nestes casos:
  • Seu próprio ambiente no Enterprise: com uma função de administrador da organização, você adiciona e exclui segredos. Sem ela, a linha Network secrets abre a lista de segredos com a nota “Only an organization admin can add or delete network secrets” e sem botão Add secret ou de exclusão. Peça a um Proprietário para adicionar o segredo a um ambiente compartilhado e depois execute suas sessões lá
  • Um ambiente compartilhado: Proprietários adicionam e excluem seus segredos nas configurações de administrador. Sem uma função de administrador da organização, peça a um Proprietário para adicionar o segredo, porque o diálogo do ambiente não tem a seção Network secrets
  • Seu próprio ambiente no Team: sem uma função de administrador da organização, Add secret abre um formulário mais curto que aceita um host
• Tipo de ambiente: um ambiente na nuvem hospedado pela Anthropic que já existe. Um ambiente auto-hospedado não tem segredos de rede
• Acessibilidade de API: a API aceita conexões da internet, porque as solicitações saem da rede da Anthropic
• Chaves de criptografia: se sua organização usa chaves de criptografia gerenciadas pelo cliente, você não pode salvar segredos de rede

​

Adicione um segredo

​

Adicione um segredo em um plano Team sem uma função de administrador da organização

• Host: o único host que recebe o segredo, como api.example.com. O formulário não aceita um curinga *.
• Name: um rótulo opcional para o segredo
• Secret type: Token para uma chave que viaja em um cabeçalho de requisição, ou Username and password. Para um token, cole a chave como o Value

​

Quais requisições recebem o segredo

​

Requisições que nunca recebem o segredo

• GitHub: o proxy do GitHub autentica requisições para o GitHub em vez disso, portanto você não precisa de um segredo de rede para isso
• A API Anthropic e registros de pacotes públicos: api.anthropic.com, registry.npmjs.org, jsr.io, npm.jsr.io, pypi.org, files.pythonhosted.org, index.crates.io e proxy.golang.org
• Solicitações de script de configuração: Claude Code se conecta ao proxy do agente quando é lançado, depois que o script de configuração foi executado
• Exportação de telemetria do Claude Code: Claude Code envia sua exportação de telemetria em si mesma em vez de através de um comando que executa, e essa solicitação não passa pelo proxy do agente

​

Selecione um ambiente a partir da CLI

​

Arquive um ambiente

• As sessões já em execução no ambiente continuam funcionando.
• O ambiente desaparece do seletor e de /remote-env, portanto você não pode escolhê-lo para novas sessões.
• Os segredos de rede no ambiente permanecem anexados em suas sessões em execução. Exclua qualquer um que você não queira mais antes de arquivar.
• Nenhuma nova sessão pode ser iniciada em um ambiente arquivado, em qualquer superfície:
  • Padrão CLI salvo: se o ambiente era seu padrão CLI salvo, Claude Code inicia sessões na nuvem da CLI no ambiente hospedado pela Anthropic quando sua lista tem um. Caso contrário, ele as inicia no primeiro ambiente em sua lista que não é um ambiente bridge Remote Control.
  • Configurado explicitamente: qualquer coisa configurada com o ambiente explicitamente, como uma tarefa agendada na nuvem, não pode iniciar novas sessões nele. Aponte-a para outro ambiente.

​

Ambientes compartilhados da organização

• Crie um ambiente compartilhado: use a página Cloud environments nas configurações de administrador, que é também onde Proprietários editam e arquivam ambientes compartilhados. Cada um tem um nome, um nível de acesso à rede, variáveis de ambiente no formato .env e um script de configuração.
• Compartilhe um ambiente pessoal: abra um de seus próprios ambientes para edição no seletor de ambiente, depois compartilhe-o a partir da linha Who can use it. O ambiente mantém seu ID, portanto sessões e tarefas agendadas que já o usam não são afetadas, e cada membro pode então vê-lo e iniciar sessões nele.

​

Defina o ambiente que um canal do Claude Tag usa

• Defina um ambiente compartilhado ou auto-hospedado como o ambiente padrão da organização em claude.ai/admin-settings/claude-code.
• Fixe um a um canal nas configurações de administrador do Claude Tag.

​

Acesso à rede

​

Níveis de acesso

• GitHub, através de seu proxy separado
• Conectores MCP que você ativa, cujo tráfego viaja através dos servidores da Anthropic
• Os hosts que você listou nos segredos de rede do ambiente, exceto os hosts que nunca recebem o segredo
• A API Anthropic, para as próprias solicitações do Claude Code, até mesmo em None, conforme observado em Segurança e isolamento

​

Permita domínios específicos

api.example.com
*.internal.example.com
registry.example.com

• Sessões neste ambiente abrem artefatos públicos de outra organização: Claude Code busca aqueles do host diretamente, portanto adicione-o a esta lista.
• Você está configurando a CLI local ou um executor auto-hospedado: mantenha o host nessa lista de permissões. Veja requisitos de acesso à rede e os requisitos de rede auto-hospedados.

​

Proxy do GitHub

• Credenciais do Git: o cliente git dentro da VM usa uma credencial com escopo, que o proxy verifica e troca por seu token real do GitHub.
• Solicitações de API: solicitações das ferramentas GitHub integradas e de gh sob o placeholder proxy-injected, saem com suas credenciais reais substituídas.
• Restrições de push: o proxy rejeita exclusões de branches e pushes de qualquer coisa que não seja um branch, como uma tag. Ele não limita quais branches um push pode atualizar. Para fazer isso, use regras de proteção de branch ou rulesets no GitHub.
• Escopo do repositório: o proxy atende requisições da API do GitHub para os repositórios anexados à sessão. Uma requisição de API para outro repositório recebe um 403 cuja mensagem começa com GitHub access to e contém is not enabled for this session. Um arquivo compactado do código-fonte que você busca por meio de uma URL github.com/{owner}/{repo}/archive/ ou codeload.github.com recebe esse mesmo 403 quando o repositório não está anexado, mesmo que seja público.
• Restrições de GraphQL: o proxy rejeita requisições ao endpoint de GraphQL do GitHub com um 403 cuja mensagem começa com GitHub GraphQL is not available from Claude Code sessions e nomeia o fallback REST, gh api repos/{owner}/{repo}/.... Os subcomandos gh que usam GraphQL, como gh pr e gh issue, recebem o mesmo 403. A restrição se aplica a cada requisição através do proxy independentemente das credenciais que você fornece, portanto um GH_TOKEN que você define recebe o mesmo 403. Claude não pode alcançar APIs do GitHub que existem apenas em GraphQL, como Projects v2, através do proxy.

​

Proxy de segurança

• Proteção contra solicitações maliciosas
• Limitação de taxa e prevenção de abuso

​

O que está disponível em sessões na nuvem

​

O que é transferido de sua configuração

​

Adicione preferências pessoais sem fazer commit no repositório

#!/bin/bash
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
Use conventional commit messages.
EOF

​

Ferramentas instaladas

​

Trabalhe com issues e pull requests do GitHub

• Se você definir um token, ele passa para o contêiner inalterado, portanto seus scripts e o gh CLI do GitHub usam-no diretamente.
• Se você não definir nenhum e o proxy do GitHub estiver manipulando a autenticação para sua sessão, ambas as variáveis leem como a string placeholder proxy-injected nos comandos que Claude executa, e o proxy substitui suas credenciais reais em requisições de saída do GitHub. As chamadas gh api para repositórios anexados funcionam sem um token seu, mas um script que lê GITHUB_TOKEN diretamente obtém o placeholder, não um token utilizável.

​

Vincule a saída de volta à sessão

echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

​

Execute testes, inicie serviços e adicione pacotes

​

Execute testes

​

Inicie serviços

service postgresql start

service redis-server start

​

Adicione pacotes

​

Limites de recursos

• 4 vCPUs
• 16 GB de RAM
• 30 GB de disco

​

Limites de tempo

• Comandos que Claude executa: um ambiente na nuvem não define seu próprio timeout de comando, portanto os padrões da ferramenta Bash se aplicam. Claude aguarda 2 minutos por um comando em foreground por padrão e pode pedir até 10 minutos. Quando um comando atinge seu timeout, Claude Code o move para o background em vez de pará-lo, a menos que o comando comece com sleep. Um comando movido dessa forma pode continuar executando por até 30 minutos a mais antes de Claude Code pará-lo em seu limite de tempo de background. Definir BASH_DEFAULT_TIMEOUT_MS acima de 1800000 milissegundos alonga esse limite bem como o padrão de foreground.
• Hooks SessionStart: Claude Code cancela um hook command após 600 segundos a menos que você defina timeout, em segundos, na entrada do hook. Claude Code não aplica o timeout em um hook que você executa com async: true.
• Script de configuração: um script que leva mais tempo do que aproximadamente cinco minutos não é armazenado em cache. Requisitos de script cobre como ficar abaixo disso.
• Sessões inativas: após alguns minutos sem atividade, a VM de uma sessão pausa com seus arquivos salvos, e uma VM pausada pode ser recuperada posteriormente. Defina variáveis de ambiente descreve o que uma sessão pega em cada caso, e Environment expired cobre como reabrir uma sessão cuja VM foi recuperada.

​

Scripts de configuração

​

Adicionar um script de configuração

#!/bin/bash
apt update && apt install -y shellcheck

​

Requisitos do script

• Saia com zero: se o script sair com não-zero, a sessão falha ao iniciar. Anexe || true a comandos não críticos para que uma falha de instalação intermitente não bloqueie a sessão.
• Termine em cinco minutos: mantenha o tempo de execução total do script em aproximadamente cinco minutos para que o cache do ambiente possa ser construído. Quando a configuração leva mais tempo do que isso, o ambiente não é armazenado em cache. Execute instalações independentes em paralelo com & e wait, e mova qualquer download único que não se encaixe em um hook SessionStart que o inicie em segundo plano. Se novas sessões travam ou expiram durante a configuração, veja Novas sessões travam ou expiram durante a configuração.
• Acesso à rede para instalações: as instalações de pacotes precisam alcançar registros. O nível Trusted padrão cobre registros de pacotes comuns incluindo npm, PyPI, RubyGems e crates.io; com acesso à rede None, as instalações falham.
• As variáveis do ambiente ainda não estão definidas: o script é executado antes de a sessão definir as variáveis de ambiente do ambiente. Defina no próprio script qualquer valor de que o script precise.

​

Cache do ambiente

​

Scripts de configuração vs. hooks SessionStart

• Ambiente hospedado pela Anthropic: Claude Code executa hooks das configurações gerenciadas pelo servidor de sua organização e, fora de uma thread de projeto, do repositório. As sessões Claude Tag não recebem configurações gerenciadas pelo servidor, portanto hooks de configurações gerenciadas pelo servidor não são executados lá.
• Ambiente auto-hospedado: Claude Code também executa os hooks que o operador semeou a partir do ~/.claude/ do host do executor, e os hooks no arquivo de configurações gerenciadas da imagem do executor quando esse arquivo é um das fontes gerenciadas que Claude Code aplica.

​

Instale dependências com um hook SessionStart

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash

if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR" || exit 1
hashes=node_modules/.install_pkgs.sha256

if ! sha256sum --check --status "$hashes" 2>/dev/null; then
  # Delete the old hashes first, so a failed install runs again next time
  rm -f "$hashes"
  if npm install; then
    sha256sum scripts/install_pkgs.sh package.json package-lock.json > "$hashes" || rm -f "$hashes"
  fi
fi

# pip skips requirements that are already satisfied
pip install -r requirements.txt
exit 0

​

Limitações em sessões na nuvem

• Um repositório por sessão: em um ambiente hospedado pela Anthropic, uma sessão com vários repositórios não carrega hooks de nenhum .claude/settings.json do repositório, portanto um hook SessionStart que você define lá não é executado. Instale dependências para essas sessões com um script de configuração em vez disso. Para um ambiente auto-hospedado, veja quais configurações do repositório se aplicam.
• Não nas threads na nuvem de um projeto: uma thread na nuvem em um projeto não executa hooks do .claude/settings.json de um repositório, qualquer que seja o número de repositórios. Em um ambiente hospedado pela Anthropic, instale dependências para threads com um script de configuração. Em um ambiente auto-hospedado, use um hook nas configurações do host do executor em vez disso.
• Sem escopo apenas na nuvem: os hooks são executados em sessões locais e na nuvem. Para pular a execução local, saia cedo a menos que a variável de ambiente CLAUDE_CODE_REMOTE seja true, da forma que o script de instalação de dependência faz.
• Requer acesso à rede: os comandos de instalação precisam alcançar registros de pacotes. Se seu ambiente usa acesso à rede None, esses hooks falham. A lista de permissões padrão em Trusted cobre npm, PyPI, RubyGems e crates.io.
• Compatibilidade de proxy: em ambientes hospedados pela Anthropic, todo o tráfego de saída passa por um proxy de segurança, e alguns gerenciadores de pacotes não funcionam corretamente com isso; Bun é um exemplo conhecido. Em um ambiente auto-hospedado, o tráfego de saída vai através de seu próprio limite de rede em vez disso.
• Adiciona latência de inicialização: os hooks são executados cada vez que uma sessão é iniciada ou retomada, ao contrário dos scripts de configuração que se beneficiam do cache do ambiente. Mantenha os scripts de instalação rápidos pulando o trabalho que já foi feito, da forma que o script de instalação de dependência faz.

​

Domínios permitidos padrão

​

Recursos relacionados

• Referência de sessões na nuvem: inicie, gerencie e compartilhe sessões na nuvem
• Guia de início rápido de sessões na nuvem: conecte GitHub e inicie sua primeira sessão na nuvem
• Claude Tag: as sessões que Claude inicia do Slack são executadas nos mesmos ambientes
• Tarefas agendadas na nuvem: as execuções agendadas usam os mesmos ambientes e níveis de acesso à rede
• Remote Control: execute sessões na rede e nos arquivos de sua própria máquina em vez disso
• Ambientes auto-hospedados: execute sessões na nuvem na infraestrutura própria de sua organização
• Hooks SessionStart: configuração confirmada no repositório que é executada em sessões locais e na nuvem
• Configurações gerenciadas pelo servidor: política da organização que alcança sessões na nuvem