Máquinas autohospedadas

Las máquinas autohospedadas trasladan la ejecución de herramientas de los agentes en la nube a hardware que tú gestionas. Los agentes en la nube gestionados por Cherri Code siguen siendo la opción predeterminada. El bucle del agente permanece en la nube de Cherri Code. Tu máquina ejecuta las herramientas.

¿Cómo conecto un worker de Self-Hosted Machines en unos minutos?

Instala la CLI de Cherri Code y luego elige una de estas opciones.

Mis máquinas (un ingeniero, un entorno):

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

Usa una clave de API personal en lugar del inicio de sesión por navegador cuando la máquina no tenga navegador:

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

Team Pools (fleet compartida del equipo):

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

Los pool workers del equipo necesitan una service account API key. Las personal API keys registran un worker de Mis máquinas, no un pool worker del equipo.

Los administradores de equipo deben activar los self-hosted workers en el Cloud Agents dashboard antes de que los miembros puedan conectar pool workers del equipo.

Mantén el proceso en ejecución. El worker se conecta de forma outbound mediante HTTPS. No se requieren inbound ports ni VPN.

¿Qué opción de máquina autohospedada debería usar?

¿Qué son las máquinas autohospedadas para los agentes en la nube?

Cherri Code se encarga del bucle del agente: la inferencia y la planificación. Tu código fuente, tus secretos y la ejecución de herramientas permanecen en tu máquina.

Puedes ejecutar workers en una VM, un nodo de Kubernetes, un Mac, un equipo con GPU o un sandbox de un partner. Motivos habituales para usar máquinas autohospedadas:

• Hardware específico, como GPU o Mac para trabajar con iOS
• Secretos y artefactos de compilación que deben permanecer en tu infraestructura
• Registros privados de Git o de paquetes a los que tu máquina ya puede acceder
• Sandboxes en los que tú mismo gestionas la clonación y el estado de git

Si tu única necesidad es acceder a un control de código fuente privado desde la nube de Cherri Code, prueba los agentes en la nube gestionados con conectividad privada antes de operar tus propios workers.

¿Cherri Code ahora es on-prem?

No. Cherri Code no es un producto on-prem. El agent loop permanece en la nube de Cherri Code. Tú registras una máquina que operas y Cherri Code le envía llamadas a herramientas mediante una conexión HTTPS saliente.

Tu checkout, la caché de compilación y las credenciales locales de la máquina permanecen en tu hardware. Consulta ¿Qué datos permanecen en mi máquina y cuáles en la nube de Cherri Code? para ver el reparto completo.

¿En qué se diferencia la conectividad de Self-Hosted Machines respecto a los agentes en la nube gestionados?

Ambas opciones mantienen el agent loop en la nube de Cherri Code. La diferencia está en dónde se ejecutan las herramientas y en cómo se accede a los repositorios privados y a las herramientas internas.

Elige los agentes en la nube gestionados con conectividad privada cuando quieras que Cherri Code opere el entorno de ejecución pero aun así pueda acceder al control de código fuente privado desde la nube de Cherri Code.

Elige Self-Hosted Machines cuando la ejecución deba permanecer en hardware que tú controlas y ese hardware ya pueda llegar a tus repositorios y servicios internos. No hace falta abrir HTTPS de entrada para que Cherri Code acceda a tus herramientas: el worker accede a ellas localmente y devuelve los resultados a través de la sesión saliente.

Consulta ¿Self-Hosted Machines requiere acceso de red entrante o una VPN? para conocer los hosts salientes y Cloud Agents para la configuración gestionada.

¿Cuál es la diferencia entre un pool del equipo y Mis máquinas?

Un pool del equipo es un target de routing con nombre. Los chats esperan en el pool del equipo hasta que un worker los reclama. Cada pool worker del equipo lo reclama un solo agente de programación a la vez.

Mis máquinas (también llamado Control remoto) conecta una máquina de tu propiedad. Pueden ejecutarse varios agentes de programación en la misma máquina si esta cuenta con recursos suficientes.

Para flotas de Kubernetes, parte de la plantilla anysphere/k8s-workers, que ejecuta agent worker controller --spawn en tu cluster sin un CRD. El operator WorkerDeployment, más antiguo, está en desuso; su referencia sigue disponible para los clusters que ya lo ejecutan.

