Cursor Cloud Agent Builds: как пользоваться

Cursor Cloud Agent Builds — это предварительная сборка среды Cloud Agent: Cursor клонирует репозитории, гоняет install и сохраняет bootable snapshot диска, чтобы новый агент стартовал уже с тёплыми зависимостями. Канон: Cloud Agent Builds. Базовая настройка среды — Environment; disk checkpoint — Snapshots.

Соседи: Secrets, Self-Hosted Workers, Background / Cloud Agents. Pillar: n8n / автоматизация.

Зачем Builds, если есть snapshot

Snapshot/Dockerfile задают базу. Build поверх базы: clone всех репо среды на default branch → install до конца → snapshot с environment version и exact commit SHA → activate. Pre-warmed копии active Build убирают clone+install со стартового пути агента.

Триггер	Когда	Можно skip?
Recurring	По расписанию для каждой среды	Да, если нет новых commits / config / secrets
Configuration change	Сохранили environment или сменили secrets	Нет, всегда бежит
Manual	Кнопка Trigger build	Нет
Agent-requested	Тестовый Build при setup	Нет

Сверка: cursor.com/docs/cloud-agent/builds (проверка 2026-09-18). Builds included with Cloud Agents; hard ₽ не публикуем.

Жизненный цикл одного Build

1. Trigger — один из четырёх типов выше.
2. Prepare — base image → clone репо → install до completion.
3. Snapshot — disk state + version + commit SHA.
4. Activate — успешный Build становится active.
5. Start agents — агенты, automations, code reviews берут active Build.

Упавший Build не заменяет active: агенты продолжают со старого зелёного.

install / start / terminals

Команда	Фаза	Для чего
install	Во время Build	Deps, codegen, compile, warm caches (идемпотентно)
start	Старт агента	Docker, БД, tunnels
terminals	Старт агента	App-процессы в shared tmux

Build хранит только диск. Процессы после snapshot мертвы — не кладите docker compose up в install.

Git state и Update stale builds

• Default branch runs стартуют с commit, записанного в active Build. Если включён Update stale builds и Build старше Staleness threshold (дефолт 24 часа), агент подтягивает свежий default branch при старте. Threshold 0 = всегда pull.
• Feature branch runs — диск Build + checkout выбранной ветки; deps переиспользуются, при смене зависимостей агент может обновить среду.
• Multi-repo — один Build готовит все репо и пишет commit на каждый.

Secrets и Builds

Build видит team и environment secrets (private registry в install). User secrets появляются только при старте агента и не попадают в shared snapshot. Смена secrets → Configuration change Build.

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

1. Доведите environment до первого Success Build (agent-driven или Dockerfile).
2. Проверьте Builds tab: Recurring Skipped/Success — норма для спокойного репо.
3. Сломанный Build: откройте логи → Start agent from failed Build → почините install → test Build.
4. Настройте Update stale builds под частоту merge в default branch.
5. Закоммитьте рабочий .cursor/environment.json; секреты держите в Secrets.

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

• Класть docker/db в install и ждать, что они «оживут» после snapshot.
• Паниковать из-за Recurring Skipped — это здоровый idle.
• Ломать active Build правкой Dockerfile без test Build.
• Ждать user secrets внутри install phase.
• Считать Builds отдельной платной фичей — дока: included with Cloud Agents.

FAQ: Cursor Cloud Agent Builds

Вывод

Builds — pre-warmed путь Cloud Agents: install на диск → active snapshot → быстрый старт. Чините через failed-Build agent, не через «надежду на magic». Цепочка: Environment → Builds → Snapshots / Secrets.