Pools de equipo

Un pool es un destino de enrutamiento con nombre que conecta las solicitudes con los workers de Máquinas autohospedadas. Las solicitudes esperan en el pool hasta que un worker disponible realiza una afirmación sobre ellas. Crea pools separados para distintos entornos de ejecución, como uno para trabajo que necesita GPUs y otro para trabajo que necesita un Mac.

Los pools de equipo están pensados para equipos Enterprise que quieren que los agentes en la nube se ejecuten dentro de una infraestructura gestionada por la empresa. En lugar de que cada desarrollador inicie un worker en una máquina personal, los administradores operan un pool de workers que puede asignarse a agentes de toda la organización.

Los pools son una decisión sobre la propiedad de la infraestructura. No trasladan el bucle del agente fuera de la nube de Cherri Code. El worker ejecuta comandos de terminal, ediciones de archivos, acciones en el navegador y otras llamadas a herramientas en tu infraestructura, mientras que Cherri Code se encarga de la orquestación, el acceso a modelos y la experiencia de los agentes en la nube.

Usa un pool cuando necesites:

• Workers gestionados de forma centralizada para un equipo u organización
• Autenticación con cuenta de servicio en lugar de inicios de sesión individuales en el navegador
• Kubernetes, autoescalado o capacidad gestionada de forma centralizada
• Etiquetas que dirijan el trabajo al entorno, equipo, repositorio o perfil de hardware correctos
• Hosts de la empresa para la ejecución de herramientas, salidas de compilación, registros de workers y monitorización

Para una configuración personal rápida, consulta Mis máquinas. Consulta Requisitos en la visión general de Máquinas autohospedadas para conocer el plan, las credenciales, los ajustes del Panel de control y las dependencias de máquina que necesitan los pools.

Cómo funciona

Un worker abre una conexión HTTPS saliente de larga duración con la nube de Cherri Code. El bucle del agente, incluida la inferencia y la planificación, se ejecuta en la nube de Cherri Code y envía llamadas a herramientas a través de esta conexión. El worker ejecuta esas llamadas a herramientas en tu infraestructura: comandos de terminal, ediciones de archivos, acciones del navegador y acceso a servicios internos.

Tus repositorios, cachés de compilación, secretos y la ejecución de herramientas permanecen en tu entorno, mientras Cherri Code se encarga de la orquestación, el acceso a modelos y la experiencia del agente en la nube. Los artefactos del agente en la nube, como capturas de pantalla y videos, se suben a Cherri Code para que puedas consultarlos en las PR y en el Panel de control.

Los workers solo necesitan acceso saliente. No se requieren puertos de entrada, IP públicas ni túneles VPN. Consulta Redes para ver la lista completa de hosts necesarios.

Requisitos previos

• Un plan de Cherri Code Enterprise
• Ajustes de autohospedado configurados por un administrador de equipo en el panel de control de agentes en la nube:
  • Permitir máquinas autohospedadas permite a los usuarios activar ejecuciones autohospedadas.
  • Requerir máquinas autohospedadas dirige cada ejecución de agente en la nube a workers autohospedados.
• Una clave de API de cuenta de servicio para la autenticación del worker del pool
• Una máquina o imagen de worker con:
  • agent CLI instalado
  • git instalado y disponible en PATH (obligatorio cuando el worker sirve git remotes o usa --clone-git-repos; opcional para los pools de cualquier repositorio si sus propios scripts se encargan del SCM)
  • Un directorio de espacio de trabajo (un repositorio clonado con un remoto configurado, o un directorio any-repo)
  • Acceso a las herramientas de compilación, los repositorios de paquetes, los secretos y los servicios internos que sus agentes necesitan

Instala la CLI

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

Comprueba que la CLI esté disponible:

agent --version

Autenticar workers

Los workers del pool se autentican con una clave de API de cuenta de servicio o con un token de sesión emitido a partir de esa clave para una única afirmación.

Las claves de API de usuario, personales, de equipo y de organización no pueden iniciar workers del pool. Usa claves de API personales o de usuario con workers personales en Mis máquinas.

export CURSOR_API_KEY="your-service-account-api-key"

También puedes proporcionar la clave directamente:

agent worker --api-key "your-service-account-api-key" start

Inicia un worker del pool

Ejecuta el worker desde el espacio de trabajo al que debe servir (la raíz de un repositorio de Git o un directorio any-repo):

cd /path/to/repoagent worker --pool start

--pool registra el worker para asignarlo a un pool. Pasa un nombre opcional para unirte a un pool con nombre (por ejemplo, --pool my-pool). Si se omite el nombre, el worker se une a default. Cada sesión del agente en la nube usa un worker a la vez.

