Sari la conținut

Configurarea mediilor

Un mediu este stack-ul în execuție al unui spațiu: serviciile de care are nevoie o ramură, izolate de toate celelalte spații, vizibile în bara laterală și accesibile agenților. Primesc unul și pull request-urile, pentru că un PR are deja propriul spațiu.

Un administrator al spațiului de lucru scrie o definiție o singură dată. Membrii apasă apoi Pornește în secțiunea Mediu din bara laterală a unui spațiu sau PR. Definițiile se află în baza de date a spațiului de lucru, așa că o ramură de funcționalitate nu schimbă niciodată ce rulează Control Center, deși instrumentele rulează în continuare codul acelei ramuri.

  1. Deschide Setări → Spațiu de lucru → Medii. Doar administratorii spațiului de lucru pot modifica definițiile, iar doar proprietarul serverului poate salva una care rulează pe gazda serverului (vezi Cine poate salva ce).
  2. Apasă Definiție nouă, apoi Definiție goală sau Schiță din repo. O ciornă caută în depozit fișiere compose, un Procfile și scripturi package.json, iar tu verifici rezultatul.
  3. Completează formularul sau folosește fila JSON. Exemplele de pe această pagină sunt acel JSON.
  4. Apasă Rulează testul. Pornește un mediu de unică folosință, așteaptă să fie gata și îl distruge.

Salvarea verifică strict o definiție. Un câmp necunoscut, o valoare de tip greșit sau o opțiune scrisă greșit este refuzat, cu calea lui și numele valid cel mai apropiat, cum ar fi repos.app.requird: Unknown field. Did you mean "required"?. Un $schema de nivel superior este permis.

Pentru a păstra o definiție într-un depozit, folosește Leagă un fișier din repo. Control Center citește fișierul doar din ramura implicită și rulează doar versiunea care a fost aprobată: de un administrator al spațiului de lucru sau, când definiția rulează pe gazdă, de proprietarul serverului. O versiune mai nouă afișează Actualizare disponibilă și nu schimbă nimic până la aprobare.

O definiție de mediu poate rula comenzi pe gazda serverului, ca utilizatorul propriu al serverului. Decizia aparține proprietarului serverului, nu unui rol din spațiul de lucru:

  • O definiție rulează pe gazdă atunci când are plasare pe gazdă, o verificare care rulează o comandă sau o sarcină provision ori archive. Acele sarcini rulează în worktree-ul spațiului de pe gazdă, indiferent de plasare.
  • Doar proprietarul serverului poate salva sau aproba o definiție care rulează pe gazdă. Asta include aprobarea unei versiuni noi a unui fișier legat din repo. Un administrator al spațiului de lucru care încearcă vede „Doar proprietarul serverului poate salva sau aproba un mediu care rulează pe gazda serverului. Un administrator al spațiului de lucru poate folosi unul care rulează într-o stație.”
  • Un administrator al spațiului de lucru poate salva și aproba o definiție care rulează în întregime într-o stație: "placement": "rig", fără comandă de verificare și fără sarcină provision sau archive.
  • Membrii pornesc, opresc și folosesc mediile în ambele cazuri.
  • O definiție care rulează pe gazdă pornește doar după ce proprietarul actual al serverului a salvat-o sau aprobat-o. Serverul înregistrează singur acea aprobare și o verifică înainte de fiecare pornire, verificare, sarcină și sincronizare a capului pull request-ului. O definiție pe care proprietarul actual nu a aprobat-o, cum este una salvată de un proprietar anterior, așteaptă sub rândul ei din lista de medii și în editor. Proprietarul serverului vede „Rulează pe acest server. Aprobă-l ca să poată porni.” cu Aprobă, care o salvează neschimbată; ceilalți văd „Rulează pe acest server. Proprietarul serverului trebuie să îl aprobe înainte să poată porni.”
  • Un mediu reținut pentru această aprobare spune „Proprietarul serverului nu a aprobat încă acest mediu, deci nu poate rula pe acest server.” Proprietarul serverului vede în schimb „Nu ai aprobat încă acest mediu. Rulează pe acest server, deci pornește după ce aprobi definiția lui.” cu Revizuiește și aprobă, care deschide definiția.
  • Terminalele de procese ale unui mediu, și terminalul pe care o pornire îl deschide când e nevoie de intervenția ta, rulează pe gazda serverului. A scrie în ele, a le redimensiona sau a le închide necesită drept de scriere pe fiecare repository pe care îl expune spațiul, citibil prin propria ta autentificare la forge: la fel ca pornirea mediului. Ceilalți nu pot ajunge deloc la aceste terminale.

