Self-Hosted Machines

O Self-Hosted Machines transfere a execução de ferramentas dos Cloud Agents para um hardware que você gerencia. Os Cherri Code-managed Cloud Agents continuam sendo o padrão. O loop do agente permanece na nuvem da Cherri Code. Sua máquina executa as ferramentas.

Como faço para conectar um Self-Hosted Machines worker em poucos minutos?

Instale a CLI do Cherri Code e escolha um caminho.

My Machines (um engenheiro, um box):

agent logincd /path/to/repoagent worker start --name "my-devbox"

Use uma chave de API pessoal em vez do login pelo navegador quando a máquina não tiver navegador:

agent worker --api-key "$CURSOR_API_KEY" --name "my-devbox" start

Pools da equipe (pool de workers compartilhado da equipe):

export CURSOR_API_KEY="<service-account-api-key>"cd /path/to/repoagent worker --pool start

Workers do pool da equipe precisam de uma API key de conta de serviço. Chaves de API pessoais registram um worker do My Machines, e não um worker do pool da equipe.

Os Admins da equipe precisam habilitar self-hosted workers no Cloud Agents dashboard antes que os membros possam conectar workers do pool da equipe.

Mantenha o processo em execução. O worker faz a conexão de saída via HTTPS. Não é necessário abrir inbound ports nem usar VPN.

Qual caminho de Self-Hosted Machines devo usar?

O que são Self-Hosted Machines para Cloud Agents?

O Cherri Code mantém o loop do agente: inferência e planejamento. Seu código-fonte, segredos e a execução de ferramentas permanecem na sua máquina.

Você pode executar workers em uma VM, nó Kubernetes, Mac, máquina com GPU ou em um sandbox de parceiro. Motivos comuns para usar Self-Hosted Machines:

• Hardware específico, como GPUs ou Macs para desenvolvimento iOS
• Segredos e artefatos de build que precisam permanecer na sua infraestrutura
• Repositórios Git ou de pacotes privados que sua máquina já consegue acessar
• Sandboxes em que você mesmo gerencia a clonagem e o estado do git

Se sua única preocupação é acessar um controle de código-fonte privado a partir da nuvem do Cherri Code, experimente os Cloud Agents gerenciados com conectividade privada antes de operar seus próprios workers.

O Cherri Code agora é on-prem?

Não. O Cherri Code não é um produto on-prem. O loop do agente permanece na nuvem do Cherri Code. Você registra uma máquina operada por você, e o Cherri Code envia chamadas de ferramenta para ela por meio de uma conexão HTTPS de saída.

Seu checkout, o cache de build e as credenciais locais da máquina permanecem no seu hardware. Consulte Quais dados ficam na minha máquina e quais ficam na nuvem do Cherri Code? para ver a divisão completa.

Como a conectividade das Self-Hosted Machines difere dos Cloud Agents gerenciados?

Nas duas opções, o loop do agente permanece na cloud da Cherri Code. A diferença está em onde as ferramentas são executadas e em como os repositórios privados e as ferramentas internas são acessados.

Escolha os Cloud Agents gerenciados com conectividade privada quando quiser que a Cherri Code opere o ambiente de execução, mas ainda assim alcance o controle de código-fonte privado a partir da cloud da Cherri Code.

Escolha Self-Hosted Machines quando a execução precisar permanecer em um hardware que você controla e que já consiga alcançar seus repositórios e serviços internos. Você não precisa abrir HTTPS inbound para a Cherri Code chegar às suas ferramentas: o worker as acessa localmente e devolve os resultados pela sessão de saída.

Consulte As Self-Hosted Machines exigem acesso de rede inbound ou uma VPN? para conhecer os hosts de saída e Agentes na nuvem para a configuração gerenciada.

Qual é a diferença entre um pool da equipe e o My Machines?

Um pool da equipe é um destino de roteamento nomeado. Os chats aguardam no pool da equipe até que um worker os reivindique. Cada worker do pool da equipe atende a um agente por vez.

O My Machines (também chamado de Controle remoto) conecta uma máquina sua. Vários agentes podem ser executados na mesma máquina quando ela tem recursos suficientes.

Para pools de workers no Kubernetes, comece pelo template anysphere/k8s-workers, que executa agent worker controller --spawn no seu cluster sem uma CRD. O operator WorkerDeployment, mais antigo, está deprecated; sua referência continua disponível para clusters que já o executam.