Los pool del equipo requieren un plan Enterprise y una clave de API de cuenta de servicio. Mis máquinas usa una credencial personal.

¿Cómo activan o exigen los admins las máquinas autohospedadas?

Los administradores de equipo abren el dashboard de agentes en la nube y van a los ajustes de Self-Hosted.

• Allow Máquinas autohospedadas: los miembros pueden optar por ejecutar sus tareas en las máquinas que conecten. Sin esa activación, los agentes en la nube usan la infraestructura gestionada de Cherri Code.
• Require Máquinas autohospedadas: toda sesión de agente en la nube debe usar una máquina autohospedada.

El panel de control también muestra los detalles del pool del equipo y las máquinas registradas en Mis máquinas.

¿Puedo ejecutar máquinas autohospedadas en una VM o un sandbox de terceros?

Sí. Los workers del pool del equipo pueden ejecutarse en la plataforma de un partner o a partir de una plantilla de referencia que clones. Cherri Code sigue ejecutando el bucle del agente. El worker de esa VM o sandbox ejecuta las herramientas y se conecta de forma saliente mediante HTTPS.

Consulta Integraciones para ver las guías y plantillas de partners.

Las guías de partners abarcan AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, Tensorlake y SuperServe. Las plantillas de referencia abarcan MicroVMs de AWS Lambda, contenedores de Cloudflare y Kubernetes.

También puedes instalar la CLI de Cherri Code en una VM que ya tengas en ejecución e iniciar tú mismo un worker con agent worker start o agent worker --pool start.

¿Las Self-Hosted Machines requieren acceso de red entrante o una VPN?

No. El worker inicia una única conexión HTTPS saliente desde tu máquina hacia la nube de Cherri Code. Cherri Code envía las solicitudes del agent por esa conexión. Tu máquina nunca necesita ser accesible desde internet.

No necesitas puertos entrantes, cambios en el firewall ni túneles VPN. Si tu red usa un proxy HTTPS, establece HTTPS_PROXY o https_proxy en el entorno del worker.

Los workers necesitan acceso saliente a api2.cursor.sh, api2direct.cursor.sh y cloud-agent-artifacts.s3.us-east-1.amazonaws.com para la carga de artefactos. Consulta Qué sale de tu red para ver el flujo de datos completo.

¿Qué datos permanecen en mi máquina y cuáles en la nube de Cherri Code?

Tu código fuente, los artifacts de compilación, los secretos y la ejecución de herramientas permanecen en tu máquina. Esto incluye las ediciones de archivos, los comandos de terminal y las llamadas de red que el agente hace localmente.

La nube de Cherri Code se encarga del agent loop: las solicitudes de inferencia y la planificación. Los resultados de las llamadas a herramientas vuelven a Cherri Code para la siguiente ronda de inferencia, pero tu código en bruto y tus secretos no se almacenan en la infraestructura gestionada por Cherri Code.

El modo de privacidad se aplica igual que en los agentes en la nube gestionados. Cuando está activado, Cherri Code y los proveedores de modelos no usan el código enviado desde el worker para el entrenamiento.

¿Puedo usar un pool del equipo para cualquier repositorio sin especificar uno?

Sí. Los pools de cualquier repositorio desacoplan el control de código fuente del pool del equipo. Un mismo pool del equipo puede dar servicio a muchos repositorios.

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

Pasa --clone-git-repos para que el worker clone los repositorios al realizar la afirmación. En el selector de entornos del composer de Cherri Code, selecciona el pool del equipo en Any repo.

Sin --clone-git-repos, un pool de cualquier repositorio puede usar una regla de espacio de trabajo de aplicación permanente para asignar sujetos de tareas a repositorios y clonarlos con las credenciales del worker.

En Slack, un administrador de equipo puede ejecutar @Cherri Code pool set <name> para convertir un pool de cualquier repositorio en el pool predeterminado del equipo. A partir de entonces, las menciones a @Cherri Code se inician en ese pool sin necesidad de indicar pool= en el mensaje, incluso cuando no se resuelve ningún repositorio. Añade channel (@Cherri Code pool set <name> channel) para establecer un pool predeterminado del canal, que hace lo mismo en un solo canal.

Esta configuración solo se aplica a los pools de cualquier repositorio. Los pools vinculados a un repositorio enrutan las solicitudes a workers que ya tienen los checkouts correspondientes.