Unui depozit compose simplu îi ajunge atât:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

Restul are valori implicite: fișierul compose este descoperit, toate serviciile rulează, porturile sunt alocate, punctele finale HTTP sunt detectate, iar mediul primește numele ramurii.

Un mediu este o listă ordonată de componente. Fiecare așteaptă ca precedenta să fie gata, dacă after nu indică altele, iar oprirea are loc în ordine inversă. enabledWhen condiționează o componentă de o opțiune sau de un rol, de exemplu opt.seed, !opt.seed sau repo.web. O componentă al cărei rol este opțional și lipsește din spațiu este lăsată deoparte în același fel, fără să fie nevoie de enabledWhen: nu pornește și nu are {port.*} sau {url.*}, astfel că altă componentă care le citește face pornirea să eșueze.

Tip Cine o rulează La ce folosește
compose Driverul compose din Control Center Orice fișier compose, unul per mediu
cli Instrumentul tău. Control Center apelează verbe mapate și citește JSON Un instrument care își gestionează ciclul de viață, domeniile și datele
process Control Center, într-o sesiune de terminal supravegheată Servere de dezvoltare și workeri
task Control Center, o dată per declanșator Instalări, migrări, teste
app Control Center, când cineva apasă Lansează O aplicație desktop

Componentele task primesc o listă when:

Declanșator Când rulează
provision La crearea worktree-ului (vezi mai jos sarcinile de worktree)
create O dată per mediu și din nou după o resetare
start La fiecare pornire
change După o sincronizare, dacă o cale modificată se potrivește cu onChange
manual La cerere: Rulează, cc-env run <id> sau environment_run_task
archive Chiar înainte de distrugerea worktree-ului

O sarcină care nu are nimic de făcut la pornire apare cu Inactiv și nu este inclusă în lista de pași afișată în timpul pornirii mediului: o sarcină manual sau change, ori o sarcină create care a rulat deja.

O comandă dată ca tablou este argv, așa că valorile opțiunilor nu trec niciodată printr-un shell. Un șir, sau script cu un tablou de linii, rulează sub bash -lc. Substituentele precum {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} și {url.<role>} se expandează doar în argv. Comenzile shell citesc aceleași valori ca variabile CC_ENV_*, de exemplu $CC_ENV_PORT_WEB. Un substituent necunoscut dintr-o componentă care participă oprește pornirea înainte ca orice să ruleze.

Fiecare comandă și terminal de spațiu primește și CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> și, în spațiile de PR, CC_PR_NUMBER și CC_PR_IS_FORK. Cu o componentă compose primesc și COMPOSE_PROJECT_NAME și COMPOSE_FILE, astfel că docker compose exec într-o sarcină ajunge la proiectul potrivit.

O definiție leagă roluri de depozitele spațiului de lucru, astfel încât un stack poate cuprinde mai multe depozite:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: un spațiu poate porni mediul dacă are cel puțin un rol ancoră. Dacă se potrivesc două definiții, alege persoana care pornește.
  • required: stack-ul nu poate rula fără acest depozit.
  • whenMissing: ce se întâmplă când spațiului îi lipsește rolul. addToSpace adaugă depozitul pe ramura implicită și este valoarea implicită pentru rolurile required. useSource transmite copia ta înregistrată, pe care trebuie să o tratezi ca doar pentru citire. skip lasă variabila nesetată și este implicit în celelalte cazuri.
  • Pornirea necesită o permisiune write pe un depozit ancoră din spațiu și acces de citire la toate celelalte depozite legate.

O comandă rulează în primul rol declarat în repos, niciodată într-un alt rol pe care îl are spațiul, așa că o definiție cu un singur depozit nu îl menționează niciodată. Orice componentă poate schimba asta cu "cwd": { "role": "e2e", "path": "packages/ui" }. Ambele câmpuri sunt opționale. Când primul rol ar putea lipsi dintr-un spațiu, pentru că nu este required și nici singura ancoră, fiecare componentă trebuie să își numească rolul.