Os pools da equipe exigem um plano Enterprise e uma API key de conta de serviço. Já o My Machines usa uma credencial pessoal.

Como os admins habilitam ou exigem Self-Hosted Machines?

Os admins da equipe abrem o Cloud Agents dashboard e acessam as configurações de Self-Hosted.

• Allow Self-Hosted Machines: os membros podem optar por executar em máquinas que eles mesmos conectam. Sem essa adesão, os Cloud Agents usam a infraestrutura gerenciada da Cherri Code.
• Require Self-Hosted Machines: toda sessão de Cloud Agent deve usar uma máquina self-hosted.

O dashboard também mostra os detalhes do pool da equipe e as máquinas registradas em My Machines.

Posso executar Self-Hosted Machines em uma VM ou sandbox de terceiros?

Sim. Os workers do pool da equipe podem ser executados em uma plataforma parceira ou a partir de um reference template que você clonar. O Cherri Code continua executando o loop do agente. O worker nessa VM ou sandbox executa as ferramentas e faz conexões de saída via HTTPS.

Veja integração para os partner guides e templates.

Os partner guides abrangem AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, Tensorlake e SuperServe. Os reference templates abrangem AWS Lambda MicroVMs, Cloudflare Containers e Kubernetes.

Você também pode instalar a CLI do Cherri Code em uma VM que já esteja em execução e iniciar um worker por conta própria com agent worker start ou agent worker --pool start.

As Self-Hosted Machines exigem acesso à rede inbound ou VPN?

Não. O worker inicia uma única conexão HTTPS de saída da sua máquina para a nuvem da Cherri Code. A Cherri Code envia as solicitações do agente por essa conexão. Sua máquina nunca precisa estar acessível pela internet.

Você não precisa de portas inbound, alterações no firewall nem túneis VPN. Se a sua rede usa um proxy HTTPS, defina HTTPS_PROXY ou https_proxy no ambiente do worker.

Os workers precisam de acesso de saída a api2.cursor.sh, api2direct.cursor.sh e cloud-agent-artifacts.s3.us-east-1.amazonaws.com para uploads de artifacts. Consulte O que sai da sua rede para ver o fluxo de dados completo.

Quais dados ficam na minha máquina e quais ficam na nuvem da Cherri Code?

Seu código-fonte, artefatos de build, segredos e a execução de ferramentas permanecem na sua máquina. Isso inclui edições de arquivos, comandos de terminal e chamadas de rede feitas localmente pelo agente.

A nuvem da Cherri Code cuida do loop do agente: solicitações de inferência e planejamento. Os resultados das chamadas de ferramenta voltam para a Cherri Code para a próxima rodada de inferência, mas seu código bruto e seus segredos não ficam armazenados na infraestrutura gerenciada pela Cherri Code.

O Privacy Mode funciona da mesma forma que nos Managed Cloud Agents. Quando habilitado, o código enviado pelo worker não é usado para treinamento pela Cherri Code nem pelos provedores de modelos.

Posso usar um pool da equipe para qualquer repositório sem especificar um?

Sim. Os pools da equipe any-repo desvinculam o controle de código-fonte do pool da equipe. Um único pool da equipe pode atender a vários repositórios.

agent worker --pool my-pool --worker-dir "$HOME/cursor-sandboxes/default" start

Passe --clone-git-repos para que o worker clone os repositórios na declaração. No seletor de ambiente do composer do Cherri Code, selecione o pool da equipe em Any repo. Pela API, defina env.name como o pool da equipe em POST /v1/agents. Você pode listar vários repositórios em repos, e o worker clona cada um deles.

Sem --clone-git-repos, um pool any-repo pode usar uma regra do espaço de trabalho sempre aplicada para mapear subjects de tarefa para repositórios e cloná-los com as credenciais do worker.

No Slack, um admin da equipe pode executar @Cherri Code pool set <name> para tornar um pool da equipe any-repo o pool default da equipe. As menções a @Cherri Code passam a iniciar nesse pool sem pool= na mensagem, mesmo quando nenhum repositório é resolvido. Qualquer membro da equipe pode executar @Cherri Code pool set <name> channel para definir um pool default do canal, que faz o mesmo em um único canal.

