Настройка облачной инфраструктуры

Облачные агенты работают на изолированных машинах Ubuntu. Настройте инфраструктуру так, чтобы у агента были те же репозитории, инструменты, зависимости, секреты и сетевой доступ, что и у разработчика.

Создайте новую инфраструктуру в своем дашборде Cloud Agents.

Что такое инфраструктура облачного агента?

Инфраструктура разработки для облачного агента похожа на настройку на вашем ноутбуке: клонированные репозитории, установленные зависимости, секреты, команды запуска и сетевой доступ.

Эффективная инфраструктура разработки дает агентам полный контекст о вашей кодовой базе и организации, чтобы они могли тестировать и проверять свою работу.

Почему важна конфигурация инфраструктуры?

Возможности агентов напрямую зависят от инфраструктуры, в которой они работают. Агент, который умеет писать код, но не может запускать тесты, обращаться к сервисам или вызывать API, не способен довести свою работу до конца.

Чтобы выполнять инженерные задачи от начала до конца, облачным агентам нужна настроенная инфраструктура разработки со всеми репозиториями, инструментами, зависимостями и контекстом, необходимыми для автономной и продуктивной работы.

Инфраструктура разработки также ускоряет сессии агентов. Сборки подготавливают репозитории, инструменты и зависимости в фоновом режиме, чтобы агенты начинали работу на готовой к использованию машине.

Настройка инфраструктуры — самый важный шаг к повышению эффективности ваших облачных агентов.

Варианты настройки инфраструктуры

Есть два основных способа настроить инфраструктуру для вашего облачного агента:

1. Позвольте агенту Cursor самостоятельно настроить свою инфраструктуру через дашборд Cloud Agents. Агент устанавливает зависимости, проверяет инфраструктуру и создаёт свою первую сборку.
2. Настройте инфраструктуру вручную с помощью Dockerfile. Если вы выберете этот вариант, то сможете указать Dockerfile в файле .cursor/environment.json.

Оба варианта позволяют указать скрипт установки. Cursor запускает его при создании сборки, чтобы зависимости были готовы до запуска агента.

Инфраструктуры с несколькими репозиториями

Используйте инфраструктуру для нескольких репозиториев, когда Agent должен работать более чем с одним репозиторием. Выберите несколько репозиториев при создании инфраструктуры. Cursor клонирует каждый выбранный репозиторий на машину Agent и затем повторно использует эту инфраструктуру для будущих запусков Agent и автоматизаций, использующих ту же группу репозиториев.

Инфраструктуры с несколькими репозиториями полезны, когда frontend, backend, инфраструктура или общие библиотеки находятся в отдельных репозиториях. Agent может анализировать всё рабочее пространство, вносить согласованные изменения, запускать тесты в разных репозиториях и открывать pull request в тех репозиториях, которые он изменил.

Вы можете посмотреть, какая инфраструктура активна, а также все предыдущие активные версии, на странице конфигурации инфраструктуры в Cloud Agents dashboard.

Порядок выбора инфраструктуры

Cursor определяет конфигурацию инфраструктуры для репозитория или группы репозиториев по первому совпадению:

1. .cursor/environment.json в репозитории
2. Личная сохранённая инфраструктура
3. Сохранённая инфраструктура команды

Это обеспечивает предсказуемые настройки по умолчанию на уровне команды и при этом позволяет отдельным пользователям переопределять их с помощью личной инфраструктуры, если .cursor/environment.json на уровне репозитория отсутствует. Пользовательские переопределения также удобны для тестирования новой конфигурации инфраструктуры перед её развертыванием на всю команду.

Настройка с помощью Agent (рекомендуется)

Cursor может настроить вашу инфраструктуру разработки в облаке менее чем за 10 минут. Запустите пошаговую настройку из дашборда Cloud Agents или из Окна Agents в десктопном приложении Cursor.

Вам будет предложено подключить аккаунт GitHub, GitLab, Azure DevOps или Bitbucket и выбрать один или несколько репозиториев.

Затем вы предоставите Cursor переменные среды и секреты, которые понадобятся для установки зависимостей и запуска кода.

Пока Agent работает, вы можете следить за его прогрессом в общей сессии терминала, пока он выполняет задачи настройки, например устанавливает зависимости. Cursor сохраняет инфраструктуру после проверки кода и успешного завершения сборки.

Будущие Cloud Agents начинают работу с активной сборки и могут тестировать изменения, запуская ваше ПО. Зафиксируйте конфигурацию в .cursor/environment.json, чтобы от этого выиграла вся ваша команда.

