My Machines

O My Machines é a configuração pessoal de Self-Hosted Machines. Ele permite que um usuário específico execute chamadas de ferramenta do Cloud Agent em uma máquina que ele já usa: um laptop, devbox ou remote VM. Use-o quando essa máquina for o ambiente de execução desejado para um repositório.

Um worker na sua máquina abre uma conexão de saída com o Cherri Code. O loop do agente é executado na nuvem do Cherri Code, mas comandos de terminal, edições de arquivos, ações no navegador e outras chamadas de ferramenta são executados na sua máquina. Nenhuma porta de entrada nem alteração no firewall são necessárias.

Use o My Machines quando você quiser:

• Usar um devbox ou estação de trabalho remota que já tenha seu repositório e ferramentas
• Executar chamadas de ferramenta na máquina de um usuário para um repositório específico
• Reutilizar o estado local da máquina que você não quer recriar em um ambiente em nuvem
• Testar o modelo de worker antes de criar um pool gerenciado centralmente

Para frotas de workers em toda a organização, veja Pools da equipe.

Início rápido

1. Instale a CLI

# macOS, Linux e WSL# Windows PowerShellirm '# | iex

Verifique se a CLI está disponível:

agent --version

2. Fazer login

Em uma máquina pessoal, fazer login pelo navegador é a forma mais fácil:

agent login

3. Inicie o worker

agent worker start

Mantenha esse processo em execução enquanto estiver usando a máquina. Por padrão, um worker do My Machines é de longa duração: permanece conectado até você interrompê-lo e pode ser reutilizado em futuras sessões do Cloud Agent.

4. Execute um agente

1. Acesse cursor.com/agents.
2. A máquina deve aparecer no menu suspenso de ambiente.
3. Envie uma tarefa.

Opções comuns

Dê um nome à máquina

Use um nome fácil de identificar quando tiver várias máquinas para o mesmo repositório:

agent worker start --name "my-devbox"

Executar a partir de outro diretório do repositório

agent worker start --worker-dir /path/to/repo

Registre várias raízes de repositório repetindo --worker-dir:

agent worker \  --worker-dir "$HOME/repos/app" \  --worker-dir "$HOME/repos/infra" \  start

Cada path deve existir. Para cada root com um remote do Git, o worker registra metadata de routing para que o Cherri Code possa associar as solicitações ao checkout correto.

Usar uma API key

Para devboxes ou automações em que o login pelo navegador não é prático, use uma chave de API de usuário pessoal em Cherri Code Dashboard → API Keys:

agent worker start --api-key "your-user-api-key"

Use um token no escopo do usuário

Para workers autogerenciados por usuário, crie um token de curta duração no escopo do usuário com POST /v1/sub-tokens e, em seguida, inicie o worker com esse token:

agent worker start --auth-token "your-user-scoped-token"

Para workers de longa duração, leia o token a partir de um arquivo:

agent worker start --auth-token-file /var/run/cursor/token

Isso é útil no Kubernetes porque as variáveis de ambiente provenientes de Secrets são definidas quando o pod é iniciado. Os volumes de Secret são atualizados enquanto o pod está em execução, e os caminhos dos tokens montados podem ser atualizados em tempo real dentro do pod, o que permite renovar o token enquanto o pod está em execução.

Emitir tokens de identidade

Permita que os agentes reivindicados emitam tokens OIDC de curta duração passando --identity-socket antes de start. O worker define CURSOR_AGENT_SOCKET como o path do socket. O token identifica o owner daquele run. Consulte Tokens OIDC para ver o contract do socket, o modelo de confiança e a AWS.

agent worker --identity-socket start

Ativar computer use

Permita que o agente clique, digite, faça capturas de tela e controle apps nesta máquina passando --computer-use antes de start:

agent worker --computer-use --name "my-mac" start

No macOS, a primeira inicialização instala o app auxiliar Cherri Code Computer Use. Conceda a ele Acessibilidade e Gravação de Tela em Ajustes do Sistema → Privacidade e Segurança e depois teste com uma tarefa que tire um screenshot. No Linux, instale antes os pacotes de desktop. Consulte Computer use e compartilhamento de desktop para ver os passos de permissão no macOS, as orientações de MDM e as opções de display no Linux.

Acione esta máquina a partir de uma interface de chat

Use worker= ou machine= quando quiser que solicitações do Slack, GitHub ou Linear sejam executadas em uma das suas máquinas com nome. Essas são as únicas opções de trigger direcionadas ao My Machines.

Inicie a máquina com --name e, em seguida, inclua esse nome na solicitação:

• No Slack, use @Cherri Code worker=my-devbox fix the flaky test ou @Cherri Code machine=my-devbox fix the flaky test.
• No GitHub, comente @cursoragent worker=my-devbox fix the flaky test ou @cursoragent machine=my-devbox fix the flaky test. Você deve ser um comentarista confiável no repositório, e a máquina de destino deve pertencer ao usuário do Cherri Code vinculado à sua conta do GitHub.
• No Linear, adicione worker=my-devbox ou machine=my-devbox ao corpo da issue. Você também pode usar um label pai chamado worker ou machine, com um label filho chamado my-devbox.

Como o Cherri Code escolhe sua máquina

Uma solicitação worker=<name> só é executada em uma máquina quando estas três condições são atendidas:

