Configurar ambientes na nuvem

Configure ambientes na nuvem para sessões na nuvem do Claude Code: níveis de acesso à rede, variáveis de ambiente, scripts de configuração e cache de ambiente.

Cada sessão na nuvem é executada em um ambiente na nuvem. Você pode configurar um ambiente para permitir ou negar acesso à rede, definir variáveis de ambiente para a sessão, em planos Pro e Max armazenar credenciais de API que as sessões usam sem vê-las, e executar um script de configuração antes de Claude começar a trabalhar.

Os mesmos ambientes se aplicam em qualquer lugar onde você inicie uma sessão na nuvem: o aplicativo Desktop, o aplicativo móvel Claude, seu navegador em claude.ai/code, o terminal com claude --cloud, rotinas e Claude Tag. Cada uma dessas superfícies também pode rotear para um ambiente auto-hospedado. Disponibilidade e limitações cobre o que Claude ainda não pode usar quando uma sessão do Claude Tag é executada em um.

O ambiente Default

Se você ainda não tem um ambiente, a integração configura o ambiente Default para você. Como depende de onde você se integra:

• 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 Configuração rápida da web; mantenha os padrões do formulário e clique em Criar e concluir para obter o mesmo ambiente Default

Default não carrega nenhuma configuração própria:

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

Com apenas Default disponível, cada sessão é executada nele. Quando você tem mais de um ambiente, as sessões escolhem um por superfície:

• 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 um ambiente quando o padrão não for suficiente: quando Claude precisa alcançar domínios fora da lista de permissões padrão, precisa de variáveis de ambiente definidas para suas sessões, ou precisa de dependências instaladas antes de começar a trabalhar.

Configure seu ambiente

Crie, edite e arquive ambientes a partir do seletor de ambiente, que você acessa em claude.ai/code após a integração web, ou a partir da caixa de prompt no aplicativo Desktop. Os ambientes que você cria são pessoais para sua conta; ambientes compartilhados criados por um Proprietário aparecem no mesmo seletor. Veja Ferramentas instaladas para saber o que está disponível sem nenhuma configuração.

1

Abra o seletor de ambiente

Em claude.ai/code, selecione o ícone de nuvem mostrando o nome do ambiente atual, na linha acima da caixa de mensagem. Não há página de configurações ou URL direto para o seletor.

2

Adicione ou edite um ambiente

Selecione Add cloud environment, ou passe o mouse sobre um ambiente existente e selecione o ícone de configurações que aparece à direita. O diálogo inclui o nome, nível de acesso à rede, variáveis de ambiente e script de configuração. Quando você edita um ambiente na nuvem existente em um plano Pro ou Max, o diálogo também inclui credenciais de API.

Defina variáveis de ambiente

As variáveis de ambiente usam o formato .env, um par KEY=value por linha. Valores simples não precisam de aspas, e se você colocar um valor entre aspas com um par correspondente, as aspas não se tornam parte do valor. Coloque entre aspas um valor que abrange várias linhas ou contém um #: em um valor sem aspas, # inicia um comentário e o resto da linha é descartado.

O exemplo a seguir define três variáveis.

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

Cada sessão copia os valores do ambiente uma vez, na inicialização, em variáveis de ambiente ordinárias que qualquer comando que Claude execute pode ler. Como as sessões em execução não releem a configuração, editar ou adicionar variáveis afeta as sessões que você inicia depois; as sessões já em execução mantêm os valores com os quais começaram.

Uma sessão na nuvem também define algumas variáveis em si mesma quando inicia. Para CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, o valor que a sessão define substitui um que você adiciona aqui, portanto adicionar essa chave aqui não tem efeito.

Qualquer pessoa que use o ambiente pode ler os valores. Em planos Pro e Max, use uma credencial de API em vez disso para uma chave que o proxy do agente pode anexar a uma solicitação. As solicitações que nunca recebem uma credencial estão listadas lá.