Ручная настройка с Dockerfile (для продвинутых случаев)

Для более сложных сценариев настройте инфраструктуру с помощью Dockerfile:

• Создайте Dockerfile, чтобы установить системные зависимости, использовать определённые версии компиляторов, установить отладчики или сменить базовый образ ОС
• Не выполняйте COPY всего проекта; Cursor управляет рабочей областью и извлекает нужный коммит
• Измените .cursor/environment.json напрямую, чтобы настроить параметры выполнения
• Используйте секреты сборки для приватных реестров пакетов или учётных данных для сборки

Вот пример .cursor/environment.json, который ссылается на .cursor/Dockerfile (относительный путь) и установочный скрипт custom_script.sh:

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

Если вашему репозиторию нужен Docker, Tailscale или Cloudflare Tunnel, см. разделы Запуск Docker, Запуск Tailscale и Запуск Cloudflare Tunnel ниже.

Инфраструктура настраивается с помощью Dockerfile; прямого доступа к удалённой машине у вас нет.

При сборке Dockerfile используется кэширование слоёв. Когда вы вносите изменения в Dockerfile, Cursor пересобирает только изменённые слои, а не все слои с нуля.

Dockerfile, настроенные Cursor (приватная бета-версия)

Для команд, которые не хотят писать Dockerfile с нуля, Cursor может настроить его за вас. Во время настройки Cursor анализирует ваши репозитории, определяет инструменты и зависимости и создаёт конфигурацию инфраструктуры на основе Dockerfile, которую вы можете редактировать и версионировать.

Этот сценарий доступен в приватной бета-версии для Enterprise teams. Чтобы запросить доступ, свяжитесь с представителем вашего аккаунта Cursor или напишите на hi@cursor.com из аккаунта администратора вашей команды.

Ограничения по ресурсам

Каждый Cloud Agent запускается на профиле виртуальной машины по умолчанию с ограниченными ресурсами памяти и CPU. Если у вас тариф Enterprise и вашему репозиторию требуется больше ресурсов, свяжитесь со службой поддержки — мы сможем увеличить лимиты для вашего рабочего пространства.

Возможность самостоятельно настраивать ресурсы появится в ближайшее время.

Скрипт установки

Раньше в дашборде и документации скрипт установки назывался скриптом обновления.

Cursor запускает скрипт установки (install в environment.json) при создании сборки. Скрипт выполняется в фоновом режиме и не задерживает запуск каждого Agent.

Используйте install для задач, которые Cursor может выполнить заранее: установки зависимостей, генерации кода, компиляции артефактов и прогрева дискового кэша.

Как сборки используют скрипт установки

Cursor начинает с базового образа среды, клонирует репозитории и выполняет install до завершения. Успешная сборка сохраняет итоговое состояние диска и становится активной. Новые агенты запускаются из активной сборки.

Скрипт должен выполняться до конца. Ресурсоёмкую настройку следует выполнять в install, поскольку он запускается до запроса агента, а не при запуске. Команды вроде pnpm install всё равно могут использовать подготовленное состояние и обновлять только изменившиеся зависимости.

Сборки сохраняют только состояние диска. Запущенные процессы, экспортированные переменные оболочки и кэши в памяти не переносятся в запуск агента. Запускайте сервисы с помощью start или terminals.

Восстановление конфигурации инфраструктуры

Неудачная сборка не заменяет активную. Агенты продолжают запускаться в последней успешно подготовленной инфраструктуре, пока вы анализируете сбой и создаёте новую сборку.

Откройте вкладку Сборки инфраструктуры, чтобы просмотреть журналы, запустить агента из неудачной сборки или выбрать другую успешную сборку. Подробнее об управлении сборками и их отладке см. в разделе Сборки Cloud Agent.

Что включить в скрипт установки

Добавьте в install все повторяемые шаги подготовки. Это включает полную установку зависимостей, генерацию кода, сборку артефактов и другие операции, сохраняющие на диске повторно используемые результаты.

Не добавляйте длительные процессы в install. Docker, базы данных, туннели и серверы разработки указывайте в командах запуска. Для сервисов, которые агенту нужны только для определённых задач, также можно добавить инструкции в AGENTS.md.

Команды запуска

После загрузки агента из Build Cursor выполняет команду start, а затем все настроенные terminals. Используйте их для процессов, которые должны оставаться активными, пока работает агент.

Во многих репозиториях start можно пропустить. Если ваша среда зависит от Docker, добавьте sudo service docker start в start.

terminals предназначены для процессов кода приложения. Они запускаются в tmux‑сессии, общей для вас и агента.

