Computer use e compartilhamento de desktop
O computer use permite que um agente em um worker de Self-Hosted Machines clique, digite, tire capturas de tela e controle aplicações com UI. Os agentes também podem controlar um navegador quando o worker tem o Chrome ou o Chromium instalado. Funciona em workers macOS e Linux, tanto para My Machines quanto para Team Pools. O compartilhamento de desktop permite que visualizadores autorizados acompanhem ou assumam o controle da área de trabalho de um agente Linux pelo Cherri Code. Para o comportamento do produto em agente na nuvem gerenciados, veja Recursos.
O computer use e o compartilhamento de desktop são novidades. Instale ou atualize para a versão mais recente
da CLI do Cherri Code antes de seguir este guia: execute agent update ou reinstale
seguindo os passos em Instalar a CLI.
Ambas as funcionalidades exigem adesão explícita e nunca são habilitadas pelo server.
O computer use funciona em workers macOS e Linux. O compartilhamento de desktop
(--share-desktop) é apenas para Linux.
Habilitar o computer use
Inicie o worker com --computer-use. As flags do worker vêm antes de start:
agent worker --computer-use startOs workers do pool aceitam a mesma flag:
agent worker --pool gpu --computer-use startO que acontece a seguir depende do sistema operacional. No macOS, o worker controla a sessão de desktop com sessão iniciada por meio de um helper app chamado Cherri Code Computer Use, e você concede a ele duas permissões de privacidade do macOS. No Linux, o worker usa um display X11 e exige que os pacotes de desktop sejam instalados antes.
macOS
No macOS, o computer use é executado pelo Cherri Code Computer Use, um pequeno helper app que a CLI gerencia para você. Ele clica, digita e captura a tela da desktop session em que o worker está sendo executado. O Cherri Code desktop app não é necessário no worker.
- Instalado pela CLI. O primeiro
agent worker --computer-use startem um Mac baixa o Cherri Code Computer Use dedownloads.cursor.come o instala em~/.cursor/cursor-computer-use/Cursor Computer Use.appcaso ele não exista. - Uma única identidade de app. Identificador de bundle
co.anysphere.cursor-computer-use, assinado com o Apple Team IDDCNK4UB866. Este é um app diferente do Cherri Code Agent Helper (co.anysphere.cursor.agent-helper), usado pelo--share-desktop. - Requer um desktop com sessão iniciada. O worker usa a GUI session de login do usuário do macOS que o executa.
--displaye displays virtuais são exclusivos do Linux. - Requer duas permissões. O macOS exige Acessibilidade (para mover o mouse e digitar) e Gravação de Tela (para fazer capturas de tela) para o Cherri Code Computer Use. O worker não verifica nem solicita essas permissões para você. Enquanto você não concedê-las, os cliques e as capturas de tela do agente falham.
Instalar o Cherri Code Computer Use
Iniciar o worker com computer use
Faça login no Mac com o usuário que vai executar o worker e depois inicie-o:
agent worker --computer-use --name "build-mac-01" startPara um worker do pool, adicione --pool:
agent worker --pool --computer-use startNa primeira inicialização, o Cherri Code Computer Use é instalado caso não esteja presente, e o macOS solicita as permissões.
Conceder Acessibilidade e Gravação de Tela ao Cherri Code Computer Use
Abra Ajustes do Sistema → Privacidade e Segurança. Em Acessibilidade, ative o Cherri Code Computer Use. Em Gravação de Tela e Áudio do Sistema (chamada de Gravação de Tela em versões mais antigas do macOS), ative o Cherri Code Computer Use.
Conceda as permissões ao Cherri Code Computer Use, e não ao Terminal, ao seu shell ou ao app Cherri Code. Permissões já concedidas a esses apps não valem para ele. Se o macOS pedir para sair e reabrir o app depois de conceder a Gravação de Tela, pare e reinicie o worker.
Verificar a instalação e as permissões
agent worker debugO relatório confirma que o Cherri Code Computer Use está instalado. Ele não informa o estado das permissões, então teste isso também: inicie o worker e envie uma tarefa em cursor.com/agents pedindo ao agente para abrir um navegador, acessar uma página e tirar uma captura de tela. A captura de tela aparece no chat quando as duas permissões estão ativas.
O macOS 15 (Sequoia) e versões posteriores pedem periodicamente que o usuário
conectado confirme novamente a Gravação de Tela para apps que capturam a tela
diretamente. Se as capturas de tela pararem de funcionar em um worker de longa
duração, procure um prompt pendente de "Permitir Por Um Mês" na sessão da
interface gráfica e aprove-o, e depois execute agent worker debug novamente.
Conceda as permissões da forma correta
Ambas as permissões são concedidas a um app específico pelo usuário com sessão iniciada. Algumas regras mantêm a configuração funcionando após reinícios, atualizações e em pools de workers:
- Conceda ao Cherri Code Computer Use. O macOS vincula cada permissão ao identificador de bundle do app (
co.anysphere.cursor-computer-use) e ao seu requisito de assinatura de código. Conceder Acessibilidade ou Gravação de Tela ao Terminal, iTerm,agent, Cherri Code ou Cherri Code Agent Helper não surte efeito algum para o computer use. - Conceda como o usuário do worker. Faça login na conta do macOS que executa o worker antes de conceder permissões ou tirar um snapshot. As aprovações de Gravação de Tela pertencem a essa conta de usuário.
- Mantenha uma sessão de desktop ativa. O worker precisa de uma sessão gráfica com login feito. Em máquinas que reiniciam sem supervisão, ative o login automático para o usuário do worker e mantenha o display ativo em Ajustes do Sistema → Tela Bloqueada e Energia.
- Deixe a CLI gerenciar o app. Instale e atualize o Cherri Code Computer Use somente por meio de
agent worker --computer-use start. Não copie, reassine nem recrie o app; uma identidade de assinatura alterada faz o macOS tratá-lo como um app novo, e suas concessões deixam de valer. - Teste novamente após alterações. Depois de uma atualização do macOS ou de uma atualização da CLI que substitua o Cherri Code Computer Use, execute novamente uma tarefa de screenshot.
Não crie scripts para contornar os prompts. Editar o banco de dados de privacidade do macOS ou desativar o System Integrity Protection quebra as proteções das quais seu Mac depende e não é suportado. Em vez disso, use os Ajustes do Sistema ou um perfil MDM.
Usar um bundle de app implantado por você
Se o seu MDM ou processo de imagem já coloca o Cherri Code Computer Use na máquina, aponte o worker para esse bundle em vez de deixar a CLI baixar um. Defina CUA_SERVICE_APP no ambiente do processo agent worker (por exemplo, no plist do launchd que o inicia) com o caminho do bundle .app. O worker usa esse bundle e pula o download.
As permissões seguem a identidade de assinatura de código do app e o local de instalação. Se você apontar CUA_SERVICE_APP para um bundle em outro local, ou trocar por um build assinado com outra identidade, o macOS o trata como um app novo e solicita novamente Acessibilidade e Gravação de Tela.
Gerenciar permissões com MDM
Se os seus Macs estiverem inscritos em um MDM, crie um perfil de Privacy Preferences Policy Control (PPPC) para o Cherri Code Computer Use. Hoje, o Cherri Code não disponibiliza um .mobileconfig. A Apple limita o que um perfil pode fazer em cada permissão:
| Permissão | Suporte a perfil | O que fazer |
|---|---|---|
| Acessibilidade | Um perfil pode conceder a permissão silenciosamente na maioria das versões do macOS. A Apple descontinua a permissão silenciosa para Acessibilidade a partir do macOS 26.2. | Defina Allowed para co.anysphere.cursor-computer-use no serviço Accessibility. No macOS 26.2 e versões posteriores, considere que um usuário precisará aprovar nos Ajustes do Sistema. |
| Gravação de Tela | Um perfil não pode conceder essa permissão. A Apple exige que uma pessoa aprove nos Ajustes do Sistema. | Defina AllowStandardUserToSetSystemService para co.anysphere.cursor-computer-use no serviço ScreenCapture para que um usuário padrão (não administrador) possa aprovar sem uma senha de administrador. |
Cada entrada do payload precisa do identificador de bundle, do Team ID (DCNK4UB866) e do requisito de código. Leia o requisito de código no app que a CLI instalou, para que ele corresponda ao build que você distribui:
codesign -d -r - ~/.cursor/cursor-computer-use/Cursor\ Computer\ Use.appComo a Gravação de Tela sempre exige aprovação humana, planeje uma aprovação por imagem, e não uma por máquina. Consulte a próxima seção.
Prepare um pool de workers: conceda uma vez e depois gere a imagem
As permissões persistem na máquina, então conceda-as uma vez em um template Mac, comprove que funcionam e tire um snapshot. Todo worker restaurado a partir dessa imagem sobe com o computer use pronto, desde que o app, seu path e o usuário logado permaneçam os mesmos. O padrão é: conceder, verificar, tirar snapshot.
Prepare o template
Faça login como o usuário do worker. Instale a CLI e faça login ou defina a API key do pool. Habilite o login automático para esse usuário, para que a desktop session exista após uma reinicialização.
Instale e conceda as permissões
Execute agent worker --computer-use start uma vez para que a CLI instale o Cherri Code Computer Use. Conceda Acessibilidade e Gravação de Tela ao Cherri Code Computer Use, ou faça push do seu PPPC profile e aprove Gravação de Tela. Pare o worker.
Verifique
agent worker debugConfirme que o relatório mostra o Cherri Code Computer Use instalado. Depois inicie o worker e execute uma task que tire uma captura de tela e clique em algo em um app. Só continue quando a captura de tela retornar e o clique funcionar; o agent worker debug sozinho não comprova que as permissões foram concedidas.
Tire o snapshot
Crie o snapshot da VM ou a imagem de disco a partir desse estado. Restaure-a em cada worker e inicie o worker com --computer-use sob o launchd ou seu gerenciador de processos.
Conceda as permissões e tire um novo snapshot quando:
- Uma atualização da CLI substituir o Cherri Code Computer Use por um build cuja signing identity mudou. Capturas de tela e cliques falham até você conceder as permissões novamente.
- O worker rodar com um usuário do macOS diferente daquele que concedeu as permissões.
- Você atualizar o template para uma nova versão principal do macOS. Execute o teste de captura de tela novamente e, se ele falhar, conceda as permissões outra vez.
Linux
No Linux, o computer use utiliza um display X11. O worker reaproveita um display que você já esteja executando ou cria o seu próprio.
Instalar dependências
Em cada worker Linux, instale os pacotes de desktop. O Cherri Code não instala pacotes de sistema por você:
sudo apt-get install -y --no-install-recommends \ dbus-x11 ffmpeg tigervnc-standalone-server \ x11-utils x11-xserver-utils xdotool xfce4xdotool, ffmpeg e os utilitários X11 são sempre necessários. tigervnc-standalone-server e xfce4 são necessários quando o próprio worker cria um desktop: o display gerenciado para computer use em máquinas headless e o desktop isolado para compartilhamento de desktop.
Instale o Chrome ou o Chromium (opcional, recomendado) para computer use no navegador.
Para pools, inclua os pacotes na sua worker image para que toda máquina já suba pronta.
Escolha o display X11
O worker resolve o display para computer use nesta ordem:
--display <display>. Exige um display X11 existente, por exemplo:0. Se o display não estiver acessível, a inicialização do worker falha em vez de recorrer a uma alternativa.DISPLAYherdado. Sem--display, o worker reutiliza umDISPLAYacessível do seu environment. Se ele não estiver acessível, o worker recorre a um desktop gerenciado.- Desktop gerenciado. Sem nenhum display configurado, o worker inicia seu próprio desktop TigerVNC executando uma sessão do Xfce. Esse é o padrão em máquinas headless e requer os pacotes
tigervnc-standalone-serverexfce4.
# Reutilize um desktop que você já executaagent worker --computer-use --display :0 start# Deixe o worker criar um desktop gerenciado (máquinas sem interface gráfica)agent worker --computer-use startCompartilhar a área de trabalho do agente
O compartilhamento de desktop é separado do computer use e está disponível apenas no Linux. Para permitir que visualizadores autorizados acompanhem ou controlem a área de trabalho do agente pelo Cherri Code, adicione --share-desktop:
agent worker --computer-use --share-desktop start--share-desktop aceita um modo opcional: view (apenas visualizar) ou view_and_control (os espectadores podem assumir o controle do mouse e do teclado; é o padrão). O compartilhamento usa uma área de trabalho do agente isolada, criada pelo worker, e não a própria sessão da máquina, e requer tigervnc-standalone-server. Um filtro de entrada fail-closed na máquina controla o acesso, e a transferência da área de transferência permanece bloqueada.
Os pixels saem da máquina apenas pela conexão de saída já existente do worker. Nenhuma porta de entrada é aberta.
Verificar a configuração
Execute o relatório de pré-verificação:
agent worker debugNo macOS, o relatório mostra se o Cherri Code Computer Use está instalado. Ele não verifica Acessibilidade nem Gravação de Tela, então confirme isso com uma tarefa real: peça ao agente para tirar uma captura de tela e clicar em algo. No Linux, o relatório verifica cada binário necessário, se o display configurado está acessível e se o worker consegue recorrer a um desktop gerenciado.
Execute agent worker debug para confirmar que o Cherri Code Computer Use está instalado.
Se a instalação falhou, verifique se o worker consegue acessar
downloads.cursor.com. Se estiver instalado, então faltam as permissões:
conceda Acessibilidade e Gravação de Tela ao Cherri Code Computer Use em
Ajustes do Sistema → Privacy & Security, reinicie o worker e execute a
tarefa novamente. O worker não verifica essas permissões por você.
O macOS vincula Acessibilidade e Gravação de Tela a um app específico. O
worker controla o desktop por meio do Cherri Code Computer Use
(co.anysphere.cursor-computer-use), então é esse app que precisa das permissões —
e não o terminal que iniciou o agent, o app Cherri Code ou o Cherri Code Agent
Helper (co.anysphere.cursor.agent-helper), que só lida com
--share-desktop.
Não. A Apple não permite que um profile libere Gravação de Tela. Um profile pode definir
AllowStandardUserToSetSystemService para que um usuário padrão consiga aprovar
sem um administrador, e você pode aprovar uma vez em um template Mac e
criar um snapshot dele.
Não. A CLI instala o Cherri Code Computer Use por conta própria. É comum os workers rodarem em Macs sem nenhum app Cherri Code instalado.
Próximos passos
- My Machines: conecte uma máquina Mac ou Linux pessoal.
- Team Pools: workers compartilhados e a referência completa de flags do
agent worker. - Referência da API: endpoints para workers, pools, a fila de solicitações pendentes e tokens de worker.
- Recursos do Cloud Agent: controle de desktop e navegador em Cloud Agents gerenciados.