Control Center alocă porturi de gazdă înainte să pornească ceva, dintr-un interval comun întregii gazde (implicit de la 42000 la 49999, în blocuri de 32). Un port rămâne același pe toată durata de viață a mediului, iar porturile compose se leagă doar la 127.0.0.1.

  • Porturile compose nu trebuie declarate. Citește-le ca {port.postgres.5432} sau CC_ENV_PORT_POSTGRES_5432.
  • Celelalte porturi se declară acolo unde sunt folosite, cu "port": "web" sau "ports": ["web", "hmr"], și se citesc ca {port.web}. Un proces cu port primește și PORT și HOST=127.0.0.1.

Punctele finale HTTP primesc un URL pe routerul serverului, care ascultă pe un singur port loopback:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> este ramura sub formă de slug, sau pr-<n> într-un spațiu de PR. <project> este naming.project, altfel numele definiției.
  • Numele *.localhost indică loopback, deci nu au nevoie de intrări hosts sau DNS, iar numele de gazdă separă cookie-urile între medii.
  • Porturile compose care răspund la HTTP sunt detectate, iar http pe componentă înlocuiește această presupunere. Un proces are nevoie de "endpoint": { "role": "web", "primary": true }, care face disponibil și {url.web}.
  • În browser (VM), folosește Deschide în Browser (VM). https://web--fix-login--shop.localhost/ ajunge acolo la aceeași rută.
  • Eticheta întreagă rămâne în limita a 63 de caractere, așa că numele lungi sunt scurtate cu un hash.
  • Două puncte finale nu au un domeniu părinte comun. O aplicație care are nevoie de un cookie pe ambele trebuie să le servească dintr-un singur punct final.

Pentru URL-urile care trebuie înregistrate din timp, cum sunt redirecționările OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } oferă un set fix de nume.

policy decide când rulează mediile. autoCreate este off, prSpaces sau allSpaces, idleStopMinutes are implicit 240, followPrHead sincronizează mediul unui PR când se mută head-ul, iar cu maxRunning (implicit 6) Pornește propune oprirea mediului folosit cel mai demult.

O aplicație web și Postgres dintr-un singur fișier compose, cu un .env ignorat de git, migrări și o sarcină de testare. seedFiles copiază fișiere numite din copia ta înregistrată în fiecare worktree nou.

{
"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 permite unui serviciu fără verificare proprie de sănătate să rețină componenta următoare. Fără ea, un container în execuție contează ca gata, iar migrările pot depăși o bază de date care încă pornește.

Fiecare pornire și reîmprospătare rulează up cu --remove-orphans, astfel că un serviciu scos din fișierul compose se oprește și își eliberează portul. Imaginile sunt construite la pornire și la reîmprospătare, dacă componenta nu setează "build": false.

Un instrument inventat, acme, care își gestionează containerele, domeniile și TLS-ul. Control Center oferă {name} și află restul din status. Nu deduce niciodată numele de gazdă ale unui instrument și nu editează niciodată /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 și destroy sunt obligatorii. Control Center alege create sau start după starea citită. Orice verb poate fi { "shell": "…" } în loc de argv.
  • interactive numește verbele, dintre create, start și reset, care pot cere ce le trebuie la un terminal. Când un astfel de verb se termină cu codul 3 pentru o persoană care a apăsat Pornește, Control Center rulează din nou același verb într-un tab de terminal, iar pornirea continuă când acesta se termină cu codul 0. Acolo condiția interactive este adevărată și CC_ENV_INTERACTIVE=1 este setat, astfel că { "if": "!interactive", "args": ["--json"] } păstrează ieșirea pentru mașini pentru pipe. O pornire de către un agent sau una automată nu deschide niciodată un terminal: mediul arată Necesită acțiune și așteaptă.
  • Un destroy care eșuează tot elimină mediul dacă status raportează apoi missing, astfel încât un mediu pe care instrumentul nu-l mai are poate fi întotdeauna șters.
  • list permite Control Center să observe un mediu pe care unealta l-a pierdut. Este marcat ca dispărut doar când numele lui lipsește din list și status atunci spune missing. Ieșirea care nu poate fi citită ca listă nu schimbă nimic.
  • {service} din logs și exec trebuie să fie un singur cuvânt care nu începe cu -, și unul dintre serviciile raportate ultima dată de unealtă, dacă a raportat vreunul.
  • statusMap citește JSON-ul instrumentului cu pointeri JSON, unde * se potrivește cu fiecare element. Regulile de stare sunt ordonate și câștigă prima potrivire. O condiție este path cu equals, sau any ori none cu where.
  • keepsDataOnStop: false dezactivează oprirea la inactivitate și adaugă la Oprește un avertisment de pierdere a datelor. Setează-l când oprirea pierde date.
  • routing.mode: "tool" conectează numele de gazdă ale instrumentului la browser (VM) și la agenți. Domeniul trebuie să se termine cu .test, .localhost sau .internal, iar un URL raportat în afara lui este eliminat.

Un instrument al tău poate renunța la statusMap și poate tipări contractul de stare descris la finalul acestei pagini.

Doar procese și sarcini, fără containere. Aplicația web găsește API-ul prin {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"] }
]
}
  • Fiecare proces este o filă de terminal pe care o poți deschide, citi și în care poți scrie, dacă ai drept de scriere pe fiecare repository din spațiu (vezi Cine poate salva ce). Închiderea filei nu îl oprește.
  • ready acceptă http (un URL complet), tcp (host:port) sau logMatch (o expresie regulată). restart este on-failure (implicit), always sau never. restartOn repornește procesul când se potrivește o cale modificată.
  • options devin un formular la Pornește, iar agentDefault se aplică rulărilor pornite de un agent.