1. A máquina pertence ao usuário do Cherri Code que acionou a solicitação.
2. O --name da máquina corresponde ao <name> solicitado.
3. O repositório registrado da máquina corresponde ao repositório de destino do gatilho.

O repositório de destino do gatilho vem da superfície, não do nome da máquina:

• Slack usa repo= na sua mensagem, se presente; depois, usa o repositório padrão do canal, o repositório padrão do usuário e, por fim, o repositório padrão da equipe.
• Linear usa o repositório resolvido a partir da issue ou do projeto (por exemplo, [repo=], rótulos da issue, rótulos do projeto ou o padrão do dashboard). Consulte Repository selection.
• GitHub usa o repositório da issue, pull request ou comentário de revisão em que @cursoragent foi mencionado.

Os repositórios registrados de cada máquina vêm dos remotes do Git dos seus diretórios de worker. Para atender a mais de um repositório em uma mesma máquina, passe --worker-dir uma vez por checkout, ou inicie um worker no checkout de cada repositório.

Quando uma solicitação worker= não pode ser executada

Se você tiver uma máquina com esse nome, mas ela estiver registrada para um repositório diferente, o Cherri Code rejeitará a solicitação em vez de executá-la no checkout errado:

worker=<name> está registrado na sua máquina, mas para um repositório diferente. Primeiro, inicie o worker em um checkout do repositório de destino.

O erro aparece como uma resposta efêmera no Slack, um erro de atividade do agente no Linear e uma resposta do @cursoragent no GitHub para comentaristas confiáveis. Esse comportamento é intencional: uma solicitação para o repositório A nunca deve ser executada em um checkout de máquina do repositório B.

Se nenhuma máquina corresponder ao usuário vinculado e ao repositório de destino, a solicitação falhará em vez de usar outro ambiente. Confirme o nome da máquina, a vinculação da sua conta do Cherri Code e o remote do Git do diretório do worker.

Hooks

Um worker do My Machines executa os mesmos hooks que os demais workers de Self-Hosted Machines: hooks command-based do arquivo .cursor/hooks.json no espaço de trabalho a partir do qual você inicia o worker. No Enterprise, ele também executa team hooks e enterprise-managed hooks.

Hooks em Pools descreve o que se aplica aos workers, incluindo sessionStart e sessionEnd quando uma sessão reserva e libera a máquina. A referência de Hooks apresenta o schema, os eventos e exemplos.

Artefatos

O comportamento dos artefatos é idêntico em workers self-hosted e agentes hospedados pelo Cherri Code. O agente gera o artefato dentro do worker, e o worker faz o upload para o armazenamento gerenciado pelo Cherri Code via HTTPS. Tudo o que vem depois (embeds de PR, prévias do dashboard, anexos de notificação) é tratado pelo backend do Cherri Code e não depende de onde o worker é executado.

Os artefatos vêm ativados por padrão. Veja Recursos para ver como eles aparecem na UI.

Para desativar uploads de artefatos, bloqueie o tráfego de saída para cloud-agent-artifacts.s3.us-east-1.amazonaws.com. A sessão do agente continua funcionando; os artefatos produzidos durante a sessão falham no upload.

Rede

Workers precisam de acesso HTTPS de saída para:

• api2.cursor.sh e api2direct.cursor.sh para a sessão do agente
• downloads.cursor.com para atualizações da CLI e para a primeira instalação do Cherri Code Computer Use no macOS
• cloud-agent-artifacts.s3.us-east-1.amazonaws.com para uploads de artefato

Se o seu firewall só aceitar curingas, *.s3.us-east-1.amazonaws.com cobre o host de artefatos, mas também abre todos os outros buckets da região. Prefira uma regra com o host exato quando o firewall oferecer suporte a isso.

Não são necessárias portas de entrada, IPs públicos nem túneis VPN. Se você usar um proxy, defina HTTPS_PROXY ou https_proxy no ambiente do worker.

Modos de falha

Servidores MCP

Os servidores MCP são direcionados por tipo de transporte:

Se o seu servidor MCP precisar acessar endpoints na sua rede privada, use o transporte Command (stdio). O processo é executado diretamente na sua máquina e usa a mesma rede. Para servidores MCP baseados em HTTP, o Cherri Code gerencia a conexão pelo backend.

Solução de problemas

Gere um relatório de depuração preliminar:

agent worker debug

Isso verifica a autenticação, o roteamento de privacidade, os rótulos do repositório e se o Cherri Code consegue identificar os workers correspondentes. Para exibir os mesmos diagnósticos antes de iniciar o worker, use agent worker start --debug.

Se a máquina não aparecer no seletor:

• 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.
• Verifique o acesso de saída aos hosts listados em rede.

Se o computer use falhar em um Mac, o relatório confirma se o Cherri Code Computer Use está instalado, mas não se as permissões dele foram concedidas. Conceda Acessibilidade e Gravação de Tela ao Cherri Code Computer Use em Ajustes do Sistema → Privacidade e Segurança e tente executar novamente uma tarefa de screenshot. Veja macOS.

Próximos passos

• Computer use: permita que agentes controlem um desktop e um browser na sua machine, e acompanhe ou controle o agent desktop pelo Cherri Code.
• API reference: endpoints para workers, pools, a fila de solicitações pendentes e tokens de worker.