Para entornos orquestados, combínalo con --idle-release-timeout para que el proceso termine correctamente al completar el trabajo:

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout mantiene el worker activo durante un intervalo (en segundos) después de que termina una sesión para procesar mensajes de seguimiento. El valor predeterminado es 3600 segundos. Consulta Ciclo de vida de la sesión para saber cómo funcionan la liberación y la reconexión.

Activar el uso de la computadora

Pasa --computer-use para que los agentes de programación afirmados puedan hacer clic, escribir, tomar capturas de pantalla y manejar aplicaciones en el worker:

agent worker --pool my-pool --computer-use start

En macOS, el primer inicio instala la aplicación auxiliar Cherri Code Computer Use. Concédele permisos de Accesibilidad y Grabación de pantalla, verifícalo con una tarea que tome una captura de pantalla y luego crea una instantánea de la máquina para que cada worker restaurado desde la imagen quede listo. En Linux, incluye los paquetes de escritorio en la imagen del worker. Consulta uso de la computadora y compartir escritorio para ver los pasos de permisos en macOS, las recomendaciones sobre perfiles MDM y las opciones de display en Linux.

Registrar varias raíces de repositorio

La compatibilidad con varios repositorios en modo autohospedado se configura al iniciar el worker registrando varias raíces del espacio de trabajo. Pasa --worker-dir una vez por cada raíz de repositorio local. La primera raíz es el repositorio principal para la identidad de asignación y para mostrarse en el Panel de control. Todas las raíces quedan expuestas al entorno de ejecución del agente, y las raíces con orígenes de git válidos registran metadatos de enrutamiento de repositorios.

--worker-dir se puede repetir hasta 20 rutas. Cada ruta debe existir previamente y ser un directorio. Si no pasas --worker-dir, la CLI usa el directorio de trabajo actual.

Antes de empezar, activa los workers autohospedados en Panel de control > Agentes en la nube > Autohospedado. Usa rutas con permisos de escritura en $HOME, salvo que la imagen de tu máquina garantice otra ubicación con permisos de escritura.

Configuración de ejemplo:

export WORKER_ROOT="$HOME/cursor-repos/my-org"mkdir -p "$WORKER_ROOT"git clone [email protected]:my-org/app.git "$WORKER_ROOT/app"git clone [email protected]:my-org/infra.git "$WORKER_ROOT/infra"export CURSOR_API_KEY="<key>"

Ejecuta una verificación previa antes de iniciar el worker:

agent worker \  --pool my-pool \  --name app-infra-worker \  --worker-dir "$WORKER_ROOT/app" \  --worker-dir "$WORKER_ROOT/infra" \  debug --json

Inicia el worker con los mismos directorios raíz:

agent worker \  --pool my-pool \  --name app-infra-worker \  --worker-dir "$WORKER_ROOT/app" \  --worker-dir "$WORKER_ROOT/infra" \  start --verbose

Coloca las opciones del worker antes de start o debug. Deja el proceso en ejecución bajo un supervisor como systemd, tmux, launchd, Kubernetes o tu propio gestor de procesos.

Los registros detallados de inicio son la referencia definitiva de las raíces registradas. Un worker multi-repo iniciado correctamente muestra cada etiqueta de repo derivada, las rutas del espacio de trabajo y las URL del repositorio:

repo=my-org/apprepo=my-org/infraworkspacePaths: [app, infra]x-repository-urls: ["[email protected]:my-org/app.git","[email protected]:my-org/infra.git"]

Usa --name y --pool <name> para que los workers multi-repo sean fáciles de identificar en el Panel de control y en los triggers.

En modo pool, solo un Agente en la nube puede realizar la afirmación del worker a la vez. Sin --pool, se permite la asignación compartida. Añade --management-addr 0.0.0.0:8080 antes de start cuando necesites /healthz, /readyz y /metrics para un orquestador.

Los directorios que no son de Git pueden ser raíces de ejecución, pero no aportan metadatos de enrutamiento de repositorios. Para un worker multi-repo, clona cada repositorio antes de iniciar el worker. Para empezar desde un espacio de trabajo vacío y dejar que el worker configure el control de código fuente tras la asignación, usa un pool de cualquier repositorio.

Pools de cualquier repositorio

Los pools tienen dos configuraciones de repositorio. Un pool con repositorio vincula el pool a uno o varios repositorios: las solicitudes llevan una etiqueta repo=<owner/repo>, coinciden con los workers que sirven ese repositorio y aparecen bajo el repositorio en el panel de control. Un pool de cualquier repositorio deja el control de código fuente en tus manos: las solicitudes coinciden solo por el nombre del pool y el pool aparece en Any repo en el panel de control.

Si prefieres gestionar el control de código fuente por tu cuenta, crea un pool sin repositorio adjunto. Un worker del pool no requiere un git remote. Apunta --worker-dir a cualquier directorio existente cuando quieras que el agente (o tu propia imagen, hooks y scripts) gestione la clonación y el estado de git:

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