Добавьте инструкции для облака в AGENTS.md

Облачные агенты читают файлы AGENTS.md. Мы рекомендуем добавить отдельный раздел с инструкциями по настройке и тестированию, относящимися только к Cloud, с заголовком вроде Cursor Cloud specific instructions.

Если этот раздел становится слишком большим, мы рекомендуем добавить ссылки на другие файлы с подробностями для отдельных задач.

Подробнее см. в нашей документации по AGENTS.md.

Переменные среды и секреты

Чтобы облачные агенты могли полноценно запускать и тестировать код, как это делает разработчик, им часто нужны переменные среды и секреты, например API-ключи и учетные данные для доступа к базе данных.

Рекомендуется: используйте вкладку Secrets в настройках Cursor

Проще всего управлять секретами через cursor.com. Они доступны облачному агенту в виде переменных среды.

Подробнее о разных типах секретов см. в нашей документации по секретам. Чтобы предоставить доступ к облачной роли без долгосрочных ключей, см. токены OIDC.

Секреты с областью действия на уровне инфраструктуры

Используйте секреты с областью действия на уровне инфраструктуры, если учетные данные должны быть доступны только агентам, использующим одну инфраструктуру. Это полезно для инфраструктур с несколькими репозиториями, учетных данных для стейджинга или групп репозиториев с разными требованиями к доступу.

Секреты с областью действия на уровне инфраструктуры применяются ко всем репозиториям в этой инфраструктуре. В других инфраструктурах они недоступны.

Учетные данные для входа и 2FA

Если для вашего приложения требуется вход, добавьте в список секретов те же учетные данные, которые вы используете локально, как секреты, например имя пользователя, адрес электронной почты и пароль.

Для 2FA на основе TOTP также добавьте TOTP-секрет, иногда называемый общим или корневым секретом, в список секретов. Агент может сгенерировать текущий 6-значный код с помощью oathtool --totp -b "$TOTP_SECRET".

Монорепозитории с несколькими файлами .env

Если в вашем монорепозитории несколько файлов .env.local:

• Добавьте значения из всех файлов .env.local в одну и ту же вкладку Secrets
• Используйте уникальные имена переменных, если ключи совпадают, например NEXTJS_* и CONVEX_*
• При необходимости обращайтесь к этим переменным из каждого приложения

Если включить файлы .env.local при создании snapshot, они могут быть сохранены и стать доступными облачным агентам. Вкладка Secrets остаётся предпочтительным вариантом с точки зрения безопасности и удобства управления.

Использование ролей AWS IAM

Cursor поддерживает использование предоставленных клиентом ролей AWS IAM для более глубокой интеграции с AWS. Это позволяет выдавать облачным агентам определенные права доступа AWS, не передавая долговременные учетные данные.

1. Создайте роль IAM: В вашем аккаунте AWS создайте роль IAM, которую должен использовать облачный агент, и сохраните ее ARN (например, arn:aws:iam::123456789012:role/acmeRole).

2. Настройте секрет роли IAM: Перейдите в Cursor Dashboard → Cloud Agents и добавьте пользовательский секрет или секрет команды с именем CURSOR_AWS_ASSUME_IAM_ROLE_ARN, указав в нем ARN созданной вами роли IAM.

3. Сгенерируйте внешний идентификатор: Это должен сделать администратор команды в разделе Advanced настроек команды. Перейдите в Cursor Dashboard → Settings → Advanced и найдите настройки внешнего идентификатора. Если внешний идентификатор не отображается, введите временное значение в поле "AWS IAM Role ARN", нажмите "Validate & Save" и перезагрузите страницу. Это сгенерирует внешний идентификатор для вашей команды (например, cursor-xxx-yyy-zzz).

4. Настройте политику доверия роли IAM: В вашем аккаунте AWS обновите политику доверия роли IAM, чтобы она доверяла механизму принятия ролей Cursor. Политика доверия должна выглядеть так:

{  "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"        }      }    }  ]}

Замените cursor-xxx-yyy-zzz на внешний идентификатор, сгенерированный для вашей команды.

Переменные среды:

После настройки Cursor задаёт эти переменные среды, чтобы инструменты AWS использовали профиль cursor-cloud-agent:

• AWS_CONFIG_FILE указывает на файл конфигурации AWS, которым управляет Cursor
• AWS_PROFILE имеет значение cursor-cloud-agent
• AWS_SDK_LOAD_CONFIG имеет значение 1

AWS CLI и AWS SDK, использующие цепочку учетных данных по умолчанию, автоматически подхватывают этот профиль во время команд настройки и пока агент запущен. Вам не нужно самостоятельно экспортировать AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY или AWS_SESSION_TOKEN.

