Builds de agentes en la nube
Los builds preparan el entorno de tu agente en la nube en segundo plano. Cada agente se inicia desde una máquina preparada previamente, con tus repositorios, herramientas y dependencias listos.
Con los builds, obtienes:
- Inicios más rápidos: La clonación, la instalación y la preparación de dependencias se realizan de antemano, para que los agentes arranquen desde un entorno listo en lugar de esperar en cada inicio.
- Inicios fiables: Los agentes siempre se inician desde el último build exitoso. Una instalación fallida o una configuración incorrecta no sustituye al que funciona.
- Entornos observables: Puedes ver cada build, inspeccionar sus registros y commits, y rastrear qué build utilizó cada agente.
Cómo funcionan las creaciones
Una creación es una instantánea arrancable de un entorno de agente en la nube preparado. Cursor crea creaciones antes de las ejecuciones de agentes y mantiene lista para iniciarse la última que se completó correctamente.
Cada creación sigue este ciclo de vida:
- Activación: Una creación se inicia según una programación, después de guardar una versión del entorno, mediante una solicitud manual o a petición de un agente. Consulta Cuándo se producen las creaciones.
- Preparación: Cursor parte de tu imagen base, clona cada repositorio del entorno en su rama predeterminada y ejecuta el comando
installhasta completarlo. - Instantánea: Cursor guarda el estado del disco de la máquina con la versión del entorno y el SHA de commit exacto de cada repositorio.
- Activación: Una creación completada correctamente pasa a estar activa.
- Iniciar agentes: Los nuevos agentes, automatizaciones y revisiones de código se inician desde la creación activa.
Cursor mantiene listas copias precalentadas de las creaciones activas. Esto elimina la clonación de repositorios y la instalación de dependencias del proceso de inicio del agente.
Si una nueva creación falla, los agentes siguen usando la última creación completada correctamente. Una actualización de dependencia defectuosa, un comando de instalación defectuoso o un Dockerfile defectuoso no reemplazan el entorno activo.
Cuándo se ejecutan las creaciones
Cursor inicia una creación por cuatro motivos. La pestaña Creaciones identifica cada una por su tipo de activación.
| Activación | Cuándo se ejecuta |
|---|---|
| Recurrente | Según una programación regular en cada entorno |
| Cambio de configuración | Cuando guardas la configuración del entorno o cambias sus secretos |
| Manual | Cuando seleccionas Activar creación en la pestaña Creaciones |
| Solicitado por el agente | Cuando un agente ejecuta una creación de prueba, por ejemplo, durante la configuración del entorno |
Creaciones recurrentes
Cursor comprueba regularmente cada entorno y lo vuelve a crear cuando hay cambios. Así, la creación activa se mantiene cerca de la cabecera de la rama predeterminada de cada repositorio, para que los agentes comiencen con código actualizado y cachés de dependencias precargadas, en lugar de tener que descargar y reinstalar al inicio.
Creaciones omitidas
Una comprobación recurrente omite la creación cuando no ha habido cambios desde la última completada: no hay commits nuevos en la rama predeterminada de ningún repositorio del entorno ni cambios en la configuración o los secretos. La pestaña Creaciones registra estas comprobaciones con el estado Omitida. Se completan en segundos, no ejecutan comandos de instalación y mantienen la creación activa.
Un flujo constante de entradas recurrentes con estados Omitida y Éxito es el estado esperado en un entorno en buen estado. Los repositorios con poca actividad generan principalmente entradas Omitida. Los repositorios activos se reconstruyen con mayor frecuencia.
Cursor solo omite las creaciones recurrentes. Las creaciones manuales, solicitadas por agentes y por cambios de configuración siempre se ejecutan.
Qué se ejecuta durante una Build y al iniciar un agente
Usa cada comando de entorno en una fase distinta:
| Comando | Cuándo se ejecuta | Úsalo para |
|---|---|---|
install | Durante cada Build | Instalar dependencias, generar código, compilar artefactos y precalentar las cachés de disco |
start | Al inicio de cada ejecución del agente | Iniciar Docker, bases de datos, túneles y otros servicios |
terminals | Al inicio de cada ejecución del agente | Iniciar procesos de la app en terminales tmux compartidas con el agente |
Haz que install sea completo e idempotente. Puede ejecutarse repetidamente, incluso sobre un estado de disco preparado previamente. Comandos como npm install, pnpm install y pip install ya admiten este patrón.
Las Builds solo conservan el estado del disco. Los procesos en ejecución, las exportaciones del shell y
las cachés en memoria se detienen cuando Cursor crea una instantánea de la máquina. Coloca los servicios y
otras tareas específicas de la sesión en start o terminals.
Tus entradas de entorno existentes se siguen aplicando. Las Builds usan instantáneas guardadas, .cursor/environment.json, Dockerfiles, comandos de instalación e inicio, secretos y ajustes de red.
Cómo los Builds gestionan el estado de Git
Un Build registra el commit extraído de cada repositorio al ejecutarse.
- Las ejecuciones de la rama predeterminada parten del commit registrado en el Build activo. Los Builds programados actualizan ese commit en segundo plano. Cuando Actualizar compilación obsoleta está activado y un Build supera tu Umbral de obsolescencia, los agentes obtienen al iniciar el código más reciente de la rama predeterminada. Cuando esta configuración está desactivada, los agentes usan tal cual el commit registrado en el Build. El umbral predeterminado es de 24 horas. Establécelo en
0para obtener siempre los cambios más recientes. - Las ejecuciones de rama de funcionalidad parten del disco preparado del Build activo y, a continuación, Cursor extrae la rama solicitada. El código fuente coincide con la rama seleccionada y reutiliza las dependencias del Build.
- Los entornos multirrepositorio registran un commit por repositorio y preparan todo el espacio de trabajo en conjunto.
Si una rama de funcionalidad modifica las dependencias, el agente recibe el contexto de tu entorno y el comando de instalación para actualizar el entorno antes de realizar pruebas.
Cómo funcionan los secretos con Builds
Los Builds pueden acceder a los secretos del equipo y del entorno. Úsalos para registros de paquetes privados, almacenes de artefactos y otras credenciales necesarias para install.
Los secretos de usuario se añaden solo cuando se inicia un agente. No están disponibles durante los Builds ni pasan a formar parte de una instantánea compartida.
Guardar la configuración del entorno o cambiar sus secretos activa un nuevo Build.
Gestionar creaciones
Abre la pestaña Creaciones de un entorno para:
- Ver el tipo, el estado y la hora de inicio de cada creación
- Abrir una creación para consultar sus detalles y registros
- Seleccionar Activar creación para ejecutar una creación cuando lo necesites
- Activar una creación en borrador o desactivar una creación
- Cancelar una creación en curso
- Iniciar un agente desde una creación específica
- Configurar Actualizar creaciones obsoletas y el Umbral de obsolescencia
Cada ejecución de un agente registra la creación desde la que se inició. Usa esta información de procedencia para comparar el comportamiento del entorno con la configuración exacta y los commits del repositorio incluidos en la creación.
Depurar un Build
Abre un Build fallido para inspeccionar sus eventos y registros. Los agentes de programación seguirán iniciándose desde el Build activo correcto mientras diagnosticas el error.
Para reproducirlo exactamente, inicia un agente de programación desde el Build fallido. El agente de programación abre la máquina en el estado en que falló, donde puede inspeccionar los registros, actualizar el entorno, ejecutar un Build de prueba y verificar el resultado.
También puedes pedir a un agente en la nube que inspeccione y gestione Builds mediante el Cursor Cloud MCP integrado. Por ejemplo:
Inspecciona la última Build fallida de este entorno. Corrige laconfiguración del entorno, ejecuta una Build de prueba y verifícala antes de proponer los comandosfinales para instalar e iniciar.Referencia sobre el comportamiento de las compilaciones
¿Qué Build usa un agente?
De forma predeterminada, un agente usa el Build activo correcto más reciente de su entorno.
También puedes iniciar un agente desde un Build específico para realizar pruebas o depurar.
¿Qué ocurre antes de la primera Build exitosa?
Los agentes usan el flujo de inicio estándar del entorno hasta que la primera Build se completa correctamente. Una Build fallida no interrumpe los flujos de trabajo de los agentes existentes.
¿Qué tan actualizado está el código fuente?
Las ejecuciones de ramas de funcionalidad cambian a la rama solicitada después de que se inicia la compilación. Las ejecuciones de la rama predeterminada comienzan en el commit registrado por la compilación activa. Si Actualizar compilación obsoleta está activado y la compilación supera tu Umbral de obsolescencia, los agentes de programación obtienen al iniciar el código más reciente de la rama predeterminada.
¿Los Builds sustituyen las instantáneas o los Dockerfiles?
No. Una instantánea guardada o un Dockerfile define la máquina base con la que se crea un Build. Cursor clona después los repositorios, ejecuta install y crea una nueva instantánea arrancable.
¿Las Builds admiten varios repositorios?
Sí. Una Build prepara todos los repositorios del entorno y registra el commit utilizado en cada uno.
¿Las compilaciones tienen un coste adicional?
No. Las compilaciones están incluidas con los agentes en la nube.