Para dar instrucciones de repositorio a cada solicitud de cualquier repositorio, crea un archivo .mdc en .cursor/rules dentro del directorio pasado a --worker-dir. El nombre del archivo es arbitrario. Este ejemplo usa repo-info.mdc:

---alwaysApply: true---Este worker de cualquier repositorio puede clonar desde `github.acme.internal` con laCLI `gh` preautenticada.- Para solicitudes sobre pagos, facturación o checkout, usa  `platform/payments-service`. Si no está, ejecuta:  `GH_HOST=github.acme.internal gh repo clone platform/payments-service`- Para solicitudes sobre el portal de miembros o los ajustes de la cuenta, usa  `web/member-portal`. Si no está, ejecuta:  `GH_HOST=github.acme.internal gh repo clone web/member-portal`- Clona solo los repositorios necesarios para la solicitud. Ejecuta los comandos  posteriores desde el repositorio clonado.- Si ninguna correspondencia coincide con la solicitud, informa de que el repositorio no está  configurado. No adivines un nombre de repositorio, una URL de clonación ni credenciales.

alwaysApply: true incluye la regla en cada solicitud. Mantén el archivo en el directorio del worker para que esté disponible antes de la clonación, y sustituye los mapeos de ejemplo por tus repositorios y comandos de SCM.

Para que el worker haga checkout de los repositorios del agente afirmado al reclamarlo, pasa --clone-git-repos. Esto requiere activación explícita. El comportamiento predeterminado de any-repo no clona.

agent worker --pool my-pool --clone-git-repos start

--clone-git-repos implica --mint-github-token. Las clonaciones y las obtenciones (fetch) usan ese token de GitHub de corta duración emitido. Un administrador de equipo debe activar la emisión de tokens de GitHub para los workers del pool de equipo, y git debe estar en el PATH.

Usa este flag solo en workers de pools de cualquier repositorio: un --pool con nombre distinto de default, sin repositorio vinculado (repo=) y sin máquina vinculada (name=). La CLI termina con un error claro si se trata de un worker con repositorio vinculado, una máquina con nombre, el pool default o un worker personal de Mis máquinas.

Los nombres de rama se clonan con --branch. Un SHA de commit completo de 40 caracteres usa un checkout desacoplado tras la clonación. Usa remotos de GitHub por HTTPS para que el token emitido pueda autenticarse.

Si el directorio del worker, o una carpeta situada directamente dentro de él, ya tiene un checkout limpio de un repositorio afirmado, el worker lo reutiliza en lugar de volver a clonarlo. El remoto origin del checkout debe apuntar al mismo host y owner/repo. El worker obtiene (fetch) la rama, etiqueta o commit solicitado, hace checkout y solo avanza una rama local mediante fast-forward. Si no puede actualizar el checkout de forma segura, clona en una carpeta nueva junto a él; por ejemplo, cuando el checkout tiene:

• Cambios sin confirmar en archivos con seguimiento
• Commits locales en la rama solicitada que el remoto no tiene
• Un merge, rebase, cherry-pick, revert o bisect en curso
• Submódulos configurados
• Configuración de Git o hooks que un clon nuevo no tendría

La reutilización requiere git 2.26 o posterior; con versiones anteriores de git, el worker clona. El log del worker indica por qué reutilizó o no cada checkout.

Cuando termina una reclamación, el worker elimina los repositorios que clonó para ella y conserva los checkouts reutilizados. Para evitar clonar un repositorio grande en cada reclamación, clónalo en el directorio del worker antes de iniciarlo.

Si la clonación falla, la solicitud permanece en la cola. Los operadores ven un fallo de clonación genérico.

--clone-git-repos, --mint-github-token y --sync-dashboard-secrets asumen un worker por contenedor o usuario del sistema operativo. No se admite alojar varios workers con credenciales activadas bajo el mismo usuario.

Los pools de cualquier repositorio omiten las etiquetas de enrutamiento repo=. Inicia agentes en ellos con env.type: "pool" y env.name establecido con el nombre del pool, y omite repos (consulta crear un agente). Elige el pool en Any repo en cursor.com/agents. En Slack, un pool de cualquier repositorio establecido como pool predeterminado del equipo o como pool predeterminado del canal permite que @Cherri Code inicie un agente incluso cuando no se resuelve ningún repositorio a partir del mensaje o de los valores predeterminados.

Gestionar pools

Los pools son duraderos. Un pool sigue registrado y seleccionable después de que se desconecte el último worker, de modo que puedes escalar a cero y recuperar capacidad cuando lleguen solicitudes. Iniciar un worker con un nombre de pool nuevo crea el pool de forma implícita. Gestiona los pools con antelación mediante la API de Cloud Agents:

• POST /v0/private-workers/pools registra un pool por adelantado, antes de que se conecte ningún worker. Incluye repoOwner, repoName y repoUrl para un pool con repositorio, u omítelos para un pool de cualquier repositorio.
• GET /v0/private-workers/pools lista los pools con el número de workers conectados y en uso.
• DELETE /v0/private-workers/pools elimina un pool de forma lógica. No afecta a las máquinas conectadas actualmente al pool.

Usa Listar pools y las solicitudes pendientes para decidir cuándo volver a escalar los workers.

Nombres de los pools

Agrupa los workers de un pool bajo un nombre cuando quieras que las sesiones se dirijan a un subconjunto específico, como máquinas con GPU, una flota de staging o máquinas de compilación dedicadas de un equipo.

Pasa el nombre a --pool:

agent worker --pool my-pool start

Cuando se omite el nombre, el worker se une al pool default. Las versiones de CLI más antiguas que solo admitían un --pool booleano junto con un --pool-name separado siguen funcionando; --pool-name es un alias en desuso de --pool <name>.

Establece el nombre del pool desde el entorno cuando un orquestador inyecta la configuración:

export CURSOR_WORKER_POOL_NAME=my-poolagent worker --pool start

Los workers de uso múltiple (iniciados sin --pool) no pertenecen a ningún pool.

En el panel de control de agentes en la nube, selecciona un pool en el selector de workers al iniciar una sesión o al editar una automatización. También puedes incluir pool=<name> en un trigger de Slack, GitHub o Linear. Las sesiones se dirigen solo a los workers registrados con ese nombre de pool.

Activar agentes de pool

Usa triggers de pool cuando quieras que un agente en la nube se ejecute en la flota compartida de workers de tu equipo. Los workers del pool son el destino adecuado para capacidad gestionada de forma centralizada, autoescalado, runners similares a los de CI e infraestructura limitada al repositorio.

Los administradores de equipo controlan el enrutamiento autohospedado desde la sección autohospedado del Panel de control de agentes en la nube. Permitir máquinas autohospedadas permite a los usuarios activarlo por solicitud. Sin esta activación, las ejecuciones usan la infraestructura gestionada de Cherri Code. Requerir máquinas autohospedadas enruta las ejecuciones de agentes en la nube a workers autohospedados.

Cuando Cherri Code inicia un agente de pool, asigna workers según sus etiquetas. Las solicitudes de pool para un repositorio incluyen una etiqueta repo=<owner/repo>; las solicitudes a un pool de cualquier repositorio sin repositorio la omiten. Las solicitudes para un pool con nombre también incluyen pool=<name>.

Los workers del pool gestionan:

• Ejecuciones cubiertas por Requerir máquinas autohospedadas, a menos que la solicitud apunte a un worker específico de Mis máquinas con worker= o machine=
• Solicitudes con self_hosted=true o su forma abreviada, sh=1
• Solicitudes con pool=<name>, que también selecciona ese pool con nombre
• Solicitudes autohospedadas con selección de repositorio desde la superficie de activación, como repo=<owner/repo> cuando sea compatible

repo= selecciona el repositorio de la ejecución. En las ejecuciones de pool de equipo, ese repositorio se convierte en la etiqueta de worker repo=<owner/repo>. No apunta a una máquina personal.

Usa estas opciones desde las integraciones para iniciar agentes de pool:

• Slack: Menciona @Cherri Code con self_hosted=true, sh=1 o pool=<name>. Los administradores de equipo pueden establecer un pool predeterminado del equipo con @Cherri Code pool set <name> para que los miembros se ejecuten en él sin indicar una opción en cada mención. Un pool predeterminado del canal, establecido con @Cherri Code pool set <name> channel, sustituye al predeterminado del equipo en ese canal. Los valores explícitos pool=, worker=, machine= o self_hosted=false anulan ambos predeterminados, y un pool predeterminado any-repo permite que Slack inicie sin un repositorio resuelto.
• GitHub: Comenta @cursoragent self_hosted=true ..., @cursoragent sh=1 ... o @cursoragent pool=<name> ... en un problema, pull request o comentario de revisión.
• Linear: Menciona @Cherri Code en un comentario con self_hosted=true, sh=1, pool=<name> o [pool=<name>]. Cherri Code lee estas opciones de ese comentario, no de la descripción del problema. También puedes usar etiquetas de problema o de proyecto donde la etiqueta padre sea pool y la etiqueta hija sea el nombre del pool. Las etiquetas son la única forma de elegir un pool cuando delegas un problema a Cherri Code, porque no hay ningún comentario que leer. Un pool= en el comentario prevalece sobre una etiqueta de pool, y self_hosted=false omite las etiquetas de pool.

Escribe cada opción como key=value. self_hosted y su forma abreviada sh aceptan true, t o 1 para activarlo y false, f o 0 para desactivarlo. Cualquier otra cosa permanece en tu prompt como texto. Esto incluye self_hosted, selfhosted o sh sin valor, y otros valores como sh=/bin/bash. Slack, GitHub y Linear ignoran estas opciones dentro de un bloque de código, así que el código pegado no cambia dónde se ejecuta el agente.