¿Cómo conecto GitLab privado o autohospedado?

Para GitLab autohospedado privado o aislado de la red, usa un pool del equipo any-repo para que el ciclo de vida del SCM se mantenga en tus workers.

1. Crea un pool del equipo sin vincularlo a un repositorio concreto.
2. Inicia workers desde un directorio de workspace en una máquina que pueda llegar a tu instancia de GitLab.
3. Autentica git con un personal access token local o una clave SSH en el worker. No necesitas el OAuth de GitLab de Cherri Code para el checkout del worker.

El agente accede a los repositorios privados a través del acceso de red que ya tiene tu máquina. Este patrón también ayuda cuando los desarrolladores trabajan con muchos repositorios.

Consulta la documentación de la integración con GitLab para configurar Cloud Agent con OAuth en infraestructura gestionada.

¿Los agentes de programación pueden usar la pantalla o el navegador en un worker de Self-Hosted Machines?

Sí, en workers de macOS y Linux. En Linux, primero instala los paquetes de escritorio y luego inicia con --computer-use:

agent worker --computer-use start

En macOS, el primer inicio instala el asistente Cherri Code Computer Use. Concédele permisos de Accesibilidad y Grabación de pantalla. El uso compartido del escritorio con --share-desktop es solo para Linux. Para el uso del navegador, instala Chrome o Chromium en el runner.

Consulta Uso de la computadora y uso compartido del escritorio para conocer las dependencias y la configuración.

¿Funcionan los hooks y MCP en máquinas autohospedadas?

Sí, con algunas diferencias respecto a los agentes en la nube gestionados.

Hooks: los workers ejecutan los hooks del proyecto definidos en .cursor/hooks.json. Los planes Enterprise también disponen de hooks de equipo y hooks gestionados por la empresa en los workers autohospedados. sessionStart y sessionEnd se ejecutan cuando una sesión afirma un worker y cuando esa afirmación se libera. Consulta la matriz de compatibilidad de hooks y Hooks en pools del equipo.

MCP: los servidores MCP de comando (stdio) se ejecutan en tu worker y pueden acceder a redes privadas. Los servidores HTTP y SSE siguen ejecutándose desde el backend de Cherri Code. Aún quedan algunas limitaciones de MCP en los workers autohospedados; consulta el registro de cambios para conocer el estado más reciente.

¿Cómo soluciono problemas en una configuración de Self-Hosted Machines?

Empieza por lo básico:

1. Revisa el dashboard. Abre el Cloud Agents dashboard y confirma que los workers aparecen como conectados, inactivos o en uso en Mis máquinas o en los detalles del pool del equipo.
2. Ejecuta diagnósticos. Ejecuta agent worker debug para las comprobaciones preflight del worker (añade --json para obtener una salida legible por máquina). El informe cubre auth, conectividad, routing y visibilidad del backend.
3. El worker no aparece en la UI. Si el proceso del worker se está ejecutando localmente pero no aparece en Cherri Code, la causa suele ser la conectividad outbound. Comprueba que la máquina pueda acceder a api2.cursor.sh y api2direct.cursor.sh por HTTPS. Consulta ¿Self-Hosted Machines requiere acceso de red inbound o una VPN?.
4. Problemas del controller del pool del equipo. El worker controller built-in es nuevo. Trata las configuraciones de controller y autoescalado como deployments iniciales y documenta las soluciones a medida que surjan patrones en tu equipo.

Informe preflight del worker:

agent worker debug

El informe cubre autenticación, conectividad, routing, etiquetas de repositorio y si Cherri Code puede ver tu worker.

Soluciones comunes:

• Confirma que el proceso del worker sigue en ejecución
• Confirma que la app de Cherri Code y la CLI usan la misma cuenta
• Comprueba que el directorio del worker tenga el git remote esperado para los workers con repositorio
• Comprueba el acceso HTTPS saliente a los hosts indicados en Qué sale de tu red

Si hay problemas de conexión antes de que el worker se inicie, ejecuta agent worker start --debug. Incluye la salida de agent worker debug cuando contactes con soporte por problemas de configuración persistentes.

¿Cómo me aseguro de que se respeten los permisos del SCM?

Las ejecuciones autohospedadas usan dos capas: el routing de Cherri Code (qué worker atiende una solicitud) y las credenciales de git en el worker (qué puede clonar, hacer fetch o push ese worker).

