Uso de la computadora y uso compartido del escritorio del agente
El uso de la computadora permite que un agente de programación en un worker de máquinas autohospedadas haga clic, escriba, tome capturas de pantalla y controle aplicaciones con UI. Los agentes de programación también pueden controlar un navegador cuando el worker tiene Chrome o Chromium instalado. Funciona en workers de macOS y Linux, tanto para Mis máquinas como para pools del equipo. El uso compartido del escritorio del agente permite que los usuarios autorizados vean o tomen el control de un escritorio del agente en Linux desde Cherri Code. Para conocer el comportamiento del producto en los agentes en la nube gestionados, consulta Capacidades.
El uso de la computadora y el uso compartido del escritorio del agente son funciones nuevas. Instala o actualiza a la última
versión de la CLI de Cherri Code antes de seguir esta guía: ejecuta agent update o reinstálala
con los pasos de Instalar la CLI.
Ambas funciones requieren una activación explícita y el servidor nunca las activa por su cuenta.
El uso de la computadora funciona en workers de macOS y Linux. El uso compartido del escritorio del agente
(--share-desktop) es solo para Linux.
Activar computer use
Inicia el worker con --computer-use. Los flags del worker van antes de start:
agent worker --computer-use startLos pool workers aceptan el mismo flag:
agent worker --pool gpu --computer-use startLo que ocurre a continuación depende del sistema operativo. En macOS, el worker controla la sesión de escritorio iniciada mediante una aplicación auxiliar llamada Cherri Code Computer Use, a la que debes concederle dos permisos de privacidad de macOS. En Linux, el worker usa un display X11 y requiere que antes se instalen los paquetes de escritorio.
macOS
En macOS, el uso de la computadora funciona mediante Cherri Code Computer Use, una pequeña aplicación auxiliar que la CLI gestiona por ti. Hace clic, escribe y captura la pantalla de la sesión de escritorio en la que se ejecuta el worker. No hace falta la aplicación de escritorio de Cherri Code en el worker.
- La instala la CLI. El primer
agent worker --computer-use starten una Mac descarga Cherri Code Computer Use desdedownloads.cursor.comy la instala en~/.cursor/cursor-computer-use/Cursor Computer Use.appsi no está presente. - Una sola identidad de aplicación. Identificador de bundle
co.anysphere.cursor-computer-use, firmado con el Apple Team IDDCNK4UB866. Es una aplicación distinta de Cherri Code Agent Helper (co.anysphere.cursor.agent-helper), que es la que usa--share-desktop. - Requiere un escritorio con sesión iniciada. El worker usa la sesión GUI de inicio de sesión del usuario de macOS que lo ejecuta.
--displayy las pantallas virtuales son solo para Linux. - Requiere dos permisos. macOS exige Accesibilidad (para mover el ratón y escribir) y Grabación de pantalla (para tomar capturas de pantalla) en el caso de Cherri Code Computer Use. El worker no los comprueba ni los solicita por ti: hasta que los concedas, los clics y las capturas de pantalla del agente de programación fallarán.
Instalar Cherri Code Computer Use
Inicia el worker con computer use
Inicia sesión en la Mac con el usuario que ejecutará el worker y luego inícialo:
agent worker --computer-use --name "build-mac-01" startPara un pool worker, añade --pool:
agent worker --pool --computer-use startEl primer inicio instala Cherri Code Computer Use si no está presente y, a continuación, macOS solicita los permisos.
Concede Accesibilidad y Grabación de pantalla a Cherri Code Computer Use
Abre Configuración del Sistema → Privacidad y seguridad. En Accesibilidad, activa Cherri Code Computer Use. En Grabación de pantalla y audio del sistema (llamada Grabación de pantalla en versiones anteriores de macOS), activa Cherri Code Computer Use.
Concede los permisos a Cherri Code Computer Use, no al Terminal, a tu shell ni a la aplicación de Cherri Code. Los permisos que ya concediste a esas aplicaciones no se heredan. Si macOS te pide salir y volver a abrir la aplicación tras conceder Grabación de pantalla, detén y reinicia el worker.
Verifica la instalación y los permisos
agent worker debugEl informe confirma que Cherri Code Computer Use está instalado, pero no indica el estado de los permisos, así que compruébalo también: inicia el worker y envía una tarea desde cursor.com/agents que pida al agente abrir un navegador, visitar una página y tomar una captura de pantalla. La captura aparece en el chat cuando ambos permisos están concedidos.
macOS 15 (Sequoia) y versiones posteriores piden periódicamente al usuario
con la sesión iniciada que vuelva a confirmar la Grabación de pantalla para
las aplicaciones que capturan la pantalla directamente. Si las capturas de
pantalla dejan de funcionar en un worker de larga duración, busca una
solicitud pendiente de «Permitir durante un mes» en la sesión gráfica y
apruébala; después, vuelve a ejecutar agent worker debug.
Otorgar los permisos de la forma correcta
Ambos permisos los otorga a una app específica el usuario con sesión iniciada. Algunas reglas mantienen la configuración en funcionamiento tras reinicios, actualizaciones y en fleets:
- Otórgalos a Cherri Code Computer Use. macOS vincula cada permiso al identificador de bundle de la app (
co.anysphere.cursor-computer-use) y a su requisito de firma de código. Otorgar Accesibilidad o Grabación de Pantalla a Terminal, iTerm,agent, Cherri Code o Cherri Code Agent Helper no sirve de nada para computer use. - Otórgalos con el usuario del worker. Inicia sesión con la cuenta de macOS que ejecuta el worker antes de otorgar permisos o tomar una instantánea. Las aprobaciones de Grabación de Pantalla corresponden a esa cuenta de usuario.
- Mantén activa una sesión de escritorio. El worker necesita una sesión gráfica con sesión iniciada. En máquinas que se reinician sin supervisión, activa el inicio de sesión automático para el usuario del worker y evita que la pantalla se apague en Configuración del Sistema → Pantalla bloqueada y Energía.
- Deja que la CLI gestione la app. Instala y actualiza Cherri Code Computer Use únicamente mediante
agent worker --computer-use start. No copies, vuelvas a firmar ni reconstruyas la app; si cambia la identidad de firma, macOS la tratará como una app nueva y tus permisos otorgados dejarán de aplicarse. - Vuelve a probar después de los cambios. Tras una actualización de macOS o una actualización de la CLI que reemplace Cherri Code Computer Use, ejecuta de nuevo una tarea de captura de pantalla.
No automatices las solicitudes con scripts. Editar la base de datos de privacidad de macOS o desactivar System Integrity Protection rompe las protecciones de las que depende tu Mac y no es compatible. Usa Configuración del Sistema o un perfil de MDM en su lugar.
Usar un bundle de aplicación que implementas tú
Si tu MDM o proceso de creación de imágenes ya coloca Cherri Code Computer Use en la máquina, apunta el worker a ese bundle en lugar de dejar que la CLI descargue uno. Establece CUA_SERVICE_APP en el entorno del proceso agent worker (por ejemplo, en el plist de launchd que lo inicia) con la ruta del bundle .app. El worker usa ese bundle y omite la descarga.
Los permisos concedidos dependen de la identidad de firma de código de la aplicación y de su ubicación de instalación. Si apuntas CUA_SERVICE_APP a un bundle ubicado en otro lugar, o lo cambias por una compilación firmada con otra identidad, macOS lo trata como una aplicación nueva y vuelve a solicitar Accesibilidad y Grabación de pantalla.
Gestionar permisos con MDM
Si tus Mac están inscritos en un MDM, crea un perfil de Privacy Preferences Policy Control (PPPC) para Cherri Code Computer Use. Actualmente Cherri Code no distribuye un archivo .mobileconfig. Apple limita lo que un perfil puede hacer con cada permiso:
| Permiso | Compatibilidad del perfil | Qué hacer |
|---|---|---|
| Accesibilidad | Un perfil puede concederlo de forma silenciosa en la mayoría de las versiones de macOS. Apple deja obsoleta la concesión silenciosa de Accesibilidad a partir de macOS 26.2. | Establece Allowed para co.anysphere.cursor-computer-use en el servicio Accessibility. En macOS 26.2 y posteriores, prevé que un usuario deba aprobarlo en Configuración del Sistema. |
| Grabación de pantalla | Un perfil no puede concederlo. Apple exige que una persona lo apruebe en Configuración del Sistema. | Establece AllowStandardUserToSetSystemService para co.anysphere.cursor-computer-use en el servicio ScreenCapture para que un usuario estándar (sin permisos de administrador) pueda aprobarlo sin una contraseña de administrador. |
Cada entrada del payload necesita el identificador de bundle, el ID de equipo (DCNK4UB866) y el requisito de código. Lee el requisito de código desde la app que instaló la CLI para que coincida con la versión que lanzas:
codesign -d -r - ~/.cursor/cursor-computer-use/Cursor\ Computer\ Use.appDado que Screen Recording siempre requiere una aprobación humana, prevé una aprobación por cada imagen y no una por cada máquina. Consulta la siguiente sección.
Preparar una fleet: conceder una vez y luego crear la imagen
Los permisos persisten en la máquina, así que concédelos una sola vez en un Mac de plantilla, comprueba que funcionan y crea una instantánea. Cada worker restaurado a partir de esa imagen arranca con computer use listo, siempre que la app, su ruta y el usuario con sesión iniciada sigan siendo los mismos. El patrón es conceder, verificar y crear la instantánea.
Preparar la plantilla
Inicia sesión como el usuario del worker. Instala la CLI e inicia sesión o establece la clave de API del pool. Activa el inicio de sesión automático para este usuario, de modo que la sesión de escritorio exista tras un reinicio.
Instalar y conceder
Ejecuta agent worker --computer-use start una vez para que la CLI instale Cherri Code Computer Use. Concede Accesibilidad y Grabación de pantalla a Cherri Code Computer Use, o envía tu perfil PPPC y aprueba Grabación de pantalla. Detén el worker.
Verificar
agent worker debugConfirma que el informe muestra Cherri Code Computer Use como instalado. Luego inicia el worker y ejecuta una tarea que tome una captura de pantalla y haga clic en algo dentro de una app. Continúa solo cuando la captura llegue y el clic surta efecto; agent worker debug por sí solo no demuestra que los permisos estén concedidos.
Instantánea
Crea la instantánea de la VM o la imagen de disco a partir de este estado. Restáurala en cada worker e inicia el worker con --computer-use bajo launchd o tu gestor de procesos.
Vuelve a conceder los permisos y a crear la instantánea cuando:
- Una actualización de la CLI reemplace Cherri Code Computer Use por una compilación cuya identidad de firma haya cambiado. Las capturas de pantalla y los clics fallarán hasta que vuelvas a conceder los permisos.
- El worker se ejecute con un usuario de macOS distinto del que concedió los permisos.
- Actualices la plantilla a una nueva versión principal de macOS. Vuelve a ejecutar la prueba de captura de pantalla y concede los permisos de nuevo si falla.
Linux
En Linux, computer use usa un display X11. El worker reutiliza un display que ya tengas en ejecución o crea uno propio.
Instalar dependencias
En cada worker de Linux, instala los paquetes de escritorio. Cherri Code no instala los paquetes del sistema por ti:
sudo apt-get install -y --no-install-recommends \ dbus-x11 ffmpeg tigervnc-standalone-server \ x11-utils x11-xserver-utils xdotool xfce4xdotool, ffmpeg y las utilidades de X11 son siempre obligatorios. tigervnc-standalone-server y xfce4 se necesitan cuando el worker crea un escritorio por su cuenta: el display gestionado para el uso de la computadora en máquinas sin interfaz gráfica y el escritorio aislado para compartir el escritorio del agente.
Instala Chrome o Chromium (opcional, recomendado) para el uso de la computadora con navegador.
Para los pools, incluye los paquetes directamente en tu worker image para que cada máquina arranque lista.
Elegir el display X11
El worker determina el display para el uso de la computadora en este orden:
--display <display>. Exige un display X11 existente, por ejemplo:0. Si no se puede acceder al display, el worker no arranca en lugar de recurrir a una alternativa.DISPLAYheredado. Sin--display, el worker reutiliza unDISPLAYaccesible de su entorno. Si no es accesible, el worker recurre a un escritorio gestionado.- Escritorio gestionado. Si no hay ningún display configurado, el worker inicia su propio escritorio TigerVNC con una sesión de Xfce. Es la opción por defecto en máquinas sin interfaz gráfica y requiere los paquetes
tigervnc-standalone-serveryxfce4.
# Reutiliza un escritorio que ya tengas en ejecuciónagent worker --computer-use --display :0 start# Deja que el worker cree un escritorio gestionado (máquinas sin interfaz gráfica)agent worker --computer-use startCompartir el escritorio del agente de programación
El uso compartido del escritorio es independiente del uso de la computadora y es solo para Linux. Para permitir que los usuarios autorizados vean o controlen el escritorio del agente de programación desde Cherri Code, añade --share-desktop:
agent worker --computer-use --share-desktop start--share-desktop acepta un modo opcional: view (solo ver) o view_and_control (quienes lo vean pueden tomar el control del ratón y el teclado; es el valor predeterminado). El uso compartido se basa en un escritorio aislado del agente de programación que crea el worker, no en la sesión propia de la máquina, y requiere tigervnc-standalone-server. Un filtro de entrada fail-closed en la máquina aplica el control, y la transferencia del portapapeles sigue bloqueada.
Los píxeles salen de la máquina únicamente a través de la conexión saliente que el worker ya tiene abierta. No se abre ningún puerto entrante.
Verificar la configuración
Ejecuta el preflight report:
agent worker debugEn macOS, el informe muestra si Cherri Code Computer Use está instalado. No comprueba Accessibility ni Screen Recording, así que verifica esos permisos con una tarea real: pide al agente que tome una captura de pantalla y haga clic en algo. En Linux, el informe comprueba cada binario requerido, si el display configurado es accesible y si el worker puede recurrir a un escritorio gestionado.
Ejecuta agent worker debug para confirmar que Cherri Code Computer Use está instalado.
Si la instalación falló, comprueba que el worker pueda acceder a
downloads.cursor.com. Si está instalado, es que faltan los permisos:
concede Accessibility y Screen Recording a Cherri Code Computer Use en
Configuración del Sistema → Privacidad y seguridad, reinicia el worker y vuelve a ejecutar la
tarea. El worker no comprueba estos permisos por ti.
macOS asocia Accessibility y Screen Recording a una app concreta. El
worker controla el escritorio a través de Cherri Code Computer Use
(co.anysphere.cursor-computer-use), así que es esa app la que necesita los permisos,
no la terminal desde la que se lanzó agent, ni la Cherri Code app, ni Cherri Code Agent
Helper (co.anysphere.cursor.agent-helper), que solo se encarga de
--share-desktop.
No. Apple no permite que un profile autorice Screen Recording. Un profile puede establecer
AllowStandardUserToSetSystemService para que un usuario estándar pueda aprobarlo
sin un administrador, y puedes aprobarlo una sola vez en un template Mac y
crear una instantánea.
No. El CLI instala Cherri Code Computer Use por su cuenta. Los workers suelen ejecutarse en Macs sin ninguna Cherri Code app instalada.
Próximos pasos
- Mis máquinas: conecta una máquina personal con Mac o Linux.
- Pools del equipo: workers compartidos y la referencia completa de flags de
agent worker. - Referencia de la API: endpoints para workers, pools, la cola de solicitudes pendientes y los tokens de worker.
- Capacidades del agente en la nube: control del escritorio y del navegador en agentes en la nube gestionados.