Adicione credenciais de API

Uma credencial de API é uma chave de API ou token que você armazena em um ambiente na nuvem para que Claude possa chamar essa API de qualquer sessão no ambiente sem ver a chave. O proxy do agente da Anthropic adiciona a chave às solicitações para os hosts que você lista, depois que cada solicitação sai da VM da sessão. A chave nunca alcança Claude, os comandos que ele executa, ou as variáveis de ambiente da sessão.

As credenciais de API estão disponíveis em planos Pro e Max. Elas ainda não estão disponíveis em planos Team ou Enterprise, portanto a seção API credentials não aparece no diálogo de ambiente nesses planos.

Requisitos

Dois destes decidem se você pode adicionar uma credencial, e dois decidem se o proxy do agente pode usá-la uma vez adicionada:

• Função: uma função de administrador da organização em sua organização claude.ai
  • Em Team e Enterprise, Proprietários a mantêm e Administradores não
  • Em Pro e Max, você a mantém em sua própria organização
  • Sem ela, você vê uma nota em vez da lista de credenciais, até mesmo em seus próprios ambientes. Peça a um Proprietário para adicionar a credencial a um ambiente compartilhado e execute suas sessões lá
• Tipo de ambiente: um ambiente na nuvem hospedado pela Anthropic que já existe. Um ambiente auto-hospedado não tem credenciais de API
• 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 credenciais

Adicione uma credencial

Você adiciona credenciais uma de cada vez a partir do editor de um ambiente que já existe. O diálogo para um novo ambiente não as oferece. Também não há edição. Para alterar os hosts ou o valor de uma credencial, delete-a e adicione-a novamente.

Para confirmar que a credencial funciona, inicie uma sessão no ambiente e peça a Claude para chamar a API, por exemplo com curl. A API responde como se a chave estivesse na solicitação, e a chave não aparece nas variáveis de ambiente da sessão ou em nenhum arquivo. Se a lista marca uma credencial Not sent em vez disso, a nota abaixo dela diz por quê e o que fazer. Duas credenciais cujos hosts se sobrepõem sem corresponder exatamente não recebem nenhum marcador, e o proxy do agente envia apenas uma delas.

Quais solicitações recebem a credencial

O proxy do agente anexa uma credencial a uma solicitação quando o host da solicitação corresponde a um que você listou nessa credencial. As sessões podem alcançar esses hosts mesmo quando o nível de acesso à rede do ambiente não permitiria de outra forma, exceto os hosts que nunca recebem a credencial. A credencial se aplica em cada sessão que é executada no ambiente, quem quer que a tenha iniciado, até você deletá-la.

Solicitações que nunca recebem a credencial

O proxy do agente nunca anexa uma credencial que você adiciona a estas solicitações:

• GitHub: o proxy do GitHub autentica solicitações para GitHub em vez disso, portanto você não precisa de uma credencial de API 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

Selecione um ambiente a partir da CLI

Execute /remote-env em seu terminal para escolher o ambiente padrão para sessões na nuvem que você cria a partir da CLI, como claude --cloud. O comando abre um seletor de seus ambientes existentes e salva sua escolha na chave remote.defaultEnvironmentId em suas configurações de usuário, portanto se aplica em cada projeto em sua máquina até você alterar, a menos que a mesma chave seja definida em uma camada de configurações de precedência mais alta, como as configurações do projeto de um repositório.

Um ID de ambiente auto-hospedado, que tem a forma ccpool_..., segue uma regra de origem mais rigorosa. Veja remote.defaultEnvironmentId para as camadas de configurações que Claude Code honra isso.

/remote-env apenas define o padrão: não inicia uma sessão e não pode adicionar ou editar ambientes. Gerencie-os a partir do seletor de ambiente.

Arquive um ambiente