O aplicație desktop cu un pas de compilare. O aplicație funcționează la fel indiferent de tehnologie, pentru că Control Center lucrează la nivelul ferestrelor sistemului de operare și nu are nevoie de hook sau SDK în aplicație.

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

O aplicație nu pornește odată cu mediul. Cineva apasă Lansează, iar prepare rulează mai întâi. Recompilează și relansează rulează din nou această pereche. enabledWhen se aplică aplicației și sarcinii ei prepare, iar Lansează este refuzat cât timp oricare dintre ele este oprită. O aplicație este considerată în rulare cât timp rulează orice proces din grupul ei de procese, așa că un lansator care pornește aplicația și iese este în regulă. Dacă totul dispare în aproximativ 5 secunde de la Lansează, aplicația apare ca eșuată, cu ultimele linii de jurnal. După aceea, o ieșire curată apare ca închisă și un crash arată ultimele linii de jurnal, iar niciuna dintre acestea nu o repornește. O repornire a serverului închide aplicația și nu o relansează niciodată, iar oprirea la inactivitate lasă în pace o aplicație care rulează.

  • Pe macOS, acordă o dată aplicației Control Center Înregistrare ecran și Accesibilitate în Configurări sistem. Gazda serverului are nevoie de o sesiune grafică: un server headless refuză să lanseze o aplicație.
  • Lansează direct binarul. open -a predă aplicația către LaunchServices și aceasta iese din arborele de procese urmărit de Control Center, așa că aplicația apare ca eșuată imediat după lansare.
  • Ferestrele rămân pe un ecran. macOS nu capturează o fereastră plasată în afara tuturor ecranelor, așa că o aplicație folosită de un agent este vizibilă pe ecranul serverului. Nu are nevoie de focus.
  • "isolate": "home" oferă aplicației un director personal privat prin HOME, XDG_* și CFFIXED_USER_HOME, astfel încât copii din două spații pot rula în paralel. NSUserDefaults nu este izolat, așa că preferințele Cocoa și shared_preferences din Flutter rămân comune între copii.
  • isolate se aplică doar procesului lansat. Un lansator de toolchain precum flutter run are nevoie de directorul personal real, așa că asociază isolate cu un binar compilat. Dacă aplicația are o setare proprie, cum e --user-data-dir, preferă-o.
  • Agenții controlează fereastra cu app_use, care ajunge doar la arborele de procese al acestui mediu. Un agent vede fereastra, nu desktopul. Lansările agenților trec prin politica de acțiuni și implicit cer confirmare, iar intrarea agentului se oprește cât timp o persoană are controlul.
  • "input": "background" (implicit) trimite evenimente către proces. "foreground" activează fereastra și preia cursorul.

Sarcinile provision și archive rulează configurarea și demontarea unui depozit împreună cu worktree-ul lui. Pictograma de pe rândul unui depozit din Setări → Spațiu de lucru → Depozite o deschide.

