[Go to site: main page, start]
Skip to main content

Command Palette

Search for a command to run...

Agentes en la nube

Cloud Environment Setup

Los agentes en la nube se ejecutan en máquinas Ubuntu aisladas. Configure el entorno para que el agente tenga los mismos repositorios, herramientas, dependencias, secretos y acceso de red que usaría un desarrollador.

Cree un entorno nuevo en el panel de control de agentes en la nube.

¿Qué es un entorno de agente en la nube?

El entorno de desarrollo de un agente en la nube es similar a la configuración de tu portátil: repositorios clonados, dependencias instaladas, secretos, comandos de inicio y acceso de red.

Los entornos de desarrollo efectivos brindan a los agentes de programación todo el contexto sobre tu base de código y tu organización, para que puedan probar y verificar su trabajo.

¿Por qué es importante la configuración del entorno?

Los agentes de programación solo son tan capaces como los entornos en los que se ejecutan. Un agente que puede escribir código pero no ejecutar pruebas, consultar servicios ni acceder a APIs no puede completar su trabajo de principio a fin.

Para llevar las tareas de ingeniería de principio a fin, los agentes en la nube necesitan un entorno de desarrollo configurado, con todos los repositorios, herramientas, dependencias y el contexto necesarios para mantenerse autónomos y productivos.

Los entornos de desarrollo también agilizan las sesiones del agente. Las compilaciones preparan repositorios, herramientas y dependencias en segundo plano para que los agentes comiencen desde una máquina lista para usar.

La configuración del entorno es el paso más importante para mejorar la eficacia de tus agentes en la nube.

Opciones de configuración del entorno

Hay dos formas principales de configurar el entorno de tu agente en la nube:

  1. Deja que el agente de Cursor configure su propio entorno desde el Panel de control de agentes en la nube. El agente instala dependencias, verifica el entorno y crea su primera creación.
  2. Configura manualmente el entorno con un Dockerfile. Si eliges esta opción, puedes especificar el Dockerfile en un archivo .cursor/environment.json.

Ambas opciones te permiten especificar un script de instalación. Cursor lo ejecuta mientras crea una creación para que las dependencias estén listas antes de que se inicie un agente.

Entornos multirrepo

Usa un entorno multirrepo cuando un agente necesita trabajar en más de un repositorio. Selecciona varios repositorios al crear un entorno. Cursor clona cada repositorio seleccionado en la máquina del agente y reutiliza el entorno en futuras ejecuciones del agente y automatizaciones que usan el mismo grupo de repositorios.

Usa entornos multirrepo cuando el frontend, backend, la infraestructura o las bibliotecas compartidas están en repositorios separados. El agente puede inspeccionar todo el espacio de trabajo, hacer cambios coordinados, ejecutar tests en varios repositorios y abrir pull request en los repositorios que modifica.

Puedes ver qué entorno está activo, junto con todas las versiones activas anteriores, visitando la página de configuración del entorno en el Panel de control de agentes en la nube.

Orden de resolución del entorno

Cursor resuelve la configuración del entorno por repositorio o grupo de repositorios usando la primera coincidencia:

  1. .cursor/environment.json en el repositorio
  2. Un entorno personal guardado
  3. Un entorno de equipo guardado

Esto ofrece valores predeterminados predecibles a nivel de equipo y, al mismo tiempo, permite que los usuarios individuales los sobrescriban con un entorno personal cuando no existe un .cursor/environment.json en el repositorio. Las sobrescrituras de usuario también son útiles para probar una nueva configuración de entorno antes de implementarla en todo el equipo.

Configuración asistida por agente de programación (recomendada)

Cursor puede configurar tu entorno de desarrollo en la nube en menos de 10 minutos. Inicia la configuración guiada desde el panel de control de agentes en la nube o desde la ventana de agente de programación en la app de escritorio de Cursor.

Se te pedirá que conectes tu cuenta de GitHub, GitLab, Azure DevOps o Bitbucket y selecciones uno o más repositorios.