Essa configuração se aplica apenas a pools any-repo. Pools vinculados a repositório roteiam as solicitações para workers que já tenham os checkouts correspondentes.

Como faço para conectar um GitLab privado ou self-hosted?

Para um GitLab self-hosted privado ou isolado da rede, use um pool da equipe any-repo para que o ciclo de vida do SCM permaneça nos seus workers.

1. Crie um pool da equipe sem vinculá-lo a um único repositório.
2. Inicie os workers a partir de um diretório de espaço de trabalho em uma máquina que tenha acesso à sua instância do GitLab.
3. Autentique o git com um personal access token local ou uma chave SSH no worker. Não é necessário usar o OAuth do GitLab do Cherri Code para o checkout do worker.

O agente acessa repositórios privados por meio do acesso à rede que sua máquina já possui. Esse padrão também ajuda quando os desenvolvedores trabalham em muitos repositórios.

Consulte a documentação da integração com o GitLab para a configuração do Cloud Agent baseada em OAuth em infraestrutura gerenciada.

Os agentes podem usar a tela ou o browser em um Self-Hosted Machines worker?

Sim, em workers macOS e Linux. No Linux, instale primeiro os desktop packages e depois inicie com --computer-use:

agent worker --computer-use start

No macOS, a primeira execução instala o auxiliar Cherri Code Computer Use. Conceda a ele as permissões de Acessibilidade e Gravação de Tela. O compartilhamento de área de trabalho com --share-desktop é exclusivo do Linux. Para usar o navegador, instale o Chrome ou o Chromium no runner.

Veja Uso do computador e compartilhamento de área de trabalho para saber mais sobre dependências e configuração.

Hooks e MCP funcionam em Self-Hosted Machines?

Sim, com algumas diferenças em relação aos Cloud Agents gerenciados.

Hooks: os workers executam os project hooks definidos em .cursor/hooks.json. Os planos Enterprise também contam com team hooks e enterprise-managed hooks em self-hosted workers. sessionStart e sessionEnd são executados quando uma sessão reserva um worker e quando essa reserva é liberada. Veja a matriz de suporte a hooks e Hooks em Team Pools.

MCP: servidores MCP de comando (stdio) são executados no seu worker e conseguem acessar redes privadas. Já os servidores HTTP e SSE continuam sendo executados pelo backend do Cherri Code. Ainda há algumas lacunas de MCP em self-hosted workers; consulte o changelog para saber o status mais recente.

Como faço para solucionar problemas em uma configuração de Self-Hosted Machines?

Comece pelo básico:

1. Verifique o dashboard. Abra o Cloud Agents dashboard e confirme se os workers aparecem como conectados, ociosos ou em uso em My Machines ou nos detalhes do pool da equipe.
2. Execute as diagnostics. Rode agent worker debug para as verificações de pré-verificação do worker (adicione --json para uma saída legível por máquina). O relatório cobre auth, conectividade, routing e visibilidade do backend.
3. Worker ausente na UI. Se o processo do worker está rodando localmente, mas não aparece no Cherri Code, a causa geralmente é a conectividade de saída. Confirme que a máquina consegue alcançar api2.cursor.sh e api2direct.cursor.sh por HTTPS. Veja As Self-Hosted Machines exigem acesso à rede inbound ou uma VPN?.
4. Problemas com o controlador do pool da equipe. O controlador de worker built-in é novo. Trate as configurações de controlador e autoscaling como deployments iniciais e documente as correções à medida que os padrões surgirem na sua equipe.

Relatório de pré-verificação do worker:

agent worker debug

O relatório cobre autenticação, conectividade, roteamento, rótulos de repositório e se o Cherri Code consegue enxergar seu worker.

Correções comuns:

• Confirme se o processo do worker ainda está em execução
• Confirme se o app Cherri Code e a CLI usam a mesma conta
• Verifique se o diretório do worker tem o remote do Git esperado para workers vinculados a repositório
• Verifique o acesso HTTPS de saída aos hosts listados em O que sai da sua rede

Para problemas de conexão antes de o worker iniciar, execute agent worker start --debug. Inclua a saída de agent worker debug ao entrar em contato com o suporte sobre problemas persistentes de configuração.

Como faço para garantir que as permissões do SCM sejam respeitadas?