Aceste sarcini urmează worktree-ul, nu mediul, așa că rulează în spații unde nimeni nu apasă Pornește:

provision archive
Rulează La crearea worktree-ului rolului, în orice spațiu Chiar înainte de distrugerea acelui worktree
La eșec Provizionarea eșuează și worktree-ul este distrus Înregistrat, nu blochează niciodată ștergerea
Timp limită implicit 5 minute 2 minute
Vede CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME La fel

Un depozit fără stack are nevoie doar de o definiție cu sarcinile lui. Neavând ce porni, nu necesită rol ancoră:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • Nu există încă un mediu, așa că aceste sarcini nu pot folosi {name}, {port.*}, {url.*}, {opt.*} sau enabledWhen și nu primesc env din definiție.
  • O singură definiție poate avea sarcini provision și archive pentru un depozit. Celelalte îl pot lega în continuare pentru orice altceva.
  • "when": ["provision", "change"] reinstalează și când se schimbă un fișier de blocare.
  • O sarcină rulează pentru worktree-ul rolului ei cwd, așa că o definiție cu mai multe depozite poate configura fiecare depozit separat.
  • O rulare de test setează CC_SCRIPT_TEST=1. O reîncercare pornește de la un worktree curat, așa că scrie sarcini care suportă o nouă rulare.

Agenții nu primesc niciodată socketul Docker. Într-un spațiu cu o definiție eligibilă, o rulare primește cc-env în PATH. Spațiul vine din rulare, așa că un agent poate acționa doar asupra propriului mediu, iar fiecare comandă trece prin politica de acțiuni.

Fereastră terminal
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>

Cu o componentă compose, un shim docker permite și docker compose cu ps, logs, exec, port, restart și top, și doar față de proiectul compose propriu al acestui mediu. Înainte de verb nu pot exista flaguri, iar fiecare verb acceptă o listă scurtă de opțiuni: logs nu poate urmări ieșirea, iar exec acceptă doar -T (sau --no-tty). Opțiunile care îndreaptă compose spre alt fișier sau alt proiect (-f, -p, --project-directory, --env-file, --profile) sunt refuzate oriunde ar apărea. Orice altceva se încheie cu codul 5 și „not available in Control Center agent runs”.

Un depozit ale cărui skill-uri apelează propriul instrument poate continua așa. Un bloc agentPassthrough pe o componentă cli declară ce comenzi pot rula agenții. Doar comenzile declarate de definiția aprobată trec prin, iar fiecare rulează pe gazdă, deci respectă regula Rulează comenzi pe gazdă, care cere confirmare implicit:

"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 numește operația a cărei politică se aplică. positionalName forțează acel argument la mediul acestui spațiu, nameFilter filtrează ieșirea JSON pentru el, iar fiecare valoare pathFlags trebuie să se rezolve în interiorul worktree-urilor rulării. O comandă care nu se potrivește cu nicio regulă se încheie cu codul 5.

Aceleași operații există ca instrumente: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app și environment_stop_app. Agenții din sandbox ajung direct la porturile lor și la numele de gazdă ale mediului prin proxy-ul rulării, așa că spune-le să citească punctele finale din environment_status în loc să ghicească un URL.

Codul unui PR dintr-un fork nu este de încredere, iar la plasarea pe gazdă rulează ca utilizatorul de sistem al serverului. policy.forkPrs decide ce se întâmplă:

Valoare Efect Implicit pentru
rig Fișierul compose rulează într-o VM, fără întrebare Definițiile doar cu componente compose și task
approval Fiecare pornire necesită un administrator Toate celelalte definiții
deny Refuzat Niciuna
  • seedFiles nu sunt niciodată copiate pentru un fork, pentru că de obicei sunt secrete. Un fișier compose care montează unul raportează fișierul lipsă pe nume.
  • Sarcinile provision și archive sunt omise, cu excepția cazului în care politica este rig, când rulează în VM.
  • La plasarea pe gazdă, privileged, spațiile de nume ale gazdei, montarea socketului Docker, devices și montările din afara worktree-urilor spațiului sunt refuzate pe un fork. În spațiile de încredere generează doar un avertisment.

