Omgevingen instellen
Een omgeving is de draaiende stack van één ruimte: de services die een branch nodig heeft, geïsoleerd van alle andere ruimtes, zichtbaar in de zijbalk en bereikbaar voor agents. Ook pull requests krijgen er een, want een PR heeft al een eigen ruimte.
Een beheerder van de werkruimte schrijft één keer een definitie. Leden klikken daarna op Starten in het onderdeel Omgeving van de zijbalk van een ruimte of PR. Definities staan in de database van de werkruimte, dus een featurebranch verandert nooit wat Control Center uitvoert, al voeren de tools wel de code van die branch uit.
Een definitie maken
Sectie getiteld “Een definitie maken”- Open Instellingen → Werkruimte → Omgevingen. Alleen beheerders van de werkruimte kunnen definities wijzigen, en alleen de serverbeheerder kan er een opslaan die op de serverhost draait (zie Wie wat kan opslaan).
- Klik op Nieuwe definitie en daarna op Lege definitie of Concept uit repo. Een concept doorzoekt de repo op compose-bestanden, een
Procfileenpackage.json-scripts, en jij controleert het resultaat. - Vul het formulier in of gebruik het tabblad JSON. De voorbeelden op deze pagina zijn die JSON.
- Klik op Test uitvoeren. Dat start een wegwerpomgeving, wacht tot die klaar is en vernietigt hem weer.
Opslaan controleert een definitie streng. Een onbekend veld, een waarde van het verkeerde type of een verkeerd gespelde keuze wordt geweigerd, met het pad en de dichtstbijzijnde geldige naam, zoals repos.app.requird: Unknown field. Did you mean "required"?. Een $schema op het hoogste niveau is toegestaan.
Gebruik Repo-bestand koppelen om een definitie in een repo te bewaren. Control Center leest het bestand alleen van de standaardbranch en voert alleen de versie uit die is goedgekeurd: door een beheerder van de werkruimte, of door de serverbeheerder wanneer de definitie op de host draait. Een nieuwere versie toont Update beschikbaar en verandert niets totdat ze is goedgekeurd.
Wie wat kan opslaan
Sectie getiteld “Wie wat kan opslaan”Een omgevingsdefinitie kan opdrachten uitvoeren op de serverhost als de eigen gebruiker van de server. Dat is een beslissing van de servereigenaar, niet van een werkruimterol:
- Een definitie draait op de host wanneer hij host-plaatsing heeft, een controle die een opdracht uitvoert, of een
provision- ofarchive-taak. Die taken draaien in de worktree van de ruimte op de host, wat de plaatsing ook is. - Alleen de serverbeheerder kan een definitie die op de host draait opslaan of goedkeuren. Dat geldt ook voor het goedkeuren van een nieuwe versie van een gekoppeld repo-bestand. Een werkruimte-admin die het probeert, ziet “Alleen de serverbeheerder kan een omgeving opslaan of goedkeuren die op de serverhost draait. Een werkruimte-admin kan er een gebruiken die in een rig draait.”
- Een werkruimte-admin kan een definitie die volledig in een rig draait opslaan en goedkeuren:
"placement": "rig", geen controle-opdracht en geenprovision- ofarchive-taak. - Leden starten, stoppen en gebruiken omgevingen in beide gevallen.
- Een definitie die op de host draait, draait pas nadat de huidige servereigenaar hem heeft opgeslagen of goedgekeurd. De server legt die goedkeuring zelf vast en controleert haar vóór elke start, controle, taak en synchronisatie van de pull-requestkop. Een definitie die de huidige eigenaar niet heeft goedgekeurd, zoals een definitie die een vorige eigenaar heeft opgeslagen, wacht onder zijn rij in de omgevingslijst en in de editor. De serverbeheerder ziet “Draait op deze server. Keur hem goed om het starten toe te staan.” met Goedkeuren, wat hem ongewijzigd opslaat; alle anderen zien “Draait op deze server. De serverbeheerder moet hem goedkeuren voordat hij kan starten.”
- Een omgeving die op die goedkeuring wacht, zegt “De serverbeheerder heeft deze omgeving nog niet goedgekeurd, dus hij kan niet op deze server draaien.” De serverbeheerder ziet in plaats daarvan “Je hebt deze omgeving nog niet goedgekeurd. Hij draait op deze server en start zodra je de definitie goedkeurt.” met Bekijken en goedkeuren, wat de definitie opent.
- De procesterminals van een omgeving en de terminal die een start opent wanneer die jou nodig heeft, draaien op de serverhost. Typen in een ervan, de grootte ervan wijzigen of hem sluiten vereist schrijfrechten op elke repository die de ruimte blootstelt, leesbaar via je eigen forge-aanmelding: hetzelfde als het starten van de omgeving. Alle anderen kunnen die terminals helemaal niet bereiken.
De kleinste definitie
Sectie getiteld “De kleinste definitie”Een eenvoudige compose-repo heeft genoeg aan dit:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Al het andere heeft een standaardwaarde: het compose-bestand wordt gevonden, elke service draait, poorten worden toegewezen, HTTP-eindpunten worden herkend en de omgeving krijgt de naam van de branch.
Soorten componenten
Sectie getiteld “Soorten componenten”Een omgeving is een geordende lijst componenten. Elk component wacht tot het vorige klaar is, tenzij after andere noemt, en stoppen gaat in omgekeerde volgorde. enabledWhen maakt een component afhankelijk van een optie of rol, bijvoorbeeld opt.seed, !opt.seed of repo.web. Een component waarvan de rol optioneel is en ontbreekt in de ruimte, wordt op dezelfde manier overgeslagen, zonder dat enabledWhen nodig is: het start niet en heeft geen {port.*} of {url.*}, dus een ander component dat die leest laat de start mislukken.
| Soort | Wie het uitvoert | Waarvoor |
|---|---|---|
compose |
De compose-driver van Control Center | Elk compose-bestand, één per omgeving |
cli |
Jouw tool. Control Center roept gekoppelde werkwoorden aan en leest JSON | Een tool die zelf zijn levenscyclus, domeinen en data beheert |
process |
Control Center, in een bewaakte terminalsessie | Dev-servers en workers |
task |
Control Center, één keer per trigger | Installaties, migraties, tests |
app |
Control Center, als iemand op Openen klikt | Een desktop-app |
task-componenten krijgen een when-lijst:
| Trigger | Draait |
|---|---|
provision |
Als de worktree wordt gemaakt (zie worktree-taken hieronder) |
create |
Eén keer per omgeving, en opnieuw na een reset |
start |
Bij elke start |
change |
Na een synchronisatie, als een gewijzigd pad overeenkomt met onChange |
manual |
Op verzoek: Uitvoeren, cc-env run <id> of environment_run_task |
archive |
Vlak voordat de worktree wordt vernietigd |
Een task zonder iets te doen bij een start toont Inactief en staat niet in de lijst met stappen die worden getoond terwijl de omgeving start: een manual- of change-task, of een create-task die al is uitgevoerd.
Een opdracht als array is argv, dus optiewaarden gaan nooit door een shell. Een string, of script met een array van regels, draait onder bash -lc. Plaatshouders als {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} en {url.<role>} worden alleen in argv ingevuld. Shell-opdrachten lezen dezelfde waarden als CC_ENV_*-variabelen, zoals $CC_ENV_PORT_WEB. Een onbekende plaatshouder in een component dat meedoet, stopt de start voordat er iets wordt uitgevoerd.
Elke opdracht en ruimteterminal krijgt ook CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> en, in PR-ruimtes, CC_PR_NUMBER en CC_PR_IS_FORK. Met een compose-component komen daar COMPOSE_PROJECT_NAME en COMPOSE_FILE bij, zodat docker compose exec in een taak het juiste project bereikt.
Rollen en werkmap
Sectie getiteld “Rollen en werkmap”Een definitie koppelt rollen aan repo’s van de werkruimte, zodat één stack meerdere repo’s kan omvatten:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: een ruimte kan de omgeving starten als ze minstens één ankerrol bevat. Passen twee definities, dan kiest degene die start.required: de stack kan niet draaien zonder deze repo.whenMissing: wat er gebeurt als de ruimte de rol mist.addToSpacevoegt de repo toe op zijn standaardbranch en is de standaard voorrequired-rollen.useSourcegeeft je geregistreerde checkout door, die je als alleen-lezen behandelt.skiplaat de variabele leeg en is verder de standaard.- Starten vereist een
write-recht op een ankerrepo in de ruimte en leestoegang tot elke andere gekoppelde repo.
Een opdracht draait in de eerste rol die in repos is gedeclareerd, nooit in een andere rol die de ruimte toevallig heeft, dus een definitie met één repo noemt dit nooit. Elk component kan dat overschrijven met "cwd": { "role": "e2e", "path": "packages/ui" }. Beide velden zijn optioneel. Als de eerste rol in een ruimte zou kunnen ontbreken, omdat die niet required is en ook niet het enige anker is, moet elk component zijn rol noemen.
Poorten en URL’s
Sectie getiteld “Poorten en URL’s”Control Center wijst hostpoorten toe voordat er iets start, uit een bereik voor de hele host (standaard 42000 tot en met 49999, in blokken van 32). Een poort blijft gelijk zolang de omgeving bestaat, en compose-poorten binden alleen aan 127.0.0.1.
- Compose-poorten hoef je niet te declareren. Lees ze als
{port.postgres.5432}ofCC_ENV_PORT_POSTGRES_5432. - Andere poorten declareer je waar ze worden gebruikt, met
"port": "web"of"ports": ["web", "hmr"], en lees je als{port.web}. Een proces met een poort krijgt ookPORTenHOST=127.0.0.1.
HTTP-eindpunten krijgen een URL op de router van de server, die op één loopbackpoort luistert:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>is de branch als slug, ofpr-<n>in een PR-ruimte.<project>isnaming.project, of anders de naam van de definitie.*.localhost-namen wijzen naar loopback, dus ze hebben geen hosts-regels of DNS nodig, en de hostnaam houdt cookies tussen omgevingen gescheiden.- Compose-poorten die HTTP spreken worden herkend, en
httpop het component overschrijft die gok. Een proces heeft"endpoint": { "role": "web", "primary": true }nodig, wat ook{url.web}beschikbaar maakt. - Gebruik in de browser (VM) Openen in Browser (VM).
https://web--fix-login--shop.localhost/bereikt daar dezelfde route. - Het hele label blijft binnen 63 tekens, dus lange namen worden met een hash ingekort.
- Twee eindpunten delen geen bovenliggend domein. Een app die één cookie voor beide nodig heeft, moet ze vanaf één eindpunt serveren.
Voor URL’s die je vooraf moet registreren, zoals OAuth-redirects, geeft "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } een vaste set namen.
policy bepaalt wanneer omgevingen draaien. autoCreate is off, prSpaces of allSpaces, idleStopMinutes is standaard 240, followPrHead synchroniseert een PR-omgeving als de head verschuift, en door maxRunning (standaard 6) biedt Starten aan de minst recent gebruikte omgeving te stoppen.
Voorbeeld: compose-app
Sectie getiteld “Voorbeeld: compose-app”Een webapp en Postgres uit één compose-bestand, met een door git genegeerde .env, migraties en een testtaak. seedFiles kopieert benoemde bestanden uit je geregistreerde checkout naar elke nieuwe 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" } ]}Met healthchecks kan een service zonder eigen healthcheck het volgende component tegenhouden. Zonder healthcheck telt een draaiende container als klaar, en kunnen migraties een database inhalen die nog opstart.
Elke start en elke vernieuwing voert up uit met --remove-orphans, zodat een service die uit het compose-bestand is verwijderd stopt en zijn poort vrijgeeft. Images worden bij de start en bij het vernieuwen gebouwd, tenzij het component "build": false instelt.
Voorbeeld: eigen CLI
Sectie getiteld “Voorbeeld: eigen CLI”Een verzonnen tool acme die zelf zijn containers, domeinen en TLS beheert. Control Center levert {name} en haalt de rest uit status. Het leidt nooit de hostnamen van een tool af en bewerkt nooit /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,statusendestroyzijn verplicht. Control Center kiestcreateofstartop basis van de status die het leest. Elk werkwoord mag{ "shell": "…" }zijn in plaats van argv.interactivenoemt de werkwoorden uitcreate,startenresetdie op een terminal kunnen vragen wat ze nodig hebben. Wanneer zo’n werkwoord eindigt met code 3 voor een persoon die op Starten heeft geklikt, voert Control Center hetzelfde werkwoord opnieuw uit in een terminaltabblad, en gaat de start verder zodra het met 0 eindigt. Daar is de voorwaardeinteractivewaar en isCC_ENV_INTERACTIVE=1ingesteld, zodat{ "if": "!interactive", "args": ["--json"] }de machine-uitvoer voor de niet-interactieve uitvoering behoudt. Een start door een agent, of een automatische start, opent nooit een terminal: de omgeving toont Actie nodig en wacht.- Een
destroydie mislukt, verwijdert de omgeving toch wanneerstatusdaarnamissingmeldt, zodat een omgeving die het tool niet meer heeft altijd kan worden verwijderd. listlaat Control Center een omgeving opmerken die de tool is kwijtgeraakt. Ze wordt pas als verdwenen gemarkeerd wanneer haar naam ontbreekt inlistenstatusdanmissingzegt. Uitvoer die niet als lijst gelezen kan worden, verandert niets.{service}inlogsenexecmoet één woord zijn dat niet met-begint, en een van de services die de tool het laatst heeft gemeld, wanneer het er gemeld heeft.statusMapleest de eigen JSON van de tool met JSON-pointers, waarbij*op elk item past. Statusregels zijn geordend en de eerste match wint. Een voorwaarde ispathmetequals, ofanyofnonemetwhere.keepsDataOnStop: falseschakelt stoppen bij inactiviteit uit en voegt een waarschuwing voor gegevensverlies toe aan Stoppen. Gebruik het als stoppen data kost.routing.mode: "tool"koppelt de hostnamen van de tool aan de browser (VM) en aan agents. Het domein moet eindigen op.test,.localhostof.internal, en een gemelde URL daarbuiten wordt genegeerd.
Een tool van jezelf kan statusMap overslaan en het statuscontract printen dat onderaan deze pagina staat.
Voorbeeld: pnpm-monorepo
Sectie getiteld “Voorbeeld: pnpm-monorepo”Alleen processen en taken, geen containers. De webapp vindt de API via {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"] } ]}- Elk proces is een terminaltabblad dat je kunt openen, lezen en waarin je kunt typen, als je schrijfrechten hebt op elke repository in de ruimte (zie Wie wat kan opslaan). Het tabblad sluiten stopt het proces niet.
readyneemthttp(een volledige URL),tcp(host:port) oflogMatch(een reguliere expressie).restartison-failure(de standaard),alwaysofnever.restartOnherstart het proces als een gewijzigd pad overeenkomt.optionsworden een formulier bij Starten, enagentDefaultgeldt voor runs die een agent start.
Voorbeeld: desktop-app
Sectie getiteld “Voorbeeld: desktop-app”Een desktop-app met een buildstap. Een app werkt hetzelfde waarmee hij ook is gebouwd, want Control Center werkt op het niveau van besturingssysteemvensters en heeft geen hook of SDK in de app nodig.
{ "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" } ]}Een app start niet met de omgeving mee. Iemand klikt op Openen, en prepare draait eerst. Opnieuw bouwen en openen voert dat paar opnieuw uit. enabledWhen geldt voor de app en voor de prepare-taak, en Openen wordt geweigerd zolang een van beide uit staat. Een app telt als draaiend zolang een proces in de procesgroep ervan draait, dus een launcher die de app start en daarna afsluit, is prima. Als alles binnen ongeveer 5 seconden na Openen verdwenen is, toont de app een fout met de laatste logregels. Daarna toont een nette afsluiting als gesloten en toont een crash de laatste logregels, en geen van beide herstart de app. Een herstart van de server sluit de app en start hem nooit opnieuw, en stoppen bij inactiviteit laat een draaiende app met rust.
Rechten en beperkingen van desktop-apps
Sectie getiteld “Rechten en beperkingen van desktop-apps”- Geef Control Center op macOS eenmalig Schermopname en Toegankelijkheid in Systeeminstellingen. De serverhost heeft een GUI-sessie nodig: een headless server weigert een app te starten.
- Start de binary rechtstreeks.
open -ageeft de app aan LaunchServices en die verlaat dan de procesboom die Control Center volgt, zodat de app direct na de start als mislukt wordt getoond. - Vensters blijven op een scherm. macOS legt geen venster vast dat buiten alle schermen staat, dus een app die een agent gebruikt is zichtbaar op het scherm van de server. Focus is niet nodig.
"isolate": "home"geeft de app een privé-thuismap viaHOME,XDG_*enCFFIXED_USER_HOME, zodat kopieën uit twee ruimtes naast elkaar kunnen draaien.NSUserDefaultsis niet geïsoleerd, dus Cocoa-voorkeuren en Fluttersshared_preferencesblijven gedeeld tussen kopieën.isolategeldt alleen voor het gestarte proces. Een toolchain-launcher alsflutter runheeft de echte thuismap nodig, dus combineerisolatemet een gebouwde binary. Heeft de app een eigen instelling, zoals--user-data-dir, gebruik die dan liever.- Agents besturen het venster met
app_use, dat alleen de procesboom van deze omgeving kan bereiken. Een agent ziet het venster, niet het bureaublad. Starts door agents gaan via het actiebeleid en vragen standaard om bevestiging, en agentinvoer stopt zolang een persoon de besturing heeft. "input": "background"(de standaard) stuurt gebeurtenissen naar het proces."foreground"activeert het venster en neemt de cursor over.
Worktree-taken
Sectie getiteld “Worktree-taken”provision- en archive-taken voeren het setup- en opruimwerk van een repo uit met zijn worktree. Het pictogram in de rij van een repo onder Instellingen → Werkruimte → Repository’s opent de definitie van de repo.
Deze taken volgen de worktree, niet de omgeving, dus ze draaien ook in ruimtes waar niemand op Starten klikt:
provision |
archive |
|
|---|---|---|
| Draait | Als de worktree van de rol wordt gemaakt, in elke ruimte | Vlak voordat die worktree wordt vernietigd |
| Bij een fout | De voorbereiding mislukt en de worktree wordt vernietigd | Vastgelegd, blokkeert verwijderen nooit |
| Standaardtime-out | 5 minuten | 2 minuten |
| Ziet | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Hetzelfde |
Een repo zonder stack heeft alleen een definitie met zijn taken nodig. Omdat er niets te starten valt, is geen ankerrol nodig:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Er is nog geen omgeving, dus deze taken kunnen
{name},{port.*},{url.*},{opt.*}enenabledWhenniet gebruiken, en ze krijgen deenvvan de definitie niet. - Slechts één definitie mag
provision- enarchive-taken voor een repo bevatten. Andere mogen de repo voor al het overige wel koppelen. "when": ["provision", "change"]installeert ook opnieuw als een lockfile verandert.- Een taak draait voor de worktree van zijn
cwd-rol, dus een definitie met meerdere repo’s kan elke repo apart inrichten. - Een testrun zet
CC_SCRIPT_TEST=1. Een nieuwe poging begint met een schone worktree, dus schrijf taken die opnieuw uitvoeren overleven.
Agents
Sectie getiteld “Agents”Agents krijgen nooit de Docker-socket. In een ruimte met een geschikte definitie krijgt een run cc-env op zijn PATH. De ruimte komt uit de run, dus een agent kan alleen op zijn eigen omgeving handelen, en elke opdracht gaat via het actiebeleid.
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>Met een compose-component staat een docker-shim ook docker compose toe met ps, logs, exec, port, restart en top, en alleen tegen het eigen compose-project van deze omgeving. Voor het werkwoord mogen geen vlaggen staan, en elk werkwoord accepteert een korte lijst opties: logs kan niet volgen en exec accepteert alleen -T (of --no-tty). Opties die compose naar een ander bestand of project laten wijzen (-f, -p, --project-directory, --env-file, --profile) worden geweigerd, waar ze ook staan. Al het andere eindigt met code 5 en “not available in Control Center agent runs”.
Een repo waarvan de skills zijn eigen tool aanroepen, kan dat blijven doen. Een agentPassthrough-blok op een cli-component legt vast welke opdrachten agents mogen uitvoeren. Alleen opdrachten die de goedgekeurde definitie declareert, worden doorgegeven, en elk draait op de host, dus hij valt onder de regel Opdrachten uitvoeren op de host, die standaard eerst vraagt:
"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 noemt de bewerking waarvan het beleid geldt. positionalName dwingt dat argument naar de omgeving van deze ruimte, nameFilter filtert JSON-uitvoer daarop en elke pathFlags-waarde moet binnen de worktrees van de run uitkomen. Een opdracht die op geen regel past, eindigt met code 5.
Dezelfde bewerkingen bestaan als tools: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app en environment_stop_app. Agents in een sandbox bereiken hun poorten rechtstreeks en de hostnamen van hun omgeving via de proxy van de run, dus laat ze eindpunten uit environment_status lezen in plaats van een URL te raden.
Pull requests vanuit forks
Sectie getiteld “Pull requests vanuit forks”De code van een fork-PR is niet vertrouwd, en bij hostplaatsing draait die als de OS-gebruiker van de server. policy.forkPrs bepaalt wat er gebeurt:
| Waarde | Effect | Standaard voor |
|---|---|---|
rig |
Het compose-bestand draait zonder vraag in een VM | Definities met alleen compose- en task-componenten |
approval |
Elke start vereist een beheerder | Alle andere definities |
deny |
Geweigerd | Geen |
seedFilesworden nooit gekopieerd voor een fork, omdat het meestal geheimen zijn. Een compose-bestand dat er een koppelt, meldt het ontbrekende bestand bij naam.provision- enarchive-taken worden overgeslagen, tenzij het beleidrigis: dan draaien ze in de VM.- Bij hostplaatsing worden
privileged, hostnamespaces, een Docker-socketbind,devicesen binds buiten de worktrees van de ruimte op een fork geweigerd. In vertrouwde ruimtes geven ze alleen een waarschuwing.
Rig-plaatsing
Sectie getiteld “Rig-plaatsing”"placement": "rig" draait compose- en task-componenten in een eigen microVM. Definities met process-, cli- of app-componenten komen niet in aanmerking. Het compose-bestand draait ongewijzigd, zonder Docker-socket van de host en zonder inloggegevens van de beheerder, en netwerktoegang is beperkt tot de registers die de images nodig hebben. De worktree wordt live gekoppeld.
- arm64-gasten. Gasten zijn arm64 op Apple Silicon, dus images die alleen amd64 ondersteunen draaien niet.
- Privéregisters worden geweigerd. Gasten hebben geen registerinloggegevens, dus een image op een register buiten de bekende openbare wordt geweigerd voordat de VM opstart. Een privérepository op een openbaar register mislukt als de gast het ophaalt.
- 16 GiB opslag. Alle images en volumes van de stack delen één schijf van 16 GiB, en die kan niet groter.
- De eerste start is traag. Imagelagen zijn per VM, dus de eerste start haalt alles op. Een gestopte rig houdt zijn schijf.
- Basisimages moeten leesbaar zijn. Een Dockerfile die zijn basisimage via een variabele noemt, kan niet worden gepland, omdat netwerktoegang bij het opstarten vastligt.
- Levensduur.
policy.rigTtlHoursbeëindigt de VM, standaard na 24 uur.
Statuscontract voor toolmakers
Sectie getiteld “Statuscontract voor toolmakers”Een cli-component zonder statusMap verwacht het native contract, cc-env/1. Het werkwoord status print dit object op 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": "…" }}stateisready,starting,stopped,failedofmissing.missingleidt totcreate,stoppedenfailedleiden totstart. Meldmissingmet exitcode 0: een misluktestatustelt alsfailed.- Alleen
stateis nodig. Onbekende velden worden genegeerd, en uitvoer die niet te lezen is verschijnt als gedegradeerd, met de ruwe tekst als detail. - Een URL moet loopback,
*.localhostof onderrouting.domainzijn, anders wordt hij genegeerd. needsRecreate: truetoont Opnieuw maken, wat data weggooit. Control Center handelt hier nooit zelf op.- Het werkwoord
listprint een JSON-array van namen, of van objecten met eenname.
Exitcodes gelden voor elk werkwoord:
| Code | Betekenis |
|---|---|
| 0 | OK |
| 3 | Er is een antwoord nodig in een terminal, zoals een sudo-wachtwoord. Een werkwoord dat in interactive staat, wordt opnieuw uitgevoerd in een terminaltabblad voor de persoon die op Starten heeft geklikt. Anders opent Uitvoeren in terminal een ruimteterminal met de command van de tool getypt maar niet uitgevoerd, daarna probeert Opnieuw proberen het opnieuw. Control Center voert nooit sudo uit en beantwoordt nooit een prompt |
| 4 | Aanmelding vereist. De command van de tool geeft aan hoe |
| 5 | Iets waarvan het afhankelijk is, is niet beschikbaar, zoals een containerruntime die niet draait |
| Anders | Fout |
Codes 3, 4 en 5 zijn geen fouten. De omgeving toont Actie nodig en wacht, en de volgende start pakt op waar die gestopt is. Een taak die met een van die codes eindigt, betekent hetzelfde.
Voortgang gaat naar stderr als JSON per regel:
{"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"}Terwijl een omgeving start, toont het paneel de onderdelen die de start doorloopt, elk met een spinner, een vinkje of een kruisje. Een step-regel laat zien wat het tool nu doet, en de label verschijnt onder de eigen rij van het tool; stappen voegen nooit rijen toe. De state van een stap is pending, running, done of failed, en een stap zonder state geldt als lopend. Een stap die zich opnieuw meldt onder dezelfde id (een tekst of een getal, of dezelfde label zonder een), vervangt wat die eerder zei, zodat een tool met één spinner één id kan houden en de label kan wijzigen. Zonder ids volgen stappen elkaar op: een nieuwe beëindigt de vorige. Wanneer het commando eindigt, eindigt een stap die nog loopt zoals het commando is geëindigd.
Een log-regel bevat één regel uitvoer die het tool in JSON heeft verpakt, en wordt gelezen als gewone uitvoer. Een note-regel gaat naar de uitvoer van de run, en een regel met "level": "warn" blijft ook op de omgeving staan als waarschuwing. Een laatste regel van het type error wordt een gestructureerde fout, met command om te kopiëren, en de laatste 12 regels uitvoer staan onder de message. Zonder die regel toont Control Center de laatste 20 stderr-regels. Alles wat geen JSON is, is gewone loguitvoer.