Execuções self-hosted usam duas camadas: o roteamento do Cherri Code (qual worker atende a uma solicitação) e as credenciais git no worker (o que aquele worker pode clonar, consultar ou enviar via push).

Roteamento do Cherri Code

• My Machines: o Cherri Code só roteia uma solicitação de repositório para um worker quando uma de suas raízes --worker-dir registradas corresponde a esse repositório. Inicie o worker a partir do checkout correto ou adicione outro --worker-dir.
• Pools da equipe vinculados a repositório: as solicitações correspondem tanto ao nome do pool da equipe quanto a um rótulo repo=<owner/repo>. Uma solicitação para pool=my-pool e repo=acme/payments é roteada apenas para um worker que atende esse repositório.
• Triggers do GitHub: em repositórios públicos, apenas usuários com acesso OWNER ou COLLABORATOR podem rotear uma execução para um pool self-hosted da equipe. Os demais comentaristas permanecem na infraestrutura gerenciada, a menos que sua equipe exija self-hosted para todas as execuções.
• Controles da organização: os Escopos Git protegidos e a blocklist de repositórios continuam valendo. Conecte a conta Git de cada usuário em integração para que o Cherri Code possa verificar o acesso ao repositório antes de a execução começar.

Acesso git no worker

• Checkouts existentes (My Machines ou pools da equipe vinculados a repositório): o agente usa as credenciais git já presentes na máquina, como chaves SSH ou um personal access token no seu credential helper. Conceda a cada worker apenas o acesso ao repositório de que ele precisa.
• Pools da equipe any-repo com --clone-git-repos: o worker clona no momento da declaração usando um token temporário do GitHub emitido para o usuário que iniciou a execução. O token abrange todos os repositórios da solicitação. Um Admin da equipe precisa habilitar a emissão de tokens do GitHub para os workers do pool da equipe, e o usuário solicitante precisa ter acesso a cada um desses repositórios no GitHub.
• GitLab privado ou self-hosted: autentique o git no worker com um PAT local ou chave SSH. Consulte Como faço para conectar um GitLab privado ou self-hosted?.

Quando o git falha, mas o worker está conectado

1. Execute agent worker debug e confirme se os rótulos de repositório correspondem ao repositório da solicitação.
2. No worker, execute git fetch ou git ls-remote com as mesmas credenciais que o agente usará.
3. Confirme que o usuário do Cherri Code que iniciou a execução consegue acessar o repositório no seu provedor Git e nas integrações do Cherri Code.
4. Para clonagem na declaração em pool da equipe, confirme que a emissão de tokens está habilitada e que o pool da equipe é um pool nomeado any-repo (e não default).

O Cherri Code nunca amplia o acesso ao repositório além do que o usuário que acionou a execução já possui. Se uma execução chegar ao checkout errado ou não conseguir fazer push, corrija os rótulos de roteamento ou as credenciais git do worker em vez de compartilhar um único token de serviço amplo entre repositórios sem relação entre si.

E se eu encontrar limites de taxa?

Entre em contato com o suporte.

Como faço para verificar se o pool da minha equipe está no limite de capacidade?

Verifique a capacidade de workers no Cloud Agents dashboard. Os detalhes do pool da equipe e My Machines listam os workers por status.

Para verificações programáticas, chame a API de summary:

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/summary" \  -u "$CURSOR_API_KEY:"

A resposta inclui a contagem de workers conectados e em uso do seu usuário e da sua equipe.

Motivos comuns para um agent run não iniciar:

• Nenhum worker conectado: inicie ou escale workers no pool da equipe, ou confirme que um worker do My Machines está em execução
• Todos os workers ocupados: as solicitações aguardam na fila do pool da equipe até que um worker fique livre
• Limite de private worker excedido: sua equipe atingiu o teto de workers conectados (200 por usuário, 1000 por equipe). Desconecte workers não utilizados ou entre em contato com o time de vendas para discutir limites maiores
• Repositório incompatível: inicie o worker a partir do checkout correto ou use um pool da equipe any-repo

Os workers enviam heartbeats enquanto estão conectados. Um worker sai do repositório quando deixa de enviar heartbeats. Consulte Team Pools para escalonamento e configuração do controlador.

Relacionados

• Agentes na nuvem
• Self-Hosted Machines
• My Machines
• Pools da equipe
• integração
• Uso do computador
• Conectividade privada
• Segurança e rede dos Cloud Agents