"placement": "rig" rulează componentele compose și task într-o microVM dedicată. Definițiile cu componente process, cli sau app nu sunt eligibile. Fișierul compose rulează nemodificat, fără socketul Docker al gazdei și fără credențialele operatorului, iar accesul la rețea este limitat la registrele de care au nevoie imaginile. Worktree-ul este montat direct.

  • Oaspeți arm64. Oaspeții sunt arm64 pe Apple Silicon, așa că imaginile doar amd64 nu rulează.
  • Registrele private sunt refuzate. Oaspeții nu au credențiale de registru, așa că o imagine dintr-un registru din afara celor publice cunoscute este refuzată înainte de pornirea VM. Un depozit privat dintr-un registru public eșuează când oaspetele îl descarcă.
  • 16 GiB de stocare. Toate imaginile și volumele stack-ului împart un disc de 16 GiB, care nu poate fi mărit.
  • Prima pornire este lentă. Straturile de imagine sunt per VM, așa că prima pornire descarcă totul. Un rig oprit își păstrează discul.
  • Imaginile de bază trebuie să poată fi citite. Un Dockerfile care își numește imaginea de bază printr-o variabilă nu poate fi planificat, pentru că accesul la rețea se fixează la pornire.
  • Durată de viață. policy.rigTtlHours încheie VM-ul, implicit după 24 de ore.

O componentă cli fără statusMap așteaptă contractul nativ, cc-env/1. Verbul status tipărește acest obiect pe 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 este ready, starting, stopped, failed sau missing. missing duce la create, iar stopped și failed duc la start. Raportează missing cu codul de ieșire 0: un status eșuat contează ca failed.
  • Este necesar doar state. Câmpurile necunoscute sunt ignorate, iar ieșirea care nu poate fi analizată apare ca degradată, cu textul brut ca detaliu.
  • Un URL trebuie să fie loopback, *.localhost sau sub routing.domain, altfel este eliminat.
  • needsRecreate: true afișează Recreează, care elimină datele. Control Center nu acționează niciodată singur pe baza acestui câmp.
  • Verbul list tipărește un tablou JSON de nume, sau de obiecte cu un name.

Codurile de ieșire se aplică tuturor verbelor:

Cod Semnificație
0 OK
3 Este nevoie de un răspuns într-un terminal, cum ar fi o parolă pentru sudo. Un verb listat în interactive rulează din nou într-un tab de terminal pentru persoana care a apăsat Pornește. Altfel, Rulează în terminal deschide un terminal de spațiu cu command al uneltei scris, dar nerulat, apoi Reîncearcă încearcă din nou. Control Center nu rulează niciodată sudo și nu răspunde niciodată unei solicitări
4 Este necesară autentificarea. Câmpul command al uneltei spune cum
5 Ceva de care depinde nu este disponibil, cum ar fi un runtime de containere care nu rulează
Altul Eșec

Codurile 3, 4 și 5 nu sunt eșecuri. Mediul arată Necesită acțiune și așteaptă, iar următoarea pornire continuă de unde s-a oprit cea anterioară. O sarcină care se termină cu unul dintre ele înseamnă același lucru.

Progresul merge pe stderr ca JSON delimitat prin linii noi:

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

Cât timp mediul pornește, panoul listează componentele prin care trece pornirea, fiecare cu un indicator rotitor, un semn de bifă sau o cruce. O linie step spune ce face instrumentul acum, iar label-ul ei apare sub linia proprie a instrumentului; pașii nu adaugă niciodată linii. state unui pas este pending, running, done sau failed, iar un pas fără state este în curs de rulare. Un pas care raportează din nou sub același id (un șir sau un număr, ori același label, dacă nu are unul) înlocuiește ce spunea înainte, așa că un instrument cu un singur indicator poate păstra un id și poate schimba label-ul. Fără id-uri, pașii se succed: unul nou îl încheie pe cel dinaintea lui. Când comanda se termină, un pas încă în curs se încheie în același fel în care s-a încheiat comanda.

O linie log conține o linie de ieșire pe care instrumentul a împachetat-o în JSON și se citește ca ieșire obișnuită. O linie note ajunge în ieșirea rulării, iar una cu "level": "warn" rămâne și pe mediu ca avertisment. O ultimă linie de tip error devine o eroare structurată, cu command oferit pentru copiere, iar ultimele 12 linii de ieșire apar sub message. Fără ea, Control Center arată ultimele 20 de linii din stderr. Tot ce nu este JSON este jurnal obișnuit.