Настройка окружений
Окружение — это работающий стек одного пространства: сервисы, нужные ветке, изолированные от всех других пространств, видимые на боковой панели и доступные агентам. Оно есть и у пул-реквестов, потому что у PR уже есть собственное пространство.
Администратор рабочего пространства один раз пишет определение. После этого участники нажимают Запустить в разделе Окружение боковой панели пространства или PR. Определения хранятся в базе данных рабочего пространства, поэтому ветка с новой функцией никогда не меняет то, что запускает Control Center, хотя инструменты по-прежнему выполняют код этой ветки.
Создание определения
Заголовок раздела «Создание определения»- Откройте Настройки → Рабочее пространство → Окружения. Менять определения могут только администраторы рабочего пространства, а сохранить определение, которое работает на хосте сервера, может только владелец сервера (см. Кто что может сохранять).
- Нажмите Новое определение, затем Пустое определение или Черновик из репозитория. Черновик ищет в репозитории файлы compose,
Procfileи скриптыpackage.json, а результат вы проверяете сами. - Заполните форму или используйте вкладку JSON. Примеры на этой странице показывают этот JSON.
- Нажмите Запустить тест. Запустится одноразовое окружение; Control Center дождётся готовности и уничтожит его.
Сохранение строго проверяет определение. Неизвестное поле, значение неверного типа или неправильно написанный вариант отклоняется с указанием пути и ближайшего допустимого имени, например repos.app.requird: Unknown field. Did you mean "required"?. Верхнеуровневое $schema допускается.
Чтобы хранить определение в репозитории, используйте Связать файл репозитория. Control Center читает файл только из ветки по умолчанию и запускает только ту версию, которая одобрена: администратором рабочего пространства или, если определение работает на хосте, владельцем сервера. Более новая версия показывает Доступно обновление и ничего не меняет до одобрения.
Кто что может сохранять
Заголовок раздела «Кто что может сохранять»Определение окружения может запускать команды на хосте сервера от имени собственного пользователя сервера. Это решение владельца сервера, а не роли в рабочем пространстве:
- Определение работает на хосте, если у него размещение на хосте, проверка, которая запускает команду, или задача
provisionлибоarchive. Эти задачи выполняются в worktree пространства на хосте независимо от размещения. - Только владелец сервера может сохранить или одобрить определение, которое работает на хосте. Сюда входит одобрение новой версии связанного файла репозитория. Администратор рабочего пространства, который попытается это сделать, увидит «Только владелец сервера может сохранять или одобрять окружение, которое работает на хосте сервера. Администратор рабочего пространства может использовать окружение, которое работает в риге.»
- Администратор рабочего пространства может сохранять и одобрять определение, которое работает целиком в риге:
"placement": "rig", без команды проверки и без задачprovisionилиarchive. - Участники в любом случае запускают, останавливают и используют окружения.
- Определение, которое работает на хосте, запускается только после того, как его сохранил или одобрил текущий владелец сервера. Сервер сам записывает это одобрение и проверяет его перед каждым запуском, проверкой, задачей и синхронизацией головы пул-реквеста. Определение, которое текущий владелец не одобрил, например сохранённое предыдущим владельцем, ждёт под своей строкой в списке окружений и в редакторе. Владелец сервера видит «Запускается на этом сервере. Одобрите, чтобы оно могло стартовать.» с кнопкой Одобрить, которая сохраняет определение без изменений; все остальные видят «Запускается на этом сервере. Владелец сервера должен его одобрить, прежде чем оно сможет стартовать.»
- Окружение, которое ждёт этого одобрения, показывает «Владелец сервера ещё не одобрил это окружение, поэтому оно не может работать на этом сервере.» Владелец сервера вместо этого видит «Вы ещё не одобрили это окружение. Оно работает на этом сервере, поэтому запустится, когда вы одобрите его определение.» с кнопкой Проверить и одобрить, которая открывает определение.
- Терминалы процессов окружения и терминал, который открывается при запуске, если нужен ваш ответ, работают на хосте сервера. Для ввода в такой терминал, изменения его размера или закрытия нужен доступ на запись к каждому репозиторию, который открывает пространство и который читается через ваш собственный вход в хост кода: то же, что нужно для запуска окружения. Никто другой не может добраться до этих терминалов вовсе.
Самое маленькое определение
Заголовок раздела «Самое маленькое определение»Простому репозиторию с compose нужно только это:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}У всего остального есть значения по умолчанию: файл compose находится сам, запускаются все сервисы, назначаются порты, определяются конечные точки HTTP, а окружение получает имя ветки.
Виды компонентов
Заголовок раздела «Виды компонентов»Окружение — это упорядоченный список компонентов. Каждый ждёт готовности предыдущего, если after не называет другие, а остановка идёт в обратном порядке. enabledWhen ставит компонент в зависимость от параметра или роли, например opt.seed, !opt.seed или repo.web. Компонент, роль которого необязательна и не входит в пространство, пропускается точно так же и без enabledWhen: он не запускается и не имеет {port.*} и {url.*}, поэтому другой компонент, который их читает, приводит к ошибке запуска.
| Вид | Кто запускает | Для чего |
|---|---|---|
compose |
Драйвер compose в Control Center | Любой файл compose, один на окружение |
cli |
Ваш инструмент. Control Center вызывает назначенные глаголы и читает JSON | Инструмент, который сам владеет жизненным циклом, доменами и данными |
process |
Control Center в контролируемом сеансе терминала | Серверы разработки и воркеры |
task |
Control Center, один раз на триггер | Установка, миграции, тесты |
app |
Control Center, когда кто-то нажимает Открыть | Настольное приложение |
Компоненты task принимают список when:
| Триггер | Когда выполняется |
|---|---|
provision |
При создании worktree (см. задачи worktree ниже) |
create |
Один раз на окружение и снова после сброса |
start |
При каждом запуске |
change |
После синхронизации, если изменённый путь совпадает с onChange |
manual |
По запросу: Выполнить, cc-env run <id> или environment_run_task |
archive |
Непосредственно перед уничтожением worktree |
Задача, которой при запуске нечего делать, показывает Простой и не попадает в список шагов, выводимый при запуске окружения: задача manual или change, либо задача create, которая уже выполнилась.
Команда в виде массива — это argv, поэтому значения параметров никогда не проходят через оболочку. Строка или script с массивом строк выполняются в bash -lc. Заполнители вроде {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} и {url.<role>} раскрываются только в argv. Команды оболочки читают те же значения из переменных CC_ENV_*, например $CC_ENV_PORT_WEB. Неизвестный заполнитель в компоненте, который участвует в окружении, останавливает запуск до выполнения чего-либо.
Каждая команда и терминал пространства также получают CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE>, а в пространствах PR ещё CC_PR_NUMBER и CC_PR_IS_FORK. С компонентом compose они получают и COMPOSE_PROJECT_NAME с COMPOSE_FILE, поэтому docker compose exec в задаче попадает в нужный проект.
Роли и рабочий каталог
Заголовок раздела «Роли и рабочий каталог»Определение привязывает роли к репозиториям рабочего пространства, поэтому один стек может охватывать несколько репозиториев:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: пространство может запустить окружение, если в нём есть хотя бы одна якорная роль. Если подходят два определения, выбирает тот, кто запускает.required: без этого репозитория стек не работает.whenMissing: что делать, если в пространстве нет этой роли.addToSpaceдобавляет репозиторий на ветке по умолчанию и является значением по умолчанию для ролейrequired.useSourceпередаёт вашу зарегистрированную копию, с которой нужно обращаться как с доступной только для чтения.skipоставляет переменную незаданной и применяется по умолчанию в остальных случаях.- Для запуска нужны право
writeна якорный репозиторий в пространстве и доступ на чтение ко всем остальным привязанным репозиториям.
Команда выполняется в первой роли, объявленной в repos, а не в другой роли, которая случайно есть в пространстве, поэтому в определении с одним репозиторием об этом можно не упоминать. Любой компонент может изменить это с помощью "cwd": { "role": "e2e", "path": "packages/ui" }. Оба поля необязательны. Если первая роль может отсутствовать в пространстве, потому что она не required и не единственный якорь, каждый компонент должен указывать свою роль.
Порты и URL
Заголовок раздела «Порты и URL»Control Center назначает порты хоста до запуска чего-либо, из общего для хоста диапазона (по умолчанию от 42000 до 49999, блоками по 32). Порт не меняется всё время жизни окружения, а порты compose привязываются только к 127.0.0.1.
- Порты compose объявлять не нужно. Читайте их как
{port.postgres.5432}илиCC_ENV_PORT_POSTGRES_5432. - Остальные порты объявляются там, где используются, с помощью
"port": "web"или"ports": ["web", "hmr"], и читаются как{port.web}. Процесс с портом также получаетPORTиHOST=127.0.0.1.
Конечные точки HTTP получают URL на маршрутизаторе сервера, который слушает один порт loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>— ветка в виде слага илиpr-<n>в пространстве PR.<project>— этоnaming.project, а иначе имя определения.- Имена
*.localhostуказывают на loopback, поэтому им не нужны записи hosts и DNS, а имя хоста разделяет cookie между окружениями. - Порты compose, отвечающие по HTTP, определяются автоматически, а
httpв компоненте заменяет это предположение. Процессу нужен"endpoint": { "role": "web", "primary": true }, который также делает доступным{url.web}. - В браузере (ВМ) используйте Открыть в Browser (VM).
https://web--fix-login--shop.localhost/ведёт там на тот же маршрут. - Вся метка укладывается в 63 символа, поэтому длинные имена сокращаются с помощью хеша.
- У двух конечных точек нет общего родительского домена. Приложение, которому нужен один cookie для обеих, должно обслуживать их из одной конечной точки.
Для URL, которые нужно зарегистрировать заранее, например перенаправлений OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } даёт фиксированный набор имён.
policy определяет, когда работают окружения. autoCreate принимает значения off, prSpaces или allSpaces, idleStopMinutes по умолчанию равно 240, followPrHead синхронизирует окружение PR при сдвиге его head, а при maxRunning (по умолчанию 6) кнопка Запустить предлагает остановить давно не использовавшееся окружение.
Пример: приложение на compose
Заголовок раздела «Пример: приложение на compose»Веб-приложение и Postgres из одного файла compose, с игнорируемым git файлом .env, миграциями и задачей тестов. seedFiles копирует указанные файлы из вашей зарегистрированной копии в каждый новый worktree.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks позволяет сервису без собственной проверки работоспособности задержать следующий компонент. Без неё запущенный контейнер считается готовым, и миграции могут обогнать базу данных, которая ещё запускается.
Каждый запуск и обновление выполняют up с --remove-orphans, поэтому сервис, удалённый из compose-файла, останавливается и освобождает свой порт. Образы собираются при запуске и обновлении, если компонент не задаёт "build": false.
Пример: свой CLI
Заголовок раздела «Пример: свой CLI»Вымышленный инструмент acme, который сам владеет контейнерами, доменами и TLS. Control Center передаёт {name} и всё остальное узнаёт из status. Он никогда не выводит имена хостов инструмента и никогда не редактирует /etc/hosts.
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}create,statusиdestroyобязательны. Control Center выбираетcreateилиstartпо прочитанному статусу. Любой глагол может быть{ "shell": "…" }вместо argv.interactiveперечисляет глаголы изcreate,startиreset, которые могут запросить нужное им в терминале. Когда такой глагол завершается с кодом 3 для человека, нажавшего Запустить, Control Center снова запускает тот же глагол во вкладке терминала, и запуск продолжается, когда он завершится с кодом 0. Там условиеinteractiveистинно и заданоCC_ENV_INTERACTIVE=1, поэтому{ "if": "!interactive", "args": ["--json"] }сохраняет машинный вывод для канала. Запуск агентом или автоматический запуск никогда не открывает терминал: окружение показывает Нужны ваши действия и ждёт.destroy, который завершился с ошибкой, всё равно удаляет окружение, если затемstatusсообщаетmissing, так что окружение, которого у инструмента уже нет, всегда можно удалить.listпозволяет Control Center заметить окружение, которое инструмент утратил. Оно помечается как исчезнувшее, только если его имени нет в выводеlist, аstatusпри этом сообщаетmissing. Вывод, который нельзя прочитать как список, ничего не меняет.{service}вlogsиexecдолжен быть одним словом, не начинающимся с-, и одним из сервисов, о которых инструмент сообщил в последний раз, когда вообще сообщал.statusMapчитает собственный JSON инструмента с помощью указателей JSON, где*соответствует каждому элементу. Правила состояния упорядочены, и побеждает первое совпадение. Условие — этоpathсequalsлибоanyилиnoneсwhere.keepsDataOnStop: falseотключает остановку при простое и добавляет к Остановить предупреждение о потере данных. Задавайте его, если остановка теряет данные.routing.mode: "tool"подключает имена хостов инструмента к браузеру (ВМ) и агентам. Домен должен оканчиваться на.test,.localhostили.internal, а сообщённый URL вне его отбрасывается.
Ваш собственный инструмент может обойтись без statusMap и выводить контракт статуса, описанный в конце этой страницы.
Пример: монорепозиторий pnpm
Заголовок раздела «Пример: монорепозиторий pnpm»Только процессы и задачи, без контейнеров. Веб-приложение находит API через {url.api}.
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- Каждый процесс — это вкладка терминала, которую можно открыть, читать и в которой можно печатать, если у вас есть доступ на запись ко всем репозиториям пространства (см. Кто что может сохранять). Закрытие вкладки его не останавливает.
readyпринимаетhttp(полный URL),tcp(host:port) илиlogMatch(регулярное выражение).restartпринимаетon-failure(по умолчанию),alwaysилиnever.restartOnперезапускает процесс при совпадении изменённого пути.optionsпревращаются в форму у Запустить, аagentDefaultприменяется к запускам агентом.
Пример: настольное приложение
Заголовок раздела «Пример: настольное приложение»Настольное приложение с шагом сборки. Приложение работает одинаково, на чём бы оно ни было написано, потому что Control Center работает на уровне окон ОС и не требует хуков или SDK в приложении.
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}Приложение не запускается вместе с окружением. Кто-то нажимает Открыть, и сначала выполняется prepare. Пересобрать и перезапустить выполняет эту пару снова. enabledWhen применяется к приложению и к его задаче prepare, и Открыть отклоняется, пока любое из них выключено. Приложение считается запущенным, пока работает любой процесс в его группе процессов, поэтому запускатель, который стартует приложение и завершается, допустим. Если всё завершилось примерно через 5 секунд после Открыть, приложение показывается как сбойное с последними строками журнала. После этого чистый выход отображается как закрытие, сбой показывает последние строки журнала, и ни то, ни другое не перезапускает приложение. Перезапуск сервера закрывает приложение и никогда не запускает его снова, а остановка при простое не трогает работающее приложение.
Разрешения и ограничения настольных приложений
Заголовок раздела «Разрешения и ограничения настольных приложений»- В macOS один раз выдайте Control Center разрешения Запись экрана и Универсальный доступ в Системных настройках. На хосте сервера нужен графический сеанс: сервер без GUI отказывается запускать приложение.
- Запускайте бинарный файл напрямую.
open -aпередаёт приложение LaunchServices, и оно покидает дерево процессов, которое отслеживает Control Center, поэтому приложение сразу после запуска отображается как сбойное. - Окна остаются на дисплее. macOS не захватывает окно за пределами всех дисплеев, поэтому приложение, с которым работает агент, видно на экране сервера. Фокус ему не нужен.
"isolate": "home"даёт приложению приватный домашний каталог черезHOME,XDG_*иCFFIXED_USER_HOME, чтобы копии из двух пространств работали рядом.NSUserDefaultsне изолируется, поэтому настройки Cocoa иshared_preferencesво Flutter остаются общими для копий.isolateдействует только на запущенный процесс. Лаунчеру инструментов вродеflutter runнужен настоящий домашний каталог, поэтому сочетайтеisolateс собранным бинарным файлом. Если у приложения есть своя настройка, например--user-data-dir, лучше использовать её.- Агенты управляют окном через
app_use, которому доступно только дерево процессов этого окружения. Агент видит окно, а не рабочий стол. Запуски агентами проходят через политику действий и по умолчанию требуют подтверждения, а ввод агента останавливается, пока управление у человека. "input": "background"(по умолчанию) отправляет события процессу."foreground"активирует окно и перехватывает курсор.
Задачи worktree
Заголовок раздела «Задачи worktree»Задачи provision и archive выполняют настройку и очистку репозитория вместе с его worktree. Значок в строке репозитория в Настройки → Рабочее пространство → Репозитории открывает определение этого репозитория.
Эти задачи следуют за worktree, а не за окружением, поэтому выполняются и в пространствах, где никто не нажимает Запустить:
provision |
archive |
|
|---|---|---|
| Выполняется | При создании worktree роли в любом пространстве | Непосредственно перед уничтожением этого worktree |
| При сбое | Подготовка завершается ошибкой, и worktree уничтожается | Записывается, никогда не блокирует удаление |
| Тайм-аут по умолчанию | 5 минут | 2 минуты |
| Видит | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
То же самое |
Репозиторию без стека нужно только определение с его задачами. Запускать нечего, поэтому якорная роль не требуется:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Окружения ещё нет, поэтому в этих задачах нельзя использовать
{name},{port.*},{url.*},{opt.*}иenabledWhen, и они не получаютenvопределения. - Задачи
provisionиarchiveдля репозитория может содержать только одно определение. Другие могут привязывать его для всего остального. "when": ["provision", "change"]также переустанавливает зависимости при изменении lock-файла.- Задача выполняется для worktree своей роли
cwd, поэтому определение с несколькими репозиториями может настраивать каждый отдельно. - Тестовый запуск задаёт
CC_SCRIPT_TEST=1. Повторная попытка начинается с чистого worktree, поэтому пишите задачи, которые переживут повторный запуск.
Агенты никогда не получают сокет Docker. В пространстве с подходящим определением запуск получает cc-env в своём PATH. Пространство берётся из запуска, поэтому агент может действовать только в своём окружении, а каждая команда проходит через политику действий.
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>С компонентом compose шим docker также разрешает docker compose с ps, logs, exec, port, restart и top, и только для compose-проекта этого окружения. Перед глаголом нельзя ставить флаги, а каждый глагол принимает короткий список опций: logs не может следить за выводом, а exec принимает только -T (или --no-tty). Опции, которые направляют compose на другой файл или проект (-f, -p, --project-directory, --env-file, --profile), отклоняются, где бы они ни стояли. Всё остальное завершается с кодом 5 и сообщением «not available in Control Center agent runs».
Репозиторий, чьи навыки вызывают его собственный инструмент, может делать это и дальше. Блок agentPassthrough в компоненте cli объявляет, какие команды могут выполнять агенты. Проходят только команды, объявленные одобренным определением, и каждая из них выполняется на хосте, поэтому на неё распространяется правило Выполнение команд на хосте, которое по умолчанию спрашивает сначала:
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}maps называет операцию, чья политика применяется. positionalName принудительно подставляет в этот аргумент окружение этого пространства, nameFilter фильтрует по нему вывод JSON, а каждое значение pathFlags должно разрешаться внутри worktree запуска. Команда, не подошедшая ни под одно правило, завершается с кодом 5.
Те же операции доступны как инструменты: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app и environment_stop_app. Агенты в песочнице обращаются к своим портам напрямую, а к именам хостов своего окружения через прокси запуска, поэтому просите их читать конечные точки из environment_status, а не угадывать URL.
Пул-реквесты из форков
Заголовок раздела «Пул-реквесты из форков»Коду PR из форка нельзя доверять, а при размещении на хосте он выполняется от имени пользователя ОС сервера. policy.forkPrs решает, что произойдёт:
| Значение | Действие | По умолчанию для |
|---|---|---|
rig |
Файл compose выполняется в ВМ без запроса | Определений только с компонентами compose и task |
approval |
Каждый запуск требует администратора | Всех остальных определений |
deny |
Отказ | Никаких |
seedFilesникогда не копируются для форка, потому что обычно это секреты. Файл compose, который монтирует такой файл, сообщает об отсутствующем файле по имени.- Задачи
provisionиarchiveпропускаются, кроме случая, когда политика равнаrig: тогда они выполняются в ВМ. - При размещении на хосте для форка отклоняются
privileged, пространства имён хоста, монтирование сокета Docker,devicesи монтирования вне worktree пространства. В доверенных пространствах они дают только предупреждение.
Размещение в rig
Заголовок раздела «Размещение в rig»"placement": "rig" выполняет компоненты compose и task в выделенной microVM. Определения с компонентами process, cli или app не подходят. Файл compose выполняется без изменений, без сокета Docker хоста и учётных данных оператора, а доступ к сети ограничен реестрами, нужными его образам. Worktree монтируется вживую.
- Гостевые системы arm64. На Apple Silicon гостевые системы работают на arm64, поэтому образы только для amd64 не запустятся.
- Частные реестры отклоняются. У гостевых систем нет учётных данных реестров, поэтому образ из реестра вне известных публичных отклоняется до загрузки ВМ. Частный репозиторий в публичном реестре завершится ошибкой при скачивании гостем.
- 16 ГиБ хранилища. Все образы и тома стека делят один диск на 16 ГиБ, и увеличить его нельзя.
- Первая загрузка медленная. Слои образов у каждой ВМ свои, поэтому первая загрузка скачивает всё. Остановленный rig сохраняет свой диск.
- Базовые образы должны быть читаемы. Dockerfile, называющий базовый образ через переменную, нельзя спланировать, потому что доступ к сети фиксируется при загрузке.
- Время жизни.
policy.rigTtlHoursзавершает ВМ, по умолчанию через 24 часа.
Контракт статуса для авторов инструментов
Заголовок раздела «Контракт статуса для авторов инструментов»Компонент cli без statusMap ожидает нативный контракт cc-env/1. Глагол status выводит этот объект в stdout:
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}stateпринимает значенияready,starting,stopped,failedилиmissing.missingприводит кcreate, аstoppedиfailedприводят кstart. Сообщайтеmissingс кодом выхода 0: неудачныйstatusсчитаетсяfailed.- Обязателен только
state. Неизвестные поля игнорируются, а вывод, который нельзя разобрать, отображается как деградировавший, с исходным текстом в деталях. - URL должен быть loopback,
*.localhostили находиться подrouting.domain, иначе он отбрасывается. needsRecreate: trueпоказывает Пересоздать, что удаляет данные. Control Center никогда не действует по этому флагу сам.- Глагол
listвыводит массив JSON из имён или объектов сname.
Коды выхода действуют для всех глаголов:
| Код | Значение |
|---|---|
| 0 | ОК |
| 3 | Нужен ответ в терминале, например пароль sudo. Глагол, перечисленный в interactive, снова запускается во вкладке терминала для человека, нажавшего Запустить. Иначе Выполнить в терминале открывает терминал пространства с введённой, но не выполненной командой command инструмента, затем Повторить пробует снова. Control Center никогда не выполняет sudo и не отвечает на запрос |
| 4 | Требуется вход. Команда command инструмента указывает, как |
| 5 | Недоступно то, от чего он зависит, например не запущена среда выполнения контейнеров |
| Другой | Сбой |
Коды 3, 4 и 5 не являются сбоями. Окружение показывает Нужны ваши действия и ждёт, а следующий запуск продолжает с того места, где остановился предыдущий. Задача, которая завершается с одним из этих кодов, означает то же самое.
Ход выполнения идёт в stderr как JSON с разделением по строкам:
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}Пока окружение запускается, панель показывает компоненты, через которые проходит запуск, каждый с индикатором вращения, галочкой или крестиком. Строка step говорит, что инструмент делает сейчас, а её label показывается под строкой самого инструмента; шаги никогда не добавляют строк. Поле state шага имеет значение pending, running, done или failed, а шаг без state считается выполняющимся. Шаг, который сообщает снова под тем же id (строкой или числом, либо тем же label, если его нет), заменяет то, что сообщал раньше, поэтому инструмент с одним индикатором может сохранить один id и менять label. Без id шаги идут друг за другом: новый завершает предыдущий. Когда команда завершается, шаг, который ещё выполняется, завершается так же, как команда.
Строка log содержит одну строку вывода, которую инструмент упаковал в JSON, и читается как обычный вывод. Строка note попадает в вывод запуска, а строка с "level": "warn" также остаётся в окружении как предупреждение. Последняя строка типа error становится структурированной ошибкой, command предлагается скопировать, а последние 12 строк вывода показываются под её message. Без неё Control Center показывает последние 20 строк stderr. Всё, что не JSON, считается обычным журналом.