Перейти до вмісту

Налаштування середовищ

Середовище — це запущений стек одного простору: сервіси, потрібні гілці, ізольовані від усіх інших просторів, видимі на бічній панелі й доступні агентам. Воно є і в пул-реквестів, бо PR уже має власний простір.

Адміністратор робочого простору один раз пише визначення. Після цього учасники натискають Запустити у розділі Середовище бічної панелі простору або PR. Визначення зберігаються в базі даних робочого простору, тому гілка з новою функцією ніколи не змінює те, що запускає Control Center, хоча інструменти все одно виконують код цієї гілки.

  1. Відкрийте Налаштування → Робочий простір → Середовища. Змінювати визначення можуть лише адміністратори робочого простору, а зберегти визначення, яке працює на хості сервера, — лише власник сервера (див. Хто що може зберігати).
  2. Натисніть Нове визначення, потім Порожнє визначення або Чернетка з репозиторію. Чернетка шукає в репозиторії файли compose, Procfile і скрипти package.json, а результат перевіряєте ви.
  3. Заповніть форму або скористайтеся вкладкою JSON. Приклади на цій сторінці показують цей JSON.
  4. Натисніть Запустити тест. Запуститься одноразове середовище; Control Center дочекається готовності й знищить його.

Збереження суворо перевіряє визначення. Невідоме поле, значення неправильного типу або помилково написаний варіант відхиляються із зазначенням шляху та найближчої правильної назви, наприклад repos.app.requird: Unknown field. Did you mean "required"?. Верхньорівневий $schema дозволено.

Щоб зберігати визначення в репозиторії, використовуйте Пов’язати файл репозиторію. Control Center читає файл лише з типової гілки й запускає лише версію, схвалену адміністратором робочого простору, або власником сервера, якщо визначення працює на хості. Новіша версія показує Доступне оновлення і нічого не змінює до схвалення.

Визначення середовища може виконувати команди на хості сервера від імені користувача сервера. Це вирішує власник сервера, а не роль у робочому просторі:

  • Визначення працює на хості, коли має розміщення на хості, перевірку, що виконує команду, або завдання provision чи archive. Ці завдання виконуються в worktree простору на хості незалежно від розміщення.
  • Лише власник сервера може зберегти або схвалити визначення, яке працює на хості. Сюди входить схвалення нової версії пов’язаного файлу репозиторію. Адміністратор робочого простору, який спробує це зробити, побачить «Лише власник сервера може зберегти або схвалити середовище, яке працює на хості сервера. Адміністратор робочого простору може користуватися тим, що працює в rig.»
  • Адміністратор робочого простору може зберегти й схвалити визначення, яке працює повністю в rig: "placement": "rig", без команди перевірки і без завдань provision чи archive.
  • Учасники запускають, зупиняють і використовують середовища в будь-якому разі.
  • Визначення, яке працює на хості, запускається лише після того, як поточний власник сервера його зберіг або схвалив. Сервер сам записує це схвалення і перевіряє його перед кожним запуском, перевіркою, завданням і синхронізацією голови pull request. Визначення, яке поточний власник не схвалив, наприклад збережене попереднім власником, чекає під своїм рядком у списку середовищ і в редакторі. Власник сервера бачить «Працює на цьому сервері. Схваліть, щоб дозволити запуск.» з кнопкою Схвалити, яка зберігає його без змін; усі інші бачать «Працює на цьому сервері. Власник сервера має схвалити його, перш ніж він зможе запуститися».
  • Середовище, яке чекає на це схвалення, каже «Власник сервера ще не схвалив це середовище, тож воно не може працювати на цьому сервері.» Власник сервера натомість бачить «Ви ще не схвалили це середовище. Воно працює на цьому сервері, тож запуститься, щойно ви схвалите його визначення.» з кнопкою Переглянути й схвалити, яка відкриває визначення.
  • Термінали процесів середовища та термінал, який відкривається під час запуску, коли потрібна ваша відповідь, працюють на хості сервера. Щоб друкувати в одному, змінювати його розмір або закривати, потрібен доступ на запис до кожного репозиторію, який відкриває простір, і він читається через ваш власний вхід у хостинг коду: те саме, що й для запуску середовища. Жоден інший користувач навіть не може дістатися до цих терміналів.

Простому репозиторію з 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 і не єдиний якір, кожен компонент має вказувати свою роль.

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) кнопка Запустити пропонує зупинити середовище, яке найдавніше використовували.

Вебзастосунок і 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.

Вигаданий інструмент 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 і виводити контракт статусу, описаний наприкінці цієї сторінки.

Лише процеси й завдання, без контейнерів. Вебзастосунок знаходить 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" активує вікно й перехоплює курсор.

Завдання 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 status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-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 простору. У довірених просторах вони дають лише попередження.

"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. Без ідентифікаторів кроки йдуть один за одним: новий завершує попередній. Коли команда завершується, крок, що ще виконується, завершується так само, як команда.

Рядок log містить один рядок виводу, який інструмент загорнув у JSON, і читається як звичайний вивід. Рядок note потрапляє у вивід запуску, а рядок із "level": "warn" також залишається в середовищі як попередження. Останній рядок типу error стає структурованою помилкою, command пропонується скопіювати, а останні 12 рядків виводу показуються під його message. Без нього Control Center показує останні 20 рядків stderr. Усе, що не JSON, вважається звичайним журналом.