Cursor Cloud Agent Environment: как настроить

Cursor Cloud Agent Environment — это изолированная Ubuntu-машина (или сохранённый Build этой машины), в которой Cloud Agent получает репозитории, зависимости, секреты, startup-команды и сетевой доступ как у разработчика. Канон: Cloud Environment Setup. Обзор ранов — в Background / Cloud Agents; здесь фокус только на среде.

Соседи: Cursor Docs, Hooks, Privacy Mode, Self-Hosted Machines. Pillar: n8n / автоматизация.

Зачем environment, если агент уже «умный»

По доке: агент, который пишет код, но не может прогнать тесты, дернуть API или поднять сервис, не закрывает цикл. Environment + Build готовят машину заранее, чтобы ран стартовал с готовыми зависимостями, а не с нуля каждый раз.

Способ	Когда брать	Что правите	Риск
Agent-driven setup	Старт команды / новый репо	Dashboard Environments + секреты	Конфиг не в git, пока не закоммитите
.cursor/environment.json + Dockerfile	Нужны системные пакеты / особый OS image	Dockerfile, install, start, terminals	Сломанный Build блокирует раны
Multi-repo environment	Frontend + backend + infra в разных репо	Набор репозиториев в dashboard	Секреты среды доступны всем репо группы

Сверка: cursor.com/docs/cloud-agent/setup (проверка 2026-09-17). Цены моделей и лимиты VM — в кабинете; hard ₽ не публикуем.

Порядок резолва среды

1. .cursor/environment.json в репозитории (или группе репо).
2. Personal saved environment.
3. Team saved environment.

Так команда держит дефолт на team-уровне, а человек может временно переопределить personal-средой до выката в репо.

Минимальный environment.json

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

Дока: не COPY весь проект в Dockerfile — Cursor сам чекаутит нужный commit. Dockerfile нужен для системных зависимостей, компиляторов, отладчиков, смены base image. Layer caching: меняете слой — пересобираются затронутые слои.

Install vs start vs terminals

• install (раньше update script) — повторяемая подготовка: install deps, codegen, сборка артефактов на диск. Попадает в Build.
• start — процессы после boot из Build (часто sudo service docker start).
• terminals — app-процессы в shared tmux (вы и агент видите один сеанс).

Долгоживущие сервисы не кладите в install: они должны жить в start/terminals или описываться в секции Cloud-specific внутри AGENTS.md.

Секреты: три типа

Тип	Видит агент	Типичный кейс
Environment Variable	Да (как env)	Флаги, публичные URL
Runtime Secret	Значение маскируется в tool/chat/commits как [REDACTED]	API keys, пароли
Build Secret	Только Docker build	Private registry на этапе образа

Канон секретов: Secrets & Network. Рекомендация доки: Secrets tab в dashboard, а не надежда на локальный .env.local в snapshot. Environment-scoped secrets ограничены одной средой (удобно для staging / multi-repo групп).

Маршрут на один вечер

1. Админ подключает SCM; вы открываете Cloud Agents → Environments.
2. Agent-driven setup: секреты → установка deps → успешный Build.
3. Закоммитьте рабочий .cursor/environment.json (и Dockerfile при необходимости).
4. Добавьте секцию Cursor Cloud specific instructions в AGENTS.md.
5. Стартуйте узкий Cloud Agent и проверьте, что тесты реально бегут.

Типичные ошибки

• Считать overview Cloud Agents достаточным без setup — раны без Build «пишут вслепую».
• Класть docker/db в install вместо start.
• Ждать user-level hooks из ~/.cursor на облачной VM.
• Смешивать Runtime Secret и Build Secret: registry-креды build-time не должны жить в runtime chat.
• Фиксировать ₽ из блогов вместо spend limit в кабинете.

FAQ: Cursor Cloud Agent Environment

Вывод

Cloud Agent Environment — рычаг качества ранов: репозитории + install/Build + секреты + start. Сначала agent-driven setup и один зелёный Build, потом версионируйте environment.json. Обзор агентов — Background Agents; если tool calls должны идти на ваших машинах — Self-Hosted.