Para arquivar um de seus próprios ambientes, abra-o para edição e selecione Archive. Um Proprietário arquiva um ambiente compartilhado a partir da página Cloud environments nas configurações de administrador. Você não pode excluir um ambiente, apenas arquivá-lo.

O arquivamento afeta novas sessões, não as em execução:

• 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.
• As credenciais de API no ambiente permanecem anexadas em suas sessões em execução. Delete qualquer uma que você não queira mais antes de arquivar.
• Nenhuma nova sessão pode ser iniciada em um ambiente arquivado, em qualquer superfície. 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, e caso contrário no primeiro ambiente em sua lista que não é um ambiente bridge Remote Control. Qualquer coisa configurada com o ambiente explicitamente, como uma rotina, não pode iniciar novas sessões nele. Aponte-a para outro ambiente.

Ambientes compartilhados da organização

Em planos Team e Enterprise, um Proprietário pode criar ambientes na nuvem que são compartilhados com cada membro da organização. O mesmo papel gerencia tudo mais na página Cloud environments do administrador, incluindo ambientes auto-hospedados; a função Admin não pode abrir a página. A lista completa de funções que podem abrir é a para gerenciar configurações gerenciadas pelo servidor.

Os ambientes compartilhados aparecem no seletor de ambiente de cada membro sob um cabeçalho Organization, depois dos ambientes pessoais do membro sob Personal, portanto uma equipe pode padronizar uma configuração em vez de cada membro recriá-la. Selecionar o ícone de configurações de um ambiente compartilhado lá abre um resumo somente leitura de sua configuração para cada membro, Proprietários inclusos.

Um Proprietário disponibiliza um ambiente para a organização de uma de duas maneiras:

• 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 rotinas que já o usam não são afetadas, e cada membro pode então vê-lo e iniciar sessões nele.

Os Proprietários escolhem o ambiente padrão da organização separadamente, em claude.ai/admin-settings/claude-code.

Cada sessão de membro em um ambiente compartilhado lê suas variáveis, portanto não inclua segredos nelas. Credenciais de API, que dão às sessões uma chave que elas não podem ler, ainda não estão disponíveis em planos Team ou Enterprise.

Defina o ambiente que um canal do Claude Tag usa

Em canais do Claude Tag, Claude trabalha como a identidade compartilhada de sua organização, não como qualquer membro, portanto as sessões de canal usam ambientes no nível da organização apenas, seja ambientes compartilhados ou ambientes auto-hospedados. Para dar a um canal uma cadeia de ferramentas que não é pré-instalada, como .NET, um Proprietário pode criar um ambiente compartilhado a partir da página Cloud environments do administrador com um script de configuração que a instala. Aponte o canal para um ambiente de uma de duas maneiras:

• 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

Cada ambiente define um nível de acesso à rede, que controla as conexões de saída que suas sessões podem fazer. O nível padrão, Trusted, permite registros de pacotes e outros domínios na lista de permissões; Custom usa sua própria lista de domínios.

Para alterar o acesso à rede de um ambiente, abra-o para edição e use o seletor Network access no diálogo. Um ambiente compartilhado abre como somente leitura lá, portanto um Owner altera seu acesso à rede a partir da página Cloud environments nas configurações de administrador. O ícone de nuvem que abre o seletor aparece nas superfícies do aplicativo listadas em O ambiente Default e no editor de rotina; os ambientes pessoais não têm uma página separada nas configurações de sua conta claude.ai.

Níveis de acesso

O campo Network access no diálogo de ambiente usa um de quatro níveis:

Qualquer que seja o nível que você escolha, as sessões ainda podem alcançar estes, porque cada um usa um caminho que não passa pela lista de permissões de rede da sessão:

• 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 nas credenciais de API do ambiente, exceto os hosts que nunca recebem a credencial
• 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

Para permitir domínios que não estão na lista Trusted, selecione Custom nas configurações de acesso à rede do ambiente, depois liste um domínio por linha no campo Allowed domains. Este exemplo permite três hosts que um projeto interno pode precisar.

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