Для федерации через AWS STS AssumeRoleWithWebIdentity, GCP, Azure или другой OIDC-проверяющий сервис выпускайте токены OIDC из VM агента вместо хранения долговременных облачных ключей.

Конфигурация в коде с environment.json

Если вы предпочитаете хранить конфигурацию инфраструктуры в коде, вы можете закоммитить .cursor/environment.json в свой репозиторий.

Сборки используют конфигурацию из ветки инфраструктуры по умолчанию. Для изменений в функциональной ветке закоммитьте и отправьте конфигурацию, затем запустите агента в этой ветке. Cursor переключается на запрошенную ветку поверх активной сборки, и агент может повторно выполнить команду установки, если ветка изменяет зависимости.

Пример environment.json с конфигурацией на основе снимка (ID снимка доступен на странице инфраструктур в дашборде):

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

Вот пример .cursor/environment.json со ссылкой на .cursor/Dockerfile (относительный путь) и скрипт установки custom_script.sh:

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

Полная схема описана здесь.

Запуск Docker

Облачные агенты поддерживают рабочие процессы Docker. Мы используем это внутри компании для full-stack-репозиториев, в которых запускается много сервисов.

Для простых конфигураций часто достаточно установить Docker. Команды вроде docker run hello-world обычно работают, если Docker установлен и демон запущен.

У Docker в Cloud Agents по-прежнему есть свои нюансы, поскольку здесь он работает внутри другого контейнерного слоя. Простые рабочие процессы обычно работают. Для более сложных конфигураций стоит начать с конфигурации fuse-overlayfs и iptables-legacy ниже.

Для более сложных конфигураций Docker используйте fuse-overlayfs, iptables-legacy и убедитесь, что пользователь вашего облачного агента может запускать Docker.

######################################################### DOCKER INSTALLATION######################################################### Install 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######################################################### ensure no password authenticationRUN echo 'PasswordAuthentication no\nChallengeResponseAuthentication no\nUsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf# Create non-root user (only if it doesn't exist)RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu# Create docker group if it doesn't exist and add ubuntu user to itRUN groupadd -f docker && usermod -aG docker ubuntuRUN usermod -aG sudo ubuntu# Configure passwordless sudo for ubuntu userRUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu# Set a password for ubuntu userRUN echo "ubuntu:ubuntu" | chpasswd

Запуск Tailscale

Tailscale не работает в стандартном сетевом режиме на ВМ облачного агента. Вместо этого используйте пользовательский сетевой режим.

Это позволяет агенту получать доступ к приватным сервисам и хранилищам данных через ваш tailnet, не открывая эти сервисы для публичного интернета.

Запустите tailscaled с помощью:

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

Затем экспортируйте эти proxy-переменные в shell, через который вы хотите направлять трафик через Tailscale:

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

После этого выполните обычную команду tailscale up ....

Если вам нужен рабочий пример, некоторые клиенты успешно использовали tailscale-orb, поскольку его режим Docker работает по этой схеме.

Запуск Cloudflare Tunnel

Cloudflare Tunnel работает в ВМ Cloud Agent, потому что cloudflared запускается в пользовательском пространстве.

Используйте эту схему, когда Cloud Agent должен получить доступ к приватному HTTP-сервису в VPC или внутренней сети:

• Установите cloudflared в Dockerfile вашей инфраструктуры или в скрипт установки.
• Запустите коннектор cloudflared внутри вашей приватной сети.
• Направьте аутентифицированное имя хоста, например vpc.example.com, через туннель к приватному origin-сервису.
• Добавьте это имя хоста в сетевой allowlist Cloud Agent, если в вашей инфраструктуре ограничен исходящий доступ.
• Сохраните значения токенов сервиса Cloudflare Access в Cursor Secrets. Например, используйте CF_ACCESS_CLIENT_ID и CF_ACCESS_CLIENT_SECRET.

После этого Cloud Agent сможет обращаться к приватному сервису по обычному HTTPS с заголовками CF-Access-Client-Id и CF-Access-Client-Secret. Коннектор устанавливает исходящее соединение с Cloudflare и пересылает запрос в ваш приватный origin-сервис. Ваши сервисы и хранилища данных остаются в вашей приватной сети, и коннектору не нужны открытые входящие порты.

Для приватных TCP-сервисов, таких как базы данных, настройте приложение Cloudflare TCP Access и запустите cloudflared access tcp в команде запуска. Направьте приложение или тестовую команду на локальный listener, который создает cloudflared.