La gestión de políticas depende de dónde se inicie la solicitud:

• Slack rechaza la activación autohospedada cuando Permitir máquinas autohospedadas está desactivado y responde en Slack. Si Requerir máquinas autohospedadas está activado, toda mención en Slack se ejecuta de forma autohospedada.
• GitHub permite que los usuarios OWNER y COLLABORATOR del repositorio enruten ejecuciones a workers autohospedados. Los demás usuarios que comentan se ejecutan en infraestructura gestionada cuando lo activan, o se omiten si Requerir máquinas autohospedadas está activado. Esto protege los repositorios públicos donde colaboradores externos pueden dejar comentarios.
• Linear rechaza las solicitudes autohospedadas explícitas cuando Permitir máquinas autohospedadas está desactivado. El problema recibe un error de actividad del agente que pide a un administrador que active los workers autohospedados o quite la indicación para ejecutarlo en la infraestructura gestionada de Cherri Code.

Para apuntar a una de tus propias máquinas por nombre, usa Mis máquinas con worker= o machine=.

La API de agente en la nube usa el mismo resolvedor con los campos usePrivateWorker y labels. Consulta la documentación de la API de agente en la nube para ver los detalles del endpoint.

Hooks

Los workers de máquina autohospedada ejecutan hooks basados en comandos durante las sesiones del agente en la nube. Cargan la configuración desde el espacio de trabajo que atiende el worker.

• Hooks de proyecto. Haz commit de .cursor/hooks.json y de los scripts a los que hace referencia en el repositorio o el directorio de espacio de trabajo que usa el worker. Es decir, el checkout de git, una raíz --worker-dir o el directorio que indiques para un pool de cualquier repositorio.
• Hooks gestionados por el equipo y por la empresa. En Enterprise, los workers también ejecutan los hooks configurados en el Panel de control web.

La referencia de Hooks cubre el esquema, los eventos y varios ejemplos. Compatibilidad con agentes en la nube indica qué eventos ejecuta el bucle del agente en la nube.

Límites de los agentes en la nube que también se aplican a estos workers de ejecución de herramientas:

• Solo hooks basados en comandos. Los hooks basados en prompts no se ejecutan.
• Sin hooks exclusivos del IDE. Los hooks de Tab (beforeTabFileRead, afterTabFileEdit) y workspaceOpen no se ejecutan en los workers.

sessionStart y sessionEnd sí se ejecutan en los workers de máquina autohospedada. Se disparan cuando una sesión de agente en la nube reclama el worker y cuando esa reserva se libera. Los agentes en la nube gestionados por Cherri Code omiten esos hooks.

Los workers en Kubernetes y otras plataformas orquestadas usan este mismo modelo de hooks.

Etiquetas

Las etiquetas son pares clave-valor que describen un worker. Controlan cómo las sesiones del agente en la nube se dirigen al pool correcto.

agent worker \  --pool \  --label team=backend \  --label env=production \  start

Las etiquetas repo y pool están reservadas. repo proviene del git remote del directorio del worker cuando está presente. pool se establece con --pool. No configures ninguna manualmente.

Servidores MCP

Los servidores MCP en workers autohospedados se enrutan según el tipo de transporte:

Si tu servidor MCP necesita acceder a endpoints de una red privada, usa el transporte de comando (stdio). El proceso se ejecuta directamente en el worker y usa su misma red. Para los servidores MCP basados en HTTP, Cherri Code gestiona la conexión desde su backend y se encarga de OAuth y de la caché de sesiones.

Artefactos

El comportamiento de los artefactos es idéntico tanto en los workers autohospedados como en los agentes alojados por Cherri Code. El agente genera el artefacto dentro del worker, y el worker lo carga en el almacenamiento gestionado por Cherri Code a través de HTTPS. Todo lo demás (embeds de PR, vistas previas del panel de control y archivos adjuntos de notificaciones) lo gestiona el backend de Cherri Code y no depende de dónde se ejecute el worker.

Los artefactos están activados de forma predeterminada. Consulta Capacidades para ver cómo aparecen en la interfaz de usuario.

Para desactivar la carga de artefactos, bloquea el tráfico saliente a cloud-agent-artifacts.s3.us-east-1.amazonaws.com. La sesión del agente sigue funcionando; los artefactos generados durante la sesión no se cargan.

Redes

Los workers necesitan acceso HTTPS saliente a:

• api2.cursor.sh y api2direct.cursor.sh para la sesión del agente
• downloads.cursor.com para las actualizaciones de la CLI y la primera instalación de Cherri Code Computer Use en macOS
• cloud-agent-artifacts.s3.us-east-1.amazonaws.com para subir artefactos