As sessões neste ambiente agora podem alcançar api.example.com, qualquer subdomínio de internal.example.com e registry.example.com, e nenhum outro domínio através da rede da sessão. Tráfego do GitHub, tráfego do conector MCP e solicitações para os hosts das credenciais de API do ambiente, outros que os hosts que nunca recebem a credencial, não passam por essa lista de permissões. Um *. inicial corresponde a cada subdomínio. Para manter também os domínios Trusted, marque Also include default list of common package managers; deixe desmarcado para permitir apenas o que você listar.

Se sua organização usa artefatos, você não precisa de *.frame.claudeusercontent.com na lista para as sessões lerem. Quando a lista deixa esse host de fora, Claude Code lê o conteúdo do artefato através da conexão da sessão com a Anthropic em vez disso. Mantenha o host em uma lista de permissões em duas situações:

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

Cada ambiente tem sua própria lista de domínios permitidos; não há uma lista de permissões no nível da organização que os administradores possam enviar para os ambientes de cada membro. As configurações gerenciadas pelo servidor ainda se aplicam dentro de sessões na nuvem, mas nenhuma delas adiciona domínios à lista de permissões de rede do ambiente. Para dar a um time uma lista padrão, um Owner pode criar um ambiente compartilhado pela organização com acesso à rede Custom e essa lista.

Proxy do GitHub

Em ambientes hospedados pela Anthropic, todas as operações do GitHub passam por um proxy dedicado que mantém suas credenciais reais do GitHub fora da VM da sessão, independentemente do nível de acesso do ambiente. As sessões em um ambiente auto-hospedado autenticam operações git com credenciais que sua implantação fornece; Configurar git cobre as opções, incluindo credenciais cunhadas por sessão e uma opção de entrada para este mesmo proxy. O proxy fornece:

• 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.
• Proteção de push: git push funciona apenas contra o branch de trabalho atual da sessão; clonagem, busca e operações de PR funcionam normalmente.
• Escopo do repositório: as solicitações de API do GitHub e de ativos de lançamento alcançam apenas repositórios anexados à sessão, portanto um script de configuração que baixa ativos de lançamento de um repositório não anexado recebe um 403.
• Restrições de GraphQL: o proxy serve apenas um conjunto fixado de operações de GraphQL para fluxos de trabalho de solicitação de pull. O proxy rejeita tudo mais no endpoint de GraphQL com um 403 que diz This GraphQL query is not enabled for this session e nomeia o fallback REST, gh api repos/{owner}/{repo}/.... A restrição se aplica a cada solicitaçã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.

Os arquivos confirmados de repositórios públicos chegam através de raw.githubusercontent.com, que o proxy de segurança manipula em vez disso. Esse domínio está na lista Trusted padrão, portanto esses arquivos permanecem acessíveis a menos que o nível de acesso do ambiente os exclua.

Proxy de segurança

As sessões na nuvem em ambientes hospedados pela Anthropic são executadas atrás de um proxy de rede HTTP/HTTPS para fins de segurança e prevenção de abuso; em um ambiente auto-hospedado, o tráfego de saída sai através de seu próprio limite de rede em vez disso. Todo o tráfego de internet de saída de uma sessão hospedada pela Anthropic passa por esse proxy, que fornece:

• Proteção contra solicitações maliciosas
• Limitação de taxa e prevenção de abuso
• Filtragem de conteúdo para segurança aprimorada
• Uma trilha de auditoria no nível de DNS dos nomes de host solicitados

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

Em ambientes hospedados pela Anthropic, cada sessão obtém uma máquina virtual (VM) fresca executando Ubuntu 24.04 em x86_64, independentemente de seu próprio sistema operacional e arquitetura de CPU, com seu repositório clonado e cadeias de ferramentas comuns pré-instaladas. Quando uma dependência fornece binários pré-compilados, como gems Ruby com extensões nativas ou wheels Python pré-construídos, use sua compilação x86_64 Linux para corresponder à VM. Esta seção cobre os padrões hospedados pela Anthropic, as ferramentas GitHub integradas, como executar testes e serviços e os limites de recursos que cada VM obtém.