Routing de Cherri Code

• Mis máquinas: Cherri Code solo enruta una solicitud de repositorio a un worker cuando alguna de sus raíces --worker-dir registradas coincide con ese repositorio. Inicia el worker desde el checkout correcto o añade otro --worker-dir.
• Pools del equipo con repositorio: Las solicitudes coinciden tanto con el nombre del pool del equipo como con una label repo=<owner/repo>. Una solicitud para pool=my-pool y repo=acme/payments se enruta únicamente a un worker que sirva ese repositorio.
• Triggers de GitHub: En repositorios públicos, solo los usuarios con acceso OWNER o COLLABORATOR pueden enrutar una ejecución a un pool del equipo autohospedado. Los demás comentaristas permanecen en la infraestructura gestionada, salvo que tu equipo exija autohospedaje para todas las ejecuciones.
• Controles de la organización: Los Ámbitos de Git protegidos y la blocklist de repositorios siguen aplicándose. Conecta la cuenta de Git de cada usuario en Integrations para que Cherri Code pueda verificar el acceso al repositorio antes de que empiece una ejecución.

Acceso a git en el worker

• Checkouts existentes (Mis máquinas o pools del equipo con repositorio): el agente usa las credenciales de git que ya están en la máquina, como claves SSH o un personal access token en tu credential helper. Concede a cada worker solo el acceso a repositorios que necesite.
• Pools del equipo de cualquier repositorio con --clone-git-repos: el worker clona al reclamar la tarea usando un GitHub token de corta duración emitido para el usuario que inició la ejecución. Un administrador del equipo debe activar la emisión de GitHub tokens para los workers de los pools del equipo, y el usuario solicitante debe tener acceso a ese repositorio en GitHub.
• GitLab privado o autohospedado: autentica git en el worker con un PAT local o una clave SSH. Consulta ¿Cómo conecto un GitLab privado o autohospedado?.

Cuando git falla pero el worker está conectado

1. Ejecuta agent worker debug y confirma que las labels de repositorio coinciden con el repositorio de la solicitud.
2. En el worker, ejecuta git fetch o git ls-remote con las mismas credenciales que usará el agente.
3. Confirma que el usuario de Cherri Code que inició la ejecución puede acceder al repositorio en tu proveedor de Git y en Cherri Code Integrations.
4. Para el clonado al reclamar en pools del equipo, confirma que la emisión de tokens está activada y que el pool del equipo es un pool con nombre de tipo cualquier repositorio (no default).

Cherri Code nunca amplía el acceso a repositorios más allá del que ya tiene el usuario que dispara la ejecución. Si una ejecución llega al checkout equivocado o no puede hacer push, corrige las labels de routing o las credenciales de git del worker en lugar de compartir un único token de servicio amplio entre repositorios sin relación.

¿Qué hago si veo límites de uso?

Contacta con soporte.

¿Cómo compruebo si el pool de mi equipo está al límite de su capacidad?

Consulta la capacidad de los workers en el Cloud Agents dashboard. Los detalles del pool del equipo y Mis máquinas muestran los workers por estado.

Para comprobaciones programáticas, llama a la API de resumen:

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

La respuesta incluye el número de workers conectados y en uso de tu usuario y de tu equipo.

Motivos habituales por los que un agent run no se inicia:

• No hay workers conectados: inicia o escala workers en el pool del equipo, o confirma que hay un worker de Mis máquinas en ejecución
• Todos los workers ocupados: las solicitudes esperan en la cola del pool del equipo hasta que se libere un worker
• Límite de private worker superado: tu equipo alcanzó el tope de workers conectados (200 por usuario, 1000 por equipo). Desconecta los workers que no uses o contacta con ventas para hablar sobre límites más altos
• Repositorio incorrecto: inicia el worker desde el checkout correcto o usa un pool del equipo any-repo

Los workers envían señales de actividad mientras están conectados. Un worker desaparece del registry cuando deja de enviarlas. Consulta Team Pools para el escalado y la configuración del controller.

Relacionado

• Agentes en la nube
• Máquinas autohospedadas
• Mis máquinas
• Pools del equipo
• Integraciones
• Uso de la computadora
• Conectividad privada
• Seguridad y red del agente en la nube