Si tu firewall solo puede usar comodines, *.s3.us-east-1.amazonaws.com cubre el host de artefactos, pero también abre todos los demás buckets de la región. Siempre que el firewall lo permita, es preferible usar una regla de host exacto.

No se requieren puertos de entrada, IPs públicas ni túneles VPN. Si usas un proxy, establece HTTPS_PROXY o https_proxy en el entorno del worker.

Modos de fallo

La sección Prerrequisitos cubre el conjunto más amplio de hosts que un worker necesita durante las ejecuciones del agente (hosts de Git, registros de paquetes y API internas).

Implementar en Kubernetes

Ejecuta workers del pool en Kubernetes cuando quieras que sea la plataforma la que se encargue de la planificación, los health checks y el ciclo de vida de los Pods. Empieza por anysphere/k8s-workers: un ejemplo de Helm que ejecuta el controlador de workers en tu cluster con --spawn. El spawn hook crea un Pod de worker por cada solicitud afirmada, o bien el controlador mantiene Pods idle precalentados con --warm-idle. No se requiere ningún CRD.

Otros hosts funcionan igual: cualquier VM, contenedor o máquina bare-metal que pueda instalar la CLI de Cherri Code y conectarse a Cherri Code mediante HTTPS saliente puede ejecutar un worker del pool con systemd, Docker o tu propio gestor de procesos. Para ver guías de partners y plantillas de referencia sobre AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, Tensorlake, Coder y SuperServe, consulta Integraciones.

Worker controlador

agent worker controller inicia workers a partir de un spawn hook --spawn. El spawn hook puede bifurcar un proceso, iniciar un contenedor o crear un Pod de Kubernetes, como hace la plantilla k8s-workers. --warm-idle es la vía para la capacidad precalentada: el controlador ejecuta el spawn hook una vez por cada worker inactivo que falte, en lugar de modificar un Deployment o un HPA. WorkerDeployment.spec.readyReplicas pertenece al Kubernetes operator en desuso; solo los clústeres que ya lo ejecutan necesitan ese control.

--spawn <path> es obligatorio. El spawn hook se ejecuta una vez tras una afirmación exitosa, o una vez por cada worker precalentado que falte. El entorno del spawn hook incluye CURSOR_API_KEY (o CURSOR_AUTH_TOKEN en su lugar con --session-token), CURSOR_API_URL, CURSOR_API_ENDPOINT, CURSOR_AGENT_WORKER_ID y los campos de la solicitud. Autentícate con una clave de cuenta de servicio mediante --api-key o CURSOR_API_KEY. La clave determina el equipo. No se usa el inicio de sesión por sesión.

El spawn hook recibe todo lo que necesita como variables de entorno:

El spawn hook debe iniciar un worker con el mismo worker id:

#!/usr/bin/env bashset -euo pipefailagent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start

La CLI del worker también lee CURSOR_AGENT_WORKER_ID del entorno, por lo que un spawn hook que arranque un contenedor puede pasar las variables por esa vía:

#!/usr/bin/env bashset -euo pipefaildocker run -d \  -e CURSOR_API_KEY \  -e CURSOR_AGENT_WORKER_ID \  -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" \  your-worker-image \  agent worker --pool start

Afirmar y luego iniciar

Modo predeterminado. El controlador enumera las solicitudes pendientes, observa GET /v0/private-workers/pending-requests/stream, afirma cada solicitud y ejecuta --spawn una vez por cada afirmación.

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --pool default

Pool precalentado

--warm-idle <count> mantiene <count> workers inactivos conectados en cada --pool iniciando de forma anticipada workers sin afirmar. Nunca llama a claim. Cherri Code asigna los agentes de programación en cola a esos workers precalentados.

El controlador se reconcilia con GET /v0/private-workers/pools cada 60 segundos. El flujo SSE de solicitudes pendientes solo acelera la carga retroactiva.

El modo precalentado requiere --pool y no se puede combinar con --all-pools. Ejecuta un solo controlador precalentado por pool: no existe un lease de arranque en el servidor, por lo que varios controladores simultáneos pueden arrancar workers de más de forma transitoria.

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --warm-idle 5

Tokens de sesión

De forma predeterminada, cada máquina que inicia el spawn hook guarda la clave de API de cuenta de servicio. Con --session-token, el controlador solicita un token de sesión para cada afirmación y se lo entrega al hook en lugar de la clave, de modo que esta permanece en el controlador.

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --session-token

El hook recibe CURSOR_AUTH_TOKEN y CURSOR_AUTH_TOKEN_EXPIRES_AT en lugar de CURSOR_API_KEY. Guarda el token en un archivo e inicia el worker con --auth-token-file:

#!/usr/bin/env bashset -euo pipefailprintf '%s' "$CURSOR_AUTH_TOKEN" > /run/cursor/tokenagent worker --pool "$CURSOR_POOL" --auth-token-file /run/cursor/token start

Un token de sesión:

• Sirve para una sola afirmación. Solo puede conectar el worker id afirmado, y Cherri Code lo rechaza en cualquier endpoint al que un worker no llame.
• Expira con su afirmación. Deja de funcionar cuando se libera la afirmación o cuando la clave de cuenta de servicio que lo emitió se elimina o caduca. La caducidad de 7 días en CURSOR_AUTH_TOKEN_EXPIRES_AT actúa como medida de respaldo.
• Se puede reemplazar. Un worker que necesita un token para una afirmación que ya tienes, como una máquina hibernada reactivada o una ejecución que dura más que su token, obtiene uno desde Create A Session Token. El controlador se encarga de esto por ti cuando reactiva una máquina hibernada. Escribe el token de reemplazo en el mismo archivo; el worker vuelve a leerlo cuando se reconecta.

Los workers precalentados se inician antes de que exista ninguna afirmación, por lo que los controladores con --warm-idle siguen pasándole la clave de API al hook. Cuando Cherri Code rechaza un token de sesión, el worker finaliza y muestra el motivo, como la hora de caducidad del token o que su afirmación ha terminado.

Si prefieres crear tu propio controlador, usa la API de Cloud Agents.

Ciclo de vida de la sesión

Una vez que un worker se asigna a una solicitud, Cherri Code reenvía todas las llamadas a herramientas del agente directamente a la máquina. La conexión tiene un tiempo de espera por inactividad de 1 hora de forma predeterminada. Configúralo según sea necesario:

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout (variable de entorno CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) es el número de segundos que el worker permanece conectado tras finalizar una sesión, a la espera de mensajes de seguimiento. Si llega un mensaje de seguimiento, el temporizador se reinicia. Cuando vence el tiempo de espera, la CLI finaliza con el código 0 para que un supervisor pueda reciclar la máquina. Usa 0 para desactivar la liberación por inactividad. Liberar una afirmación es una API aparte: deja de dar preferencia a esa máquina para el agente, pero no cierra la CLI del worker.

Cuando un worker agota su tiempo de espera, Cherri Code lo marca como liberado. La máquina puede reiniciarse y volver a entrar en el pool. Si un usuario reinicia un chat que se ha desconectado de su máquina, el chat se vuelve a conectar a una máquina nueva del pool. El estado del workspace de la máquina original no se conserva, salvo que el pool use hibernación.

Hibernación

Una máquina del pool no tiene por qué permanecer en línea mientras su agente está inactivo. Cuando termina una sesión, el worker espera mensajes de seguimiento hasta que se cumple su tiempo de espera por inactividad, y mantener todas las máquinas encendidas entre interacciones sale caro.

La contrapartida es la localidad del workspace. Sin hibernación, un mensaje de seguimiento que llega después de que la máquina se haya liberado vuelve a adquirir capacidad del pool: el agente acaba en una máquina nueva y puede dedicar sus primeros minutos a reconstruir el workspace que ya tenía. Con hibernación, la máquina vuelve con su workspace intacto y el mensaje de seguimiento retoma el trabajo donde el agente lo dejó.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "my-pool",    "workerReadyTimeoutSeconds": 900  }'

export CURSOR_AGENT_WORKER_ID="<claimedWorkerId>"agent worker --pool my-pool start

Crea tu propio controlador

El controlador integrado cubre la mayoría de las configuraciones. Si necesitas lógica personalizada, por ejemplo tu propia planificación, cuotas o ubicación de máquinas, crea un controlador sobre la API de Cloud Agents. Un controlador hace tres cosas: observar la cola de solicitudes, afirmar una solicitud e iniciar un worker para ella. Los mismos endpoints sirven para supervisar el uso y el autoescalado fuera de Kubernetes.

Autentícate con la clave de API de la cuenta de servicio del pool mediante Basic auth o Bearer token. Otros tipos de clave de API no pueden gestionar la capacidad de workers del pool.

Supervisar la cola de solicitudes

Consulta la cola una vez para hacerte una idea de las solicitudes pendientes y, después, sigue los cambios en tiempo real mediante Server-Sent Events (SSE).

Empieza con GET /v0/private-workers/pending-requests. Añade ?pool=<name> para observar un único pool. Pagina hasta el final y conserva el streamCursor de la respuesta:

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pending-requests?pool=my-pool&limit=50" \  -u "$CURSOR_API_KEY:"

Después, abre el flujo de eventos con GET /v0/private-workers/pending-requests/stream, pasando ese streamCursor y los mismos filtros. Mantén tu vista actualizada a medida que lleguen los eventos: añade solicitudes con los eventos created y claimed_offline, y elimínalas cuando veas claimed o expired:

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?pool=my-pool&cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

Los cursores expiran cinco minutos después del listado que los emitió. Cuando el flujo devuelva 410 Gone, vuelve a listar y reabre el flujo desde el nuevo streamCursor. Mejor aún: vuelve a listar cada cinco minutos con algo de jitter en lugar de esperar al 410.

El número de solicitudes que ves es la profundidad de la cola del pool. Cuando crezca, añade workers. Trata los eventos como indicios y el listado como fuente de verdad: la entrega de eventos se hace en la medida de lo posible y cada nuevo listado corrige cualquier desviación. Consulta Watch Pending Pool Requests para conocer todas las garantías de entrega y las reglas de los cursores.

Enumerar workers

curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

Los workers incluyen name, isInUse, metadata de conexión y campos de repo (repoOwner/repoName son cadenas vacías en los workers any-repo). Consulta la referencia de la API para ver la respuesta completa.

Listar pools

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool" \  -u "$CURSOR_API_KEY:"

Devuelve los pools duraderos con connectedWorkerCount, inUseWorkerCount, isStale y campos de repo opcionales. Los pools de cualquier repositorio omiten los campos de repo. Usa esto para obtener el número de workers conectados y en uso por pool; el resumen de workers de todo el equipo que aparece más abajo no sustituye a la demanda específica de cada pool.

Obtener un resumen de workers

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

Devuelve el número de conexiones y usos de tu usuario y tu equipo. Consulta Get Worker Summary. Usa esto para dimensionar tu respuesta cuando crezca la profundidad de la cola o para activar el escalado cuando la utilización sea alta:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // Escalar: aprovisionar workers adicionales  }}

Obtener worker por ID

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

Afirmar una solicitud pendiente

Los controladores efímeros pueden reservar una solicitud en cola antes de iniciar un worker:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Luego inicia el worker con el mismo id (CURSOR_AGENT_WORKER_ID=pw_123). Consulta Claim A Pending Request.

Para no guardar la clave de la cuenta de servicio en el worker, añade "sessionToken": true al cuerpo. La respuesta incluirá además un token de sesión en token, con su fecha de vencimiento en expiresAt. Guarda el token en un archivo e inicia el worker con --auth-token-file en lugar de la clave.

Emitir un token de sesión

Obtén un token de sesión nuevo para una afirmación que tu equipo ya tiene, por ejemplo, para reactivar una máquina hibernada:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/tokens" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Consulta Create A Session Token.

Liberar una afirmación

Elimina la afirmación que vincula un agente a un worker autohospedado. A partir de ese momento, Cherri Code deja de dar preferencia a esa máquina para el agente:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

Se rechaza una segunda afirmación si ya existe una afirmación activa; libera primero y luego afirma un nuevo workerId. Consulta Release A Claim.

Monitorización

El servidor de gestión expone GET /metrics, GET /healthz y GET /readyz al iniciar un worker con --management-addr:

agent worker --pool --management-addr ":8080" start

Recopila métricas de tu worker:

curl http://localhost:8080/metrics

Métricas disponibles

Indicadores

Contadores

Motivos de finalización de la sesión

El contador cursor_self_hosted_worker_session_ends_total incluye una etiqueta reason con uno de estos valores:

Seguridad

Flujo de datos. Dos cosas salen de tu red: fragmentos de archivos que el modelo lee durante la inferencia y los artefactos del agente en la nube (capturas de pantalla, videos y referencias a registros) que el worker sube al almacenamiento gestionado por Cherri Code para que puedan aparecer en los PR y en el Panel de control. Tus repositorios, cachés de compilación y secretos permanecen en tus máquinas.

Solo saliente. Los workers se conectan por HTTPS mediante conexiones salientes. No se requieren puertos de entrada ni cambios en el firewall.

Modo de privacidad. Los agentes en la nube autohospedados respetan los ajustes del modo de privacidad de Cherri Code. Cuando el modo de privacidad está activado, nada de tu código se usa para entrenamiento.

Aislamiento. Cada sesión del agente recibe su propio worker dedicado. Las sesiones no se comparten entre workers.

Autenticación. Los workers del pool se autentican con una clave de API de cuenta de servicio o con un token de sesión que sirve para una sola afirmación, de modo que la clave nunca llega al worker. Se rechaza cualquier otro tipo de clave de API.

Visibilidad en el Panel de control. Los administradores de equipo pueden ver todos los workers conectados. Los miembros del equipo solo ven los workers que tienen asignados.

Referencia de la CLI

agent worker [options] start

Preguntas frecuentes

Próximos pasos

• anysphere/k8s-workers: plantilla de Kubernetes basado en agent worker controller --spawn, con los modos afirmar y luego iniciar y --warm-idle.
• Integrations: guías de partners y plantillas de referencia para otras plataformas.
• Kubernetes operator (en desuso): referencia para clusters que ya ejecutan el operator de WorkerDeployment.
• Computer use: permite que los agentes de programación controlen un escritorio y un navegador en tus workers.
• Referencia de la API: endpoints para workers, pools, la cola de solicitudes pendientes y los tokens de worker.