O que é transferido de sua configuração

As sessões na nuvem começam a partir de um clone fresco de seu repositório. Qualquer coisa que você confirme no repositório está disponível. Qualquer coisa que você tenha instalado ou configurado apenas em sua própria máquina não está disponível na sessão. A política de sua organização chega separadamente através das configurações gerenciadas pelo servidor.

Para disponibilizar sua própria configuração em sessões na nuvem, confirme-a no repositório.

Qualquer pessoa que use o ambiente pode ler suas variáveis de ambiente e script de configuração. A nota do diálogo em Environment variables diz isso e avisa contra colocar segredos lá. Em planos Pro e Max, armazene uma chave que o proxy do agente pode anexar como uma credencial de API em vez disso.

Ferramentas instaladas

As sessões na nuvem vêm com tempos de execução de linguagem comuns, ferramentas de compilação e bancos de dados pré-instalados. A tabela abaixo resume o que está incluído por categoria.

¹ Bun está instalado mas tem problemas de compatibilidade de proxy conhecidos para busca de pacotes.

Para obter as versões da maioria das ferramentas nesta tabela, peça a Claude para executar check-tools em uma sessão na nuvem. É um comando shell instalado na VM da sessão, não um comando que você digita com /; você pede a Claude porque Claude executa todos os comandos da VM para você. Para uma ferramenta que não relata, como Ruby, PHP, bun, PostgreSQL ou Redis, peça a Claude para executar o comando de versão próprio da ferramenta, por exemplo psql --version.

As versões do Node.js estão instaladas em /opt/node20, /opt/node21 e /opt/node22, com 22 em PATH por padrão. Para trabalhar com uma versão diferente, peça a Claude para prepender o diretório bin dessa versão, como /opt/node20/bin, a PATH.

As cadeias de ferramentas fora dessa lista, como o SDK .NET, não estão pré-instaladas mesmo quando seus registros de pacotes estão na lista de permissões padrão. Instale-as com um script de configuração.

Trabalhe com problemas e solicitações de pull do GitHub

As sessões na nuvem incluem ferramentas GitHub integradas que permitem a Claude ler problemas, listar solicitações de pull, buscar diffs e postar comentários sem nenhuma configuração. Essas ferramentas se autenticam através do proxy do GitHub usando qualquer método que você configurou em opções de autenticação do GitHub, portanto seu token nunca entra no contêiner.

Você pode definir GH_TOKEN ou GITHUB_TOKEN você mesmo nas configurações de ambiente, ou deixar ambos não definidos e deixar o proxy do GitHub autenticar para você:

• 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 solicitações de saída do GitHub. gh funciona sem um token seu, mas um script que lê GITHUB_TOKEN diretamente obtém o placeholder, não um token utilizável.

Um token que você define é uma variável de ambiente ordinária, portanto qualquer pessoa que use o ambiente pode lê-lo; o caminho do proxy mantém a credencial fora da configuração do ambiente e da VM da sessão.

Para verificar qual caso se aplica à sua sessão, peça a Claude para executar echo $GH_TOKEN.

O gh CLI do GitHub está pré-instalado. Se você precisar de um comando gh que as ferramentas integradas não cobrem, como gh release ou gh workflow run, peça a Claude para executá-lo. gh lê GH_TOKEN automaticamente, portanto você não precisa executar gh auth login.

Vincule a saída de volta à sessão

Cada sessão na nuvem tem uma URL de transcrição em claude.ai, e a sessão pode ler seu próprio ID a partir da variável de ambiente CLAUDE_CODE_REMOTE_SESSION_ID. Use isso para colocar um link rastreável em corpos de PR, mensagens de commit, posts do Slack ou relatórios gerados para que um revisor possa abrir a execução que os produziu.

Os commits que Claude cria em uma sessão na nuvem incluem um trailer git Claude-Session: <url>, e os corpos de PR incluem a URL da sessão em sua própria linha. Para omitir o trailer e o link do corpo de PR, defina attribution.sessionUrl como false.

Para incluir o link da sessão em algo diferente de um commit ou PR, como uma mensagem do Slack que Claude posta ou um arquivo de relatório que ele escreve, peça a Claude para executar o seguinte comando e use sua saída. O comando converte o prefixo cse_ no valor da variável de ambiente para o prefixo session_ que a URL de transcrição espera:

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

Execute testes, inicie serviços e adicione pacotes

Você não obtém um shell na VM da sessão. Claude executa cada comando para você, portanto expresse as tarefas nesta seção como solicitações em seu prompt.

Execute testes

Claude executa testes como parte do trabalho em uma tarefa. Peça por isso em seu prompt, como "corrigir os testes falhando em tests/" ou "executar pytest após cada alteração." Os executores de teste que vêm com as cadeias de ferramentas pré-instaladas, como pytest e cargo test, funcionam sem configuração adicional. Um executor que seu projeto declara como uma dependência, como jest, instala com suas dependências.

Inicie serviços

PostgreSQL e Redis estão pré-instalados mas não estão em execução por padrão. Peça a Claude para iniciar o que você precisar; os comandos que ele executa são:

service postgresql start

service redis-server start

Docker está disponível para executar serviços em contêiner. Peça a Claude para executar docker compose up para iniciar os serviços do seu projeto. O acesso à rede para puxar imagens segue o nível de acesso do seu ambiente, e os padrões Trusted incluem Docker Hub e outros registros comuns.

Se suas imagens forem grandes ou lentas para puxar, adicione docker compose pull ou docker compose build ao seu script de configuração. O cache do ambiente mantém as imagens puxadas, portanto cada nova sessão as tem no disco. O cache armazena apenas arquivos, não processos em execução, portanto Claude ainda inicia os contêineres cada sessão.

Adicione pacotes

Para adicionar pacotes que não estão pré-instalados, use um script de configuração. O cache do ambiente mantém o que o script instala, portanto os pacotes que você instala lá estão disponíveis no início de cada sessão sem reinstalar cada vez. Você também pode pedir a Claude para instalar pacotes no meio da sessão, mas essas instalações não se transferem para outras sessões.

Limites de recursos

As sessões na nuvem em ambientes hospedados pela Anthropic são executadas com limites de recursos aproximados que podem mudar ao longo do tempo:

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

A VM pode parar tarefas que precisam significativamente mais memória, como grandes trabalhos de compilação ou testes com uso intensivo de memória. Para cargas de trabalho além desses limites, use Remote Control para executar Claude Code em seu próprio hardware, ou execute sessões na nuvem em um ambiente auto-hospedado em computação que sua organização opera.

Scripts de configuração

Um script de configuração é um script Bash que é executado quando uma nova sessão na nuvem é iniciada, antes do Claude Code ser lançado. Use scripts de configuração para instalar dependências, configurar ferramentas ou buscar qualquer coisa que a sessão precise que não esteja pré-instalada.

Os scripts são executados como root no Ubuntu 24.04, portanto apt install e a maioria dos gerenciadores de pacotes de linguagem funcionam.

Para adicionar um script de configuração, abra o diálogo de configurações do ambiente e insira seu script no campo Setup script.

Este exemplo instala ShellCheck, que não está pré-instalado.

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

Requisitos do script

Um script de configuração tem três restrições para trabalhar:

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

Cache do ambiente

O script de configuração é executado na primeira vez que você inicia uma sessão em um ambiente. Depois que é concluído, a Anthropic tira um snapshot do sistema de arquivos e reutiliza esse snapshot como ponto de partida para sessões posteriores. As novas sessões começam com suas dependências, ferramentas e imagens Docker já no disco, e pulam a etapa do script de configuração. Isso mantém a inicialização rápida mesmo quando o script instala cadeias de ferramentas grandes ou puxa imagens de contêiner.

O cache é um snapshot do sistema de arquivos, portanto mantém o que o script de configuração escreve no disco e perde qualquer coisa que estava apenas em execução. Os pacotes que você instala, as imagens Docker que você puxa e os arquivos que você escreve todos se transferem. Um banco de dados que o script iniciou, uma pilha docker compose up ou qualquer outro processo em segundo plano não; inicie aqueles por sessão pedindo a Claude ou com um hook SessionStart.

O script de configuração é executado novamente para reconstruir o cache quando você altera o script de configuração do ambiente ou hosts de rede permitidos, e quando o cache atinge sua expiração após aproximadamente sete dias. Retomar uma sessão existente nunca re-executa o script de configuração.

Você não precisa ativar o cache ou gerenciar snapshots você mesmo.

Scripts de configuração vs. hooks SessionStart

Use um script de configuração para provisionar a própria VM: cadeias de ferramentas e ferramentas CLI que não estão pré-instaladas. Use um hook SessionStart para configuração de projeto que deve ser executada em qualquer lugar, nuvem e local, como npm install.

Os scripts de configuração e hooks SessionStart são executados em uma ordem fixa quando uma sessão na nuvem é iniciada. A tabela compara onde você os configura, quando são executados e onde são executados.

Se você tem hooks SessionStart em seu ~/.claude/settings.json no nível de usuário, não espere por eles na nuvem: as configurações no nível de usuário ficam em sua máquina. Qual outro hook é executado depende de onde a sessão é executada:

• Ambiente hospedado pela Anthropic: Claude Code executa hooks do repositório e das configurações gerenciadas pelo servidor de sua organização.
• 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

Para instalar dependências apenas em sessões na nuvem, emparelhe um hook SessionStart com um script que verifica onde está sendo executado.

Primeiro, adicione um hook SessionStart ao seu .claude/settings.json do repositório. Esta configuração diz a Claude Code para executar scripts/install_pkgs.sh do seu repositório sempre que uma sessão é iniciada ou retomada:

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

O matcher limita o hook aos eventos startup e resume, e $CLAUDE_PROJECT_DIR resolve para a raiz do repositório, portanto o hook encontra o script independentemente do diretório de trabalho da sessão.

Em seguida, crie o script em scripts/install_pkgs.sh. Ele sai imediatamente fora da nuvem, depois instala suas dependências:

#!/bin/bash

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

npm install
pip install -r requirements.txt
exit 0

A verificação CLAUDE_CODE_REMOTE é o que escopa a instalação para sessões na nuvem: a VM do ambiente carrega essa variável como true, nunca é true localmente, portanto em seu laptop o script sai antes de instalar qualquer coisa.

Juntos, os dois arquivos dão a cada sessão na nuvem um npm install e pip install fresco na inicialização enquanto deixam as sessões locais intocadas.

Limitações em sessões na nuvem

Os hooks SessionStart se comportam da mesma forma na nuvem que localmente, com essas ressalvas:

• Um repositório por sessão: 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.
• 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 verificando se as dependências já estão presentes antes de reinstalar.

Para personalizar a imagem base, use um script de configuração para instalar o que você precisa no topo da imagem fornecida, ou execute sua própria imagem como um contêiner ao lado de Claude com docker compose. Substituir a imagem base inteiramente ainda não é suportado.

Domínios permitidos padrão

Com acesso à rede Trusted, as sessões podem alcançar os seguintes domínios por padrão. Os domínios marcados com * indicam correspondência de subdomínio curinga, portanto *.gcr.io permite qualquer subdomínio de gcr.io.

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
• Rotinas: 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