Después, proporciona a Cursor las variables de entorno y los secretos que necesitará para instalar dependencias y ejecutar el código.

Mientras el agente de programación trabaja, puedes seguir su progreso en una sesión de terminal compartida mientras se encarga de tareas de configuración, como instalar dependencias. Cursor guarda el entorno después de verificar el código y completar correctamente una creación.

Los futuros agentes en la nube se inician desde la creación activa y pueden probar cambios ejecutando tu software. Haz commit de la configuración en .cursor/environment.json para que todo tu equipo se beneficie.

Configuración manual con Dockerfile (avanzado)

Para casos avanzados, configura el entorno con un Dockerfile:

  • Crea un Dockerfile para instalar dependencias del sistema, usar versiones específicas del compilador, instalar depuradores o cambiar la imagen base del sistema operativo
  • No hagas COPY de todo el proyecto; Cursor gestiona el espacio de trabajo y extrae el commit correcto
  • Edita .cursor/environment.json directamente para configurar los ajustes de ejecución
  • Usa secretos de compilación para registros privados de paquetes o credenciales de compilación

Aquí tienes un ejemplo de .cursor/environment.json que hace referencia a un .cursor/Dockerfile (ruta relativa) y a un script de instalación custom_script.sh:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

Si tu repositorio necesita Docker, Tailscale o Cloudflare Tunnel, consulta Ejecutar Docker, Ejecutar Tailscale y Ejecutar Cloudflare Tunnel a continuación.

El entorno se configura con un Dockerfile; no tienes acceso directo a la máquina remota.

Las compilaciones con Dockerfile usan caché de capas. Cuando cambias un Dockerfile, Cursor recompila las capas modificadas en lugar de recompilar todas las capas desde cero.

Dockerfiles configurados por Cursor (beta privada)

Para los equipos que no quieran escribir un Dockerfile desde cero, Cursor puede configurarlo. Durante la configuración, Cursor inspecciona tus repositorios, identifica herramientas y dependencias, y genera una configuración de entorno basada en Dockerfile que puedes editar y versionar.

Este flujo está en beta privada para equipos Enterprise. Para solicitar acceso, ponte en contacto con tu representante de cuenta de Cursor o envía un correo a hi@cursor.com desde tu cuenta de administrador de equipo.

Límites de recursos

Cada Cloud Agent se ejecuta en un perfil de VM predeterminado con memoria y CPU limitadas. Si tienes un plan Enterprise y tu repositorio necesita más recursos, ponte en contacto con soporte y podremos aumentar los límites de tu workspace.

La configuración autoservicio de recursos personalizados estará disponible pronto.

Script de instalación

El script de instalación antes se llamaba script de actualización en el Panel de control y la documentación.

Cursor ejecuta el script de instalación (install en environment.json) al crear una creación. El script se ejecuta en segundo plano, sin retrasar el inicio de cada agente.

Usa install para las tareas que Cursor pueda preparar de antemano. Por ejemplo, instalar dependencias, generar código, compilar artefactos y precalentar cachés de disco.

Cómo las creaciones usan el script de instalación

Cursor parte de la imagen base del entorno, clona sus repositorios y ejecuta install hasta que finaliza. Una creación correcta guarda el estado resultante del disco y pasa a estar activa. Los nuevos agentes de programación parten de la creación activa.

Asegúrate de que el script se complete. La configuración costosa debe incluirse en install, ya que se ejecuta antes de una solicitud a un agente de programación, en lugar de durante el inicio. Comandos como pnpm install pueden reutilizar el estado preparado y actualizar solo las dependencias modificadas.

Las creaciones solo conservan el estado del disco. Los procesos en ejecución, las variables de shell exportadas y las cachés en memoria no se mantienen al ejecutar un agente de programación. Inicia los servicios con start o terminals.

Recuperación de la configuración del entorno

Una creación fallida no reemplaza la creación activa. Los agentes de programación siguen iniciándose desde el entorno de la creación correcta más reciente mientras inspeccionas el error y creas una sustituta.

Abre la pestaña Creaciones del entorno para inspeccionar los registros, iniciar un agente de programación desde la creación fallida o seleccionar otra creación correcta. Consulta Creaciones de Cloud Agent para conocer los controles de creación y las opciones de depuración.

Cómo decidir qué incluir en el script de instalación

Incluye en install todos los pasos de preparación repetibles. Incluye la instalación completa de dependencias, la generación de código, la compilación de artefactos y cualquier otra tarea que genere resultados reutilizables en disco.

Mantén los procesos de larga duración fuera de install. Configura Docker, las bases de datos, los túneles y los servidores de desarrollo en los comandos de inicio. También puedes añadir instrucciones en AGENTS.md para servicios que un agente solo necesite para tareas específicas.

Comandos de inicio

Después de que un agente se inicia desde una creación, Cursor ejecuta el comando start y luego cualquier terminals configurados. Úsalos para procesos que deben mantenerse activos mientras se ejecuta el agente.

Puedes omitir start en muchos repositorios. Si tu entorno depende de Docker, agrega sudo service docker start en start.

terminals son para procesos de la aplicación. Se ejecutan en una sesión de tmux compartida entre tú y el agente.

Añadir instrucciones específicas de la nube a AGENTS.md

Los agentes en la nube leen archivos AGENTS.md. Recomendamos añadir una sección dedicada para las instrucciones de configuración y pruebas exclusivas de Cloud, con un título como Cursor Cloud specific instructions.

Si esta sección se vuelve muy extensa, recomendamos incluir referencias a otros archivos que puedan contener instrucciones detalladas para tareas específicas.

Consulta nuestra documentación de AGENTS.md para obtener más información.

Variables de entorno y secretos

Para poder ejecutar y probar código igual que lo haría un desarrollador humano, los agentes en la nube suelen necesitar variables de entorno y secretos, como claves de API y credenciales de base de datos.

Recomendado: usa la pestaña Secrets en los ajustes de Cursor

La forma más fácil de gestionar secretos es a través de cursor.com. Estos se ponen a disposición del agente en la nube como variables de entorno.

Para obtener más información sobre los distintos tipos de secretos, consulta nuestra documentación sobre Secrets. Para conceder acceso al rol en la nube sin claves de larga duración, consulta los tokens OIDC.

Secretos con alcance de entorno

Usa secretos con alcance de entorno cuando una credencial solo deba estar disponible para agentes de programación que usan un entorno. Esto resulta útil para entornos multirrepositorio, credenciales de staging o grupos de repositorios con distintas necesidades de acceso.

Los secretos con alcance de entorno se aplican a todos los repositorios de ese entorno. No están disponibles en otros entornos.

Credenciales de inicio de sesión y 2FA

Si tu aplicación requiere iniciar sesión, añade como secretos las mismas credenciales que usas localmente, como nombre de usuario, correo electrónico y contraseña.

Si tu flujo de inicio de sesión usa 2FA basada en TOTP, añade también como secreto el secreto de TOTP, a veces llamado secreto compartido o secreto raíz. El agente puede generar el código actual de 6 dígitos con oathtool --totp -b "$TOTP_SECRET".

Monorepos con varios archivos .env

Si tu monorepo tiene varios archivos .env.local:

  • Añade los valores de todos los archivos .env.local a la misma pestaña Secrets
  • Usa nombres de variable únicos cuando las claves se superpongan, como NEXTJS_* y CONVEX_*
  • Haz referencia a esas variables desde cada app según sea necesario

Si incluyes archivos .env.local al tomar una instantánea, pueden guardarse y quedar disponibles para los agentes en la nube. La pestaña Secrets sigue siendo la opción recomendada por motivos de seguridad y gestión.

Uso de roles de IAM de AWS

Cursor permite asumir roles de IAM de AWS proporcionados por el cliente para lograr una integración más profunda con AWS. Esto te permite otorgar permisos específicos de AWS a los agentes en la nube sin compartir credenciales de larga duración.

  1. Crea el rol de IAM: En tu cuenta de AWS, crea el rol de IAM que quieres que asuma el agente en la nube y anota su ARN (p. ej., arn:aws:iam::123456789012:role/acmeRole).

  2. Configura el secreto del rol de IAM: Ve a Panel de control de Cursor → agentes en la nube y añade un secreto de usuario o de equipo llamado CURSOR_AWS_ASSUME_IAM_ROLE_ARN, configurado con el ARN del rol de IAM que creaste.

  3. Genera un ID externo: Un administrador de equipo debe hacerlo desde la sección Advanced de los ajustes del equipo. Ve a Panel de control de Cursor → Ajustes → Advanced y busca la configuración del ID externo. Si no ves ningún ID externo, introduce un valor provisional en el campo "AWS IAM Role ARN", haz clic en "Validate & Save" y recarga la página. Esto generará un ID externo para tu equipo (p. ej., cursor-xxx-yyy-zzz).

  4. Configura la política de confianza del rol de IAM: En tu cuenta de AWS, actualiza la política de confianza del rol de IAM para que confíe en el sistema de asunción de roles de Cursor. La política de confianza debería verse así:

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "AllowCursorAssume",      "Effect": "Allow",      "Principal": {        "AWS": "arn:aws:iam::289469326074:role/roleAssumer"      },      "Action": "sts:AssumeRole",      "Condition": {        "StringEquals": {          "sts:ExternalId": "cursor-xxx-yyy-zzz"        }      }    }  ]}

Reemplaza cursor-xxx-yyy-zzz por el ID externo generado para tu equipo.

Variables de entorno:

Una vez configurado, Cursor establece estas variables de entorno para que las herramientas de AWS usen el perfil cursor-cloud-agent:

  • AWS_CONFIG_FILE apunta a un archivo de configuración de AWS gestionado por Cursor
  • AWS_PROFILE se establece en cursor-cloud-agent
  • AWS_SDK_LOAD_CONFIG se establece en 1

La CLI de AWS y los SDK de AWS que usan la cadena de credenciales predeterminada detectan este perfil automáticamente durante los comandos de configuración y mientras el agente está en ejecución. No necesitas exportar AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY ni AWS_SESSION_TOKEN manualmente.

Para federarte con AWS STS AssumeRoleWithWebIdentity, o con GCP, Azure u otro verificador de OIDC, emite tokens OIDC desde la VM del agente en lugar de almacenar claves de nube de larga duración.

Configuración en código con environment.json

Si prefieres mantener la configuración de tu entorno definida en código, puedes hacer commit de .cursor/environment.json en tu repositorio.

Las creaciones usan la configuración de la rama predeterminada del entorno. Para los cambios en ramas de funcionalidades, haz commit y push de la configuración y luego inicia un agente en la rama. Cursor hace checkout de la rama solicitada sobre la creación activa, y el agente puede volver a ejecutar el comando de instalación cuando la rama modifica las dependencias.

Ejemplo de environment.json con una configuración basada en instantáneas (puedes acceder al ID de la instantánea desde la página de entornos del panel de control):

{  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",  "install": "npm install"}

Aquí tienes un ejemplo de .cursor/environment.json que hace referencia a .cursor/Dockerfile (ruta relativa) y a un script de instalación custom_script.sh:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

El esquema completo está definido aquí.

Ejecutar Docker

Los agentes en la nube admiten flujos de trabajo con Docker. Usamos esto internamente para repositorios full-stack que ejecutan muchos servicios.

Para configuraciones simples, suele bastar con instalar Docker. Comandos como docker run hello-world suelen funcionar una vez que Docker está instalado y el daemon está en ejecución.

Docker se ejecuta dentro de otra capa de contenedor, por lo que las configuraciones complejas pueden requerir configuración adicional. Los flujos de trabajo simples suelen funcionar. Las configuraciones más complejas deberían partir de la configuración de fuse-overlayfs e iptables-legacy que aparece a continuación.

Para configuraciones de Docker más complejas, usa fuse-overlayfs, iptables-legacy y asegúrate de que el usuario de tu agente en la nube pueda ejecutar Docker.

######################################################### DOCKER INSTALLATION######################################################### Instalar DockerRUN install -m 0755 -d /etc/apt/keyrings && \    curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \    chmod a+r /etc/apt/keyrings/docker.gpg && \    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \    apt-get update && \    apt-get install -y \    docker-ce=5:28.5.2-1~ubuntu.24.04~noble \    docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble \    containerd.io \    docker-buildx-plugin \    docker-compose-plugin \    && rm -rf /var/lib/apt/lists/*RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/*RUN mkdir -p /etc/docker && \    printf '%s\n' '{' \    '  "storage-driver": "fuse-overlayfs"' \    '}' > /etc/docker/daemon.jsonRUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/*RUN update-alternatives --set iptables /usr/sbin/iptables-legacy && \    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy######################################################### CONFIG UBUNTU USER######################################################### asegurarse de que no haya autenticación por contraseñaRUN echo 'PasswordAuthentication no\nChallengeResponseAuthentication no\nUsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf# Crear usuario sin privilegios de root (solo si no existe)RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu# Crear el grupo docker si no existe y añadir el usuario ubuntu a élRUN groupadd -f docker && usermod -aG docker ubuntuRUN usermod -aG sudo ubuntu# Configurar sudo sin contraseña para el usuario ubuntuRUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu# Establecer una contraseña para el usuario ubuntuRUN echo "ubuntu:ubuntu" | chpasswd

Ejecutar Tailscale

Tailscale no funciona en su modo de red predeterminado en las VM de agentes en la nube. Usa en su lugar el modo de red en espacio de usuario.

Esto permite que el agente acceda a servicios privados y almacenes de datos a través de tu tailnet sin exponer esos servicios a la Internet pública.

Inicia tailscaled con:

tailscaled --tun=userspace-networking \  --outbound-http-proxy-listen=localhost:1054 \  --socks5-server=localhost:1055

A continuación, exporta estas variables de proxy en el shell donde quieras que el tráfico pase por Tailscale:

export ALL_PROXY=socks5h://localhost:1055/export HTTP_PROXY=http://localhost:1054/export HTTPS_PROXY=http://localhost:1054/

Después de eso, ejecuta tu proceso habitual de tailscale up ....

Si quieres una referencia que funcione, algunos clientes han usado tailscale-orb con éxito porque su modo Docker sigue este patrón.

Ejecutar Cloudflare Tunnel

Cloudflare Tunnel funciona en las VM de agente en la nube porque cloudflared se ejecuta en espacio de usuario.

Usa este patrón cuando un agente en la nube necesita acceder a un servicio HTTP privado en una VPC o intranet:

  • Instala cloudflared en el Dockerfile de tu entorno o en el script de instalación.
  • Ejecuta un conector de cloudflared dentro de tu red privada.
  • Enruta un nombre de host autenticado, como vpc.example.com, a través del túnel hasta el origen privado.
  • Añade ese nombre de host a la lista de permitidos de red de agente en la nube si tu entorno usa salida restringida.
  • Almacena los valores del token de servicio de Cloudflare Access en Cursor Secrets. Por ejemplo, usa CF_ACCESS_CLIENT_ID y CF_ACCESS_CLIENT_SECRET.

El agente en la nube puede entonces acceder al servicio privado a través de HTTPS normal con las cabeceras CF-Access-Client-Id y CF-Access-Client-Secret. El conector establece la conexión de salida con Cloudflare y reenvía la solicitud a tu origen privado. Tus servicios y almacenes de datos permanecen en tu red privada, y el conector no necesita puertos de entrada abiertos.

Para servicios TCP privados, como bases de datos, configura una aplicación de Cloudflare TCP Access y ejecuta cloudflared access tcp en tu comando de inicio. Haz que tu aplicación o comando de prueba apunte al listener local que crea cloudflared.