Configuração do ambiente em nuvem

Os agentes em nuvem são executados em máquinas Ubuntu isoladas. Configure o ambiente para que o agente tenha os mesmos repositórios, ferramentas, dependências, segredos e acesso à rede que um desenvolvedor usaria.

Crie um novo ambiente no dashboard do Cloud Agents.

O que é um ambiente de agente em nuvem?

O ambiente de desenvolvimento de um agente em nuvem é semelhante à configuração de um laptop: repositórios clonados, dependências instaladas, segredos, comandos de inicialização e acesso à rede.

Ambientes de desenvolvimento eficazes dão aos agentes contexto completo sobre sua base de código e organização, para que possam testar e verificar o próprio trabalho.

Por que a configuração do ambiente é importante?

Os agentes só são tão capazes quanto os ambientes em que são executados. Um agente que consegue escrever código, mas não consegue executar testes, consultar serviços nem acessar APIs, não consegue completar seu trabalho.

Para executar tarefas de engenharia do início ao fim, agentes em nuvem precisam de um ambiente de desenvolvimento configurado, com todos os repositórios, ferramentas, dependências e contexto necessários para permanecerem autônomos e produtivos.

Ambientes de desenvolvimento também tornam as sessões de agente mais rápidas. As Builds preparam repositórios, ferramentas e dependências em segundo plano para que os agentes comecem em uma máquina pronta para uso.

A configuração do ambiente é a etapa mais importante para melhorar a eficácia dos seus agentes em nuvem.

Opções de configuração do ambiente

Há duas principais maneiras de configurar o ambiente para seu agente em nuvem:

1. Deixe o agente do Cherri Code configurar o próprio ambiente pelo dashboard do Cloud Agents. O agente instala dependências, verifica o ambiente e cria seu primeiro Build.
2. Configure manualmente o ambiente com um Dockerfile. Se você escolher essa opção, poderá especificar o Dockerfile em um arquivo .cursor/environment.json.

Ambas as opções permitem especificar um script de instalação. O Cherri Code o executa ao criar um Build para que as dependências estejam prontas antes de um agente iniciar.

Ambientes multi-repositório

Use um ambiente multi-repositório quando um agente precisar trabalhar em mais de um repositório. Selecione vários repositórios ao criar um ambiente. O Cherri Code clona cada repositório na máquina do agente e reutiliza o ambiente em execuções futuras do agente e automações que usam o mesmo grupo de repositórios.

Use ambientes multi-repositório quando frontend, backend, infraestrutura ou bibliotecas compartilhadas estão em repositórios separados. O agente pode inspecionar todo o espaço de trabalho, fazer alterações coordenadas, executar testes em vários repositórios e abrir pull requests nos repositórios que alterar.

Você pode ver qual ambiente está ativo, junto com todas as versões ativas anteriores, acessando a página de configuração do ambiente no Cloud Agents dashboard.

Ordem de resolução do ambiente

O Cherri Code resolve a configuração do ambiente por repositório ou grupo de repositórios, usando a primeira correspondência:

1. .cursor/environment.json no repositório
2. Um ambiente pessoal salvo
3. Um ambiente da equipe salvo

Isso oferece valores padrão previsíveis no nível da equipe, sem deixar de permitir que usuários individuais substituam isso por um ambiente pessoal quando não houver um .cursor/environment.json no nível do repositório. As substituições do usuário também são úteis para testar uma nova configuração de ambiente antes de implementá-la para toda a equipe.

Configuração orientada por agente (recomendada)

O Cherri Code pode configurar seu ambiente de desenvolvimento na nuvem em menos de 10 minutos. Inicie a configuração guiada no dashboard do Cloud Agents ou na Janela de Agentes no app para desktop do Cherri Code.

Você deverá conectar sua conta do GitHub, GitLab, Azure DevOps ou Bitbucket e selecionar um ou mais repositórios.

Em seguida, você fornece ao Cherri Code as variáveis de ambiente e os segredos de que ele precisará para instalar dependências e executar o código.

Enquanto o agente trabalha, você pode acompanhar o progresso dele em uma sessão de terminal compartilhada enquanto ele realiza tarefas de configuração, como instalar dependências. O Cherri Code salva o ambiente depois de verificar o código e concluir uma Build bem-sucedida.

Futuros Cloud Agents iniciam a partir da Build ativa e podem testar alterações executando seu software. Faça commit da configuração em .cursor/environment.json para que toda a sua equipe se beneficie.

Configuração manual com Dockerfile (avançada)

Para casos avançados, configure o ambiente com um Dockerfile:

• Crie um Dockerfile para instalar dependências de sistema, usar versões específicas de compiladores, instalar depuradores ou trocar a imagem base do sistema operacional
• Não faça COPY do projeto inteiro; o Cherri Code gerencia o espaço de trabalho e faz checkout do commit correto
• Edite .cursor/environment.json diretamente para configurar opções de tempo de execução
• Use segredos de build para registries privados de pacotes ou credenciais de build

Aqui está um exemplo de .cursor/environment.json que faz referência a um .cursor/Dockerfile (caminho relativo) e a um script de instalação custom_script.sh:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

Se o seu repositório precisar de Docker, Tailscale ou Cloudflare Tunnel, consulte Executando o Docker, Executando o Tailscale e Executando o Cloudflare Tunnel abaixo.

O ambiente é configurado com um Dockerfile; você não tem acesso direto à máquina remota.

As builds de Dockerfile usam cache de camadas. Quando você altera um Dockerfile, o Cherri Code recompila as camadas alteradas em vez de recompilar todas as camadas do zero.

Dockerfiles configurados pelo Cherri Code (beta privado)

Para equipes que não querem escrever um Dockerfile do zero, o Cherri Code pode configurar um para você. Durante a configuração, o Cherri Code inspeciona seus repositórios, identifica ferramentas e dependências e gera uma configuração de ambiente baseada em Dockerfile que você pode editar e versionar.

Esse fluxo está em beta privado para equipes corporativas. Para solicitar acesso, entre em contato com o representante da sua conta Cherri Code ou envie um email para [email protected] usando sua conta de administrador da equipe.

Limites de recursos

Cada agente em nuvem é executado em um perfil de VM padrão com memória e CPU limitadas. Se você estiver em um plano Enterprise e seu repositório precisar de mais recursos, entre em contato com o suporte e poderemos aumentar os limites do seu espaço de trabalho.

A configuração personalizada de recursos em modo de autoatendimento estará disponível em breve.

Começar do zero

Você pode iniciar um agente em nuvem sem um repositório ou um provedor de source control conectado. Selecione Começar do zero no seletor de repositórios em cursor.com/agents ou na Janela de Agentes e envie seu prompt. O Cherri Code cria, em segundo plano, um repositório Origin em rascunho para o agente, e o agente já trabalha nele desde o primeiro turno.

Salve o trabalho em um repositório

Quando o trabalho do agente estiver do jeito que você quer, selecione Create repo acima da entrada do agente. Escolha um dos nomes sugeridos ou selecione Other e digite o seu. Os nomes podem conter letras, dígitos, hifens e sublinhados, com até 100 caracteres. Em uma equipe, defina quem pode ver o código: Private (somente você) ou Internal (qualquer pessoa da sua equipe pode visualizar e editar). Depois, selecione Create Origin repo.

O Cherri Code publica o repositório em rascunho com esse nome, e o trabalho do agente vai junto. O repositório aparece em cursor.com/codebase, onde você pode navegar por ele, cloná-lo e alterar sua visibilidade.

Visualize a prévia do app em execução

O Cherri Code encaminha as portas do ambiente do agente para a sua máquina, assim você pode abrir o app que o agente está criando enquanto ele roda. Na Janela de Agentes, abra o menu Forwarded Ports no painel do editor. As portas em que os processos do ambiente do agente escutam aparecem em Detected. Ative Auto-Forward Ports para encaminhá-las automaticamente ou informe um número de porta para encaminhá-la manualmente. Selecione Open in internal browser em uma porta encaminhada para ver a prévia do app e use o Modo de Design para apontar elementos e orientar o agente direto da página.

Publicar em uma URL ativa

Depois que o repositório existir, conecte uma conta da Vercel e, na Janela de Agentes, selecione Publish acima da entrada do agente. Se você ainda não adicionou o plugin da Vercel, o Cherri Code oferece primeiro Add Vercel. O agente vincula o repositório a um projeto da Vercel, faz o deploy do branch padrão e responde com a URL do deployment. Commits posteriores no branch padrão passam a ser implantados automaticamente.

Script de instalação

Anteriormente, o script de instalação era chamado de script de atualização no dashboard e na documentação.

O Cherri Code executa o script de instalação (install em environment.json) ao criar uma Build. O script é concluído em segundo plano, sem atrasar o início de cada agente.

Use install para tarefas que o Cherri Code pode preparar antecipadamente, como instalar dependências, gerar código, compilar artefatos e aquecer caches de disco.

Os scripts de instalação podem ler metadados do agente e emitir Tokens OIDC pelo mesmo socket local que o agente usa.

Como os Builds usam o script de instalação

O Cherri Code parte da imagem base do ambiente, clona os repositórios e executa install até o fim. Um Build bem-sucedido captura o estado resultante do disco e se torna ativo. Novos agentes começam a partir do Build ativo.

Garanta que o script seja concluído. Configurações demoradas devem ficar em install, pois ele é executado antes de uma solicitação do agente, e não durante a inicialização. Comandos como pnpm install ainda podem reutilizar o estado preparado e atualizar apenas as dependências alteradas.

Os Builds preservam apenas o estado do disco. Processos em execução, variáveis de shell exportadas e caches em memória não continuam na execução de um agente. Inicie serviços com start ou terminals.

Recuperação da configuração do ambiente

Uma Build com falha não substitui a Build ativa. Os agentes continuam sendo iniciados no ambiente bem-sucedido mais recente enquanto você analisa a falha e cria uma substituta.

Abra a aba Builds do ambiente para inspecionar os logs, iniciar um agente a partir da Build com falha ou selecionar outra Build bem-sucedida. Consulte Cloud Agent Builds para saber mais sobre os controles e a depuração de Builds.

Como decidir o que incluir no script de instalação

Coloque todas as etapas de preparação repetíveis em install. Inclua a instalação completa das dependências, a geração de código, a compilação de artefatos e outras tarefas que gravam resultados reutilizáveis em disco.

Mantenha processos de longa duração fora de install. Coloque Docker, bancos de dados, túneis e servidores de desenvolvimento nos comandos de inicialização. Você também pode adicionar instruções ao AGENTS.md para serviços de que um agente precisa apenas em tarefas específicas.

Comandos de inicialização

Depois que um agente é iniciado a partir de uma Build, o Cherri Code executa o comando start e depois quaisquer terminals configurados. Use-os para processos que devem permanecer em execução enquanto o agente estiver rodando.

Você pode omitir start em muitos repositórios. Se seu ambiente depende do Docker, adicione sudo service docker start em start.

terminals são para processos da aplicação. Eles são executados em uma sessão tmux compartilhada entre você e o agente.

Adicione instruções específicas de nuvem ao AGENTS.md

Agentes em nuvem leem arquivos AGENTS.md. Recomendamos adicionar uma seção dedicada para instruções de configuração e testes apenas para a Cloud, com um título como Instruções específicas do Cherri Code Cloud.

Se essa seção ficar grande, recomendamos incluir referências a outros arquivos que possam conter instruções detalhadas para tarefas específicas.

Consulte a documentação do AGENTS.md para mais informações.

Variáveis de ambiente e segredos

Para conseguir executar e testar código como um desenvolvedor humano, agentes em nuvem geralmente precisam de variáveis de ambiente e segredos, como chaves de API e credenciais de banco de dados.

Recomendado: use a aba Secrets nas Cherri Code Settings

A forma mais fácil de gerenciar segredos é pelo cursor.com. Eles ficam disponíveis para o agente em nuvem como variáveis de ambiente.

Para saber mais sobre os diferentes tipos de segredos, consulte nossa documentação sobre Secrets. Para conceder acesso à função de nuvem sem chaves de longa duração, consulte tokens OIDC.

Segredos com escopo de ambiente

Use segredos com escopo de ambiente quando uma credencial deve estar disponível apenas para agentes que usam um ambiente. Isso é útil para ambientes multi-repositório, credenciais de staging ou grupos de repositórios com diferentes necessidades de acesso.

Eles se aplicam a todos os repositórios desse ambiente. Eles não ficam disponíveis em outros ambientes.

Credenciais de login e 2FA

Se o seu app exigir login, adicione como segredos as mesmas credenciais que você usa localmente, como nome de usuário, email e senha.

Se o seu fluxo de login usar 2FA via TOTP, adicione também o segredo TOTP, às vezes chamado de segredo compartilhado ou segredo raiz, como segredo. O agente pode gerar o código atual de 6 dígitos com oathtool --totp -b "$TOTP_SECRET".

Monorepos com vários arquivos .env

Se o seu monorepo tiver vários arquivos .env.local:

• Adicione os valores de todos os arquivos .env.local à mesma aba Secrets
• Use nomes de variáveis exclusivos quando houver chaves com o mesmo nome, como NEXTJS_* e CONVEX_*
• Referencie essas variáveis em cada app, conforme necessário

Se você incluir arquivos .env.local ao gerar um snapshot, eles poderão ser salvos e ficar disponíveis para agentes em nuvem. A aba Secrets continua sendo a abordagem recomendada em termos de segurança e gerenciamento.

Usando funções do IAM da AWS

O Cherri Code oferece suporte a assumir funções do IAM fornecidas pelo cliente para uma integração mais profunda com a AWS. Isso permite conceder permissões específicas da AWS a agentes na nuvem sem compartilhar credenciais de longa duração.

1. Crie a função do IAM: Na sua conta da AWS, crie a função do IAM que você quer que o agente na nuvem assuma e anote o ARN dela (por exemplo, arn:aws:iam::123456789012:role/acmeRole).

2. Configure o segredo da função do IAM: Acesse dashboard do Cherri Code → Agentes na nuvem e adicione um segredo de usuário ou de equipe chamado CURSOR_AWS_ASSUME_IAM_ROLE_ARN, definido com o ARN da função do IAM que você criou.

3. Gere um ID externo: Um administrador da equipe deve fazer isso na seção Advanced das configurações da equipe. Acesse dashboard do Cherri Code → Settings → Advanced e localize as configurações de ID externo. Se nenhum ID externo for exibido, insira um valor provisório no campo "AWS IAM Role ARN", clique em "Validate & Save" e recarregue a página. Isso gerará um ID externo para a sua equipe (por exemplo, cursor-xxx-yyy-zzz).

4. Configure a trust policy da função do IAM: Na sua conta da AWS, atualize a trust policy da função do IAM para confiar no role assumer do Cherri Code. A trust policy deve ficar assim:

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "AllowCursorAssume",      "Effect": "Allow",      "Principal": {        "AWS": "arn:aws:iam::289469326074:role/roleAssumer"      },      "Action": "sts:AssumeRole",      "Condition": {        "StringEquals": {          "sts:ExternalId": "cursor-xxx-yyy-zzz"        }      }    }  ]}

Substitua cursor-xxx-yyy-zzz pelo ID externo gerado para sua equipe.

Variáveis de ambiente:

Quando configurado, o Cherri Code define estas variáveis de ambiente para que as ferramentas da AWS usem o perfil cursor-cloud-agent:

• AWS_CONFIG_FILE aponta para um arquivo de configuração da AWS gerenciado pelo Cherri Code
• AWS_PROFILE é definido como cursor-cloud-agent
• AWS_SDK_LOAD_CONFIG é definido como 1

A CLI da AWS e os SDKs da AWS que usam a cadeia padrão de credenciais usam esse perfil automaticamente durante os comandos de configuração e enquanto o agente está em execução. Você não precisa exportar AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY nem AWS_SESSION_TOKEN por conta própria.

Para se federar com o AssumeRoleWithWebIdentity do AWS STS ou com o GCP, Azure ou outro verificador OIDC, emita tokens OIDC na VM do agente em vez de armazenar chaves de nuvem de longa duração.

Configuração em código com environment.json

Se você preferir manter a configuração do ambiente definida em código, pode fazer commit de .cursor/environment.json no seu repositório.

As builds usam a configuração da branch padrão do ambiente. Para alterações em branches de funcionalidade, faça commit e push da configuração e inicie um agente na branch. O Cherri Code faz checkout da branch solicitada sobre a Build ativa, e o agente pode executar novamente o comando de instalação quando a branch altera dependências.

Exemplo de environment.json com uma configuração baseada em snapshot (o ID do snapshot está disponível na página de environments do dashboard):

{  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",  "install": "npm install"}

Aqui está um exemplo de .cursor/environment.json que faz referência a .cursor/Dockerfile (caminho relativo) e a um script de instalação custom_script.sh:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

O esquema completo está definido aqui.

Executando o Docker

Agentes em nuvem oferecem suporte a workflows com Docker. Usamos isso internamente para repositórios full-stack que executam muitos serviços.

Para configurações simples, instalar o Docker geralmente é suficiente. Comandos como docker run hello-world normalmente funcionam quando o Docker está instalado e o daemon está em execução.

Em Cloud Agents, o Docker é executado dentro de outra camada de contêiner, então há casos de borda. Fluxos de trabalho simples geralmente funcionam. Configurações mais complexas devem partir da configuração de fuse-overlayfs e iptables-legacy abaixo.

Para configurações Docker mais complexas, use fuse-overlayfs, iptables-legacy e garanta que o usuário do seu agente em nuvem possa executar o Docker.

######################################################### DOCKER INSTALLATION######################################################### Install DockerRUN install -m 0755 -d /etc/apt/keyrings && \    curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \    chmod a+r /etc/apt/keyrings/docker.gpg && \    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \    apt-get update && \    apt-get install -y \    docker-ce=5:28.5.2-1~ubuntu.24.04~noble \    docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble \    containerd.io \    docker-buildx-plugin \    docker-compose-plugin \    && rm -rf /var/lib/apt/lists/*RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/*RUN mkdir -p /etc/docker && \    printf '%s\n' '{' \    '  "storage-driver": "fuse-overlayfs"' \    '}' > /etc/docker/daemon.jsonRUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/*RUN update-alternatives --set iptables /usr/sbin/iptables-legacy && \    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy######################################################### CONFIG UBUNTU USER######################################################### garantir que não haja autenticação por senhaRUN echo 'PasswordAuthentication no\nChallengeResponseAuthentication no\nUsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf# Criar usuário não-root (somente se não existir)RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu# Criar grupo docker se não existir e adicionar o usuário ubuntu a eleRUN groupadd -f docker && usermod -aG docker ubuntuRUN usermod -aG sudo ubuntu# Configurar sudo sem senha para o usuário ubuntuRUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu# Definir uma senha para o usuário ubuntuRUN echo "ubuntu:ubuntu" | chpasswd

Executando o Tailscale

O Tailscale não funciona no modo de rede padrão das VMs de agente em nuvem. Use o modo de rede em espaço de usuário.

Isso permite que o agente acesse serviços privados e armazenamentos de dados por meio da sua tailnet sem expor esses serviços à internet pública.

Inicie o tailscaled com:

tailscaled --tun=userspace-networking \  --outbound-http-proxy-listen=localhost:1054 \  --socks5-server=localhost:1055

Em seguida, exporte estas variáveis de proxy no shell em que você quer que o tráfego seja roteado pelo Tailscale:

export ALL_PROXY=socks5h://localhost:1055/export HTTP_PROXY=http://localhost:1054/export HTTPS_PROXY=http://localhost:1054/

Depois disso, execute o fluxo habitual do tailscale up ....

Se quiser uma referência prática, alguns clientes usaram o tailscale-orb com sucesso porque o modo Docker dele segue esse padrão.

Executando o Cloudflare Tunnel

O Cloudflare Tunnel funciona nas VMs do Cloud Agent porque o cloudflared é executado em espaço de usuário.

Use este padrão quando um Cloud Agent precisar acessar um serviço HTTP privado em uma VPC ou intranet:

• Instale o cloudflared no Dockerfile do seu ambiente ou no script de instalação.
• Execute um conector cloudflared dentro da sua rede privada.
• Encaminhe um hostname autenticado, como vpc.example.com, pelo túnel até a origem privada.
• Adicione esse hostname à lista de permissão de rede do Cloud Agent se o seu ambiente usar saída restrita.
• Armazene os valores do token de serviço do Cloudflare Access como Secrets do Cherri Code. Por exemplo, use CF_ACCESS_CLIENT_ID e CF_ACCESS_CLIENT_SECRET.

O Cloud Agent pode então chamar o serviço privado por HTTPS normal com os cabeçalhos CF-Access-Client-Id e CF-Access-Client-Secret. O conector faz a conexão de saída com o Cloudflare e encaminha a solicitação para sua origem privada. Seus serviços e armazenamentos de dados permanecem na sua rede privada, e o conector não precisa de portas de entrada abertas.

Para serviços TCP privados, como bancos de dados, configure um app Cloudflare TCP Access e execute cloudflared access tcp no seu comando de inicialização. Aponte seu app ou comando de teste para o listener local que o cloudflared cria.