Zum Inhalt springen

Environments einrichten

Ein Environment ist der laufende Stack eines Bereichs: die Dienste, die ein Branch braucht, isoliert von allen anderen Bereichen, sichtbar in der Seitenleiste und für Agenten erreichbar. Auch Pull Requests bekommen eines, denn ein PR hat bereits seinen eigenen Bereich.

Ein Admin des Arbeitsbereichs schreibt einmal eine Definition. Mitglieder klicken dann im Abschnitt Environment der Seitenleiste eines Bereichs oder PRs auf Starten. Definitionen liegen in der Datenbank des Arbeitsbereichs, ein Feature-Branch ändert also nie, was Control Center ausführt. Die Tools führen aber weiterhin den Code dieses Branches aus.

  1. Öffne Einstellungen → Arbeitsbereich → Environments. Nur Admins des Arbeitsbereichs können Definitionen ändern, und nur der Serverinhaber kann eine speichern, die auf dem Server-Host läuft (siehe Wer darf was speichern).
  2. Klicke auf Neue Definition und dann auf Leere Definition oder Aus Repo entwerfen. Ein Entwurf durchsucht das Repo nach Compose-Dateien, einem Procfile und package.json-Skripten, und du prüfst das Ergebnis.
  3. Fülle das Formular aus oder nutze den Tab JSON. Die Beispiele auf dieser Seite zeigen dieses JSON.
  4. Klicke auf Test ausführen. Das startet ein Wegwerf-Environment, wartet, bis es bereit ist, und zerstört es wieder.

Speichern prüft eine Definition streng. Ein unbekanntes Feld, ein Wert mit falschem Typ oder eine falsch geschriebene Auswahl wird abgelehnt, mit Pfad und dem nächstliegenden gültigen Namen, etwa repos.app.requird: Unknown field. Did you mean "required"?. Ein $schema auf oberster Ebene ist erlaubt.

Um eine Definition in einem Repo zu pflegen, nutze Repo-Datei verknüpfen. Control Center liest die Datei nur vom Standardbranch und führt nur die Version aus, die freigegeben wurde: von einem Admin des Arbeitsbereichs oder, wenn die Definition auf dem Host läuft, vom Serverinhaber. Eine neuere Version zeigt Update verfügbar und ändert bis zur Freigabe nichts.

Eine Environment-Definition kann Befehle auf dem Server-Host als dessen eigener Benutzer ausführen. Das ist die Entscheidung des Serverinhabers, nicht einer Arbeitsbereichsrolle:

  • Eine Definition läuft auf dem Host, wenn sie Host-Platzierung hat, eine Prüfung, die einen Befehl ausführt, oder eine Aufgabe provision oder archive. Diese Aufgaben laufen auf dem Host im Worktree des Bereichs, unabhängig von der Platzierung.
  • Nur der Serverinhaber kann eine Definition speichern oder genehmigen, die auf dem Host läuft. Dazu gehört auch die Genehmigung einer neuen Version einer verknüpften Repo-Datei. Ein Admin des Arbeitsbereichs, der es versucht, sieht „Nur der Serverinhaber kann eine Umgebung speichern oder genehmigen, die auf dem Server-Host läuft. Ein Workspace-Admin kann eine nutzen, die in einem Rig läuft.“
  • Ein Admin des Arbeitsbereichs kann eine Definition speichern und genehmigen, die vollständig in einem Rig läuft: "placement": "rig", ohne Prüfbefehl und ohne Aufgabe provision oder archive.
  • Mitglieder starten, stoppen und nutzen Environments in beiden Fällen.
  • Eine Definition, die auf dem Host läuft, läuft erst, nachdem der aktuelle Serverinhaber sie gespeichert oder genehmigt hat. Der Server hält diese Genehmigung selbst fest und prüft sie vor jedem Start, jeder Prüfung, jeder Aufgabe und jedem Abgleich des PR-Heads. Eine Definition, die der aktuelle Inhaber nicht genehmigt hat, etwa eine, die ein früherer Inhaber gespeichert hat, wartet unter ihrer Zeile in der Environment-Liste und im Editor. Der Serverinhaber sieht „Läuft auf diesem Server. Genehmige sie, damit sie starten kann.“ mit Genehmigen, was die Definition unverändert speichert; alle anderen sehen „Läuft auf diesem Server. Der Serverinhaber muss sie genehmigen, bevor sie starten kann.“
  • Eine Environment, die auf diese Genehmigung wartet, zeigt „Der Serverinhaber hat diese Umgebung noch nicht genehmigt, daher kann sie auf diesem Server nicht laufen.“ Der Serverinhaber sieht stattdessen „Du hast diese Umgebung noch nicht genehmigt. Sie läuft auf diesem Server und startet, sobald du ihre Definition genehmigst.“ mit Prüfen und genehmigen, was die Definition öffnet.
  • Prozess-Terminals einer Environment und das Terminal, das ein Start öffnet, wenn er dich braucht, laufen auf dem Server-Host. Tippen, Größe ändern oder Schließen braucht Schreibzugriff auf jedes Repository, das der Bereich freigibt und das über deine eigene Forge-Anmeldung lesbar ist; das gilt wie beim Starten der Environment. Alle anderen erreichen diese Terminals gar nicht.

Ein einfaches Compose-Repo braucht nur das:

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

Alles andere hat einen Standardwert: Die Compose-Datei wird gefunden, jeder Dienst läuft, Ports werden zugewiesen, HTTP-Endpunkte werden erkannt, und das Environment heißt wie der Branch.

Ein Environment ist eine geordnete Liste von Komponenten. Jede wartet, bis die vorherige bereit ist, sofern after keine anderen nennt, und das Stoppen läuft umgekehrt. enabledWhen macht eine Komponente von einer Option oder Rolle abhängig, zum Beispiel opt.seed, !opt.seed oder repo.web. Eine Komponente, deren Rolle optional und im Bereich nicht vorhanden ist, wird genauso ausgelassen, ohne dass enabledWhen nötig ist: Sie startet nicht und hat weder {port.*} noch {url.*}, sodass eine andere Komponente, die diese liest, den Start scheitern lässt.

Art Wer sie ausführt Wofür
compose Der Compose-Treiber von Control Center Jede Compose-Datei, eine pro Environment
cli Dein Tool. Control Center ruft zugeordnete Verben auf und liest JSON Ein Tool, dem Lebenszyklus, Domains und Daten gehören
process Control Center, in einer überwachten Terminalsitzung Dev-Server und Worker
task Control Center, einmal pro Auslöser Installationen, Migrationen, Tests
app Control Center, wenn jemand auf Starten klickt Eine Desktop-App

task-Komponenten nehmen eine when-Liste:

Auslöser Läuft
provision Wenn der Worktree erstellt wird (siehe Worktree-Tasks unten)
create Einmal pro Environment und erneut nach einem Zurücksetzen
start Bei jedem Start
change Nach einem Sync, wenn ein geänderter Pfad zu onChange passt
manual Auf Anfrage: Ausführen, cc-env run <id> oder environment_run_task
archive Kurz bevor der Worktree zerstört wird

Eine Task, die beim Start nichts zu tun hat, zeigt Inaktiv und fehlt in der Liste der Schritte, die angezeigt werden, während die Environment startet: eine manual- oder change-Task oder eine create-Task, die bereits gelaufen ist.

Ein als Array angegebener Befehl ist argv, Optionswerte laufen also nie durch eine Shell. Ein String oder script mit einem Array von Zeilen läuft unter bash -lc. Platzhalter wie {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} und {url.<role>} werden nur in argv aufgelöst. Shell-Befehle lesen dieselben Werte als CC_ENV_*-Variablen, etwa $CC_ENV_PORT_WEB. Ein unbekannter Platzhalter in einer beteiligten Komponente stoppt den Start, bevor etwas ausgeführt wird.

Jeder Befehl und jedes Bereichsterminal bekommt außerdem CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> und in PR-Bereichen CC_PR_NUMBER und CC_PR_IS_FORK. Mit einer Compose-Komponente kommen COMPOSE_PROJECT_NAME und COMPOSE_FILE dazu, sodass docker compose exec in einem Task das richtige Projekt erreicht.

Eine Definition bindet Rollen an Repos des Arbeitsbereichs, sodass ein Stack mehrere Repos umfassen kann:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: Ein Bereich kann das Environment starten, wenn er mindestens eine Anker-Rolle enthält. Passen zwei Definitionen, wählt die Person, die startet.
  • required: Der Stack läuft ohne dieses Repo nicht.
  • whenMissing: Was passiert, wenn dem Bereich die Rolle fehlt. addToSpace fügt das Repo auf seinem Standardbranch hinzu und ist der Standard für required-Rollen. useSource übergibt deinen registrierten Checkout, den du als schreibgeschützt behandeln solltest. skip lässt die Variable leer und ist sonst der Standard.
  • Zum Starten brauchst du eine write-Berechtigung auf einem Anker-Repo im Bereich und Lesezugriff auf jedes andere gebundene Repo.

Ein Befehl läuft in der ersten in repos deklarierten Rolle, nie in einer anderen Rolle, die der Bereich zufällig hat, eine Definition mit einem Repo erwähnt das also nie. Jede Komponente kann das mit "cwd": { "role": "e2e", "path": "packages/ui" } überschreiben. Beide Felder sind optional. Wenn die erste Rolle in einem Bereich fehlen könnte, weil sie weder required noch der einzige Anker ist, muss jede Komponente ihre Rolle nennen.

Control Center weist Host-Ports zu, bevor etwas startet, aus einem hostweiten Bereich (standardmäßig 42000 bis 49999, in Blöcken von 32). Ein Port bleibt für die Lebensdauer des Environments gleich, und Compose-Ports binden nur an 127.0.0.1.

  • Compose-Ports müssen nicht deklariert werden. Lies sie als {port.postgres.5432} oder CC_ENV_PORT_POSTGRES_5432.
  • Andere Ports werden dort deklariert, wo sie gebraucht werden, mit "port": "web" oder "ports": ["web", "hmr"], und als {port.web} gelesen. Ein Prozess mit Port bekommt außerdem PORT und HOST=127.0.0.1.

HTTP-Endpunkte bekommen eine URL auf dem Router des Servers, der auf einem Loopback-Port lauscht:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> ist der Branch als Slug oder pr-<n> in einem PR-Bereich. <project> ist naming.project, sonst der Name der Definition.
  • *.localhost-Namen zeigen auf Loopback, sie brauchen also weder Hosts-Einträge noch DNS, und der Hostname hält Cookies zwischen Environments getrennt.
  • Compose-Ports, die HTTP sprechen, werden erkannt, und http an der Komponente überschreibt die Vermutung. Ein Prozess braucht "endpoint": { "role": "web", "primary": true }, das auch {url.web} verfügbar macht.
  • Im Browser (VM) nutze Im Browser (VM) öffnen. https://web--fix-login--shop.localhost/ erreicht dort dieselbe Route.
  • Das gesamte Label bleibt innerhalb von 63 Zeichen, lange Namen werden also mit einem Hash gekürzt.
  • Zwei Endpunkte teilen keine übergeordnete Domain. Eine App, die ein Cookie über beide braucht, muss sie von einem Endpunkt ausliefern.

Für URLs, die du vorab registrieren musst, etwa OAuth-Redirects, liefert "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } eine feste Menge von Namen.

policy legt fest, wann Environments laufen. autoCreate ist off, prSpaces oder allSpaces, idleStopMinutes ist standardmäßig 240, followPrHead synchronisiert ein PR-Environment, wenn sich sein Head bewegt, und bei maxRunning (Standard 6) bietet Starten an, das am längsten ungenutzte Environment zu stoppen.

Eine Web-App und Postgres aus einer Compose-Datei, mit einer gitignorierten .env, Migrationen und einem Test-Task. seedFiles kopiert benannte Dateien aus deinem registrierten Checkout in jeden neuen 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" }
]
}

Mit healthchecks kann auch ein Dienst ohne eigenen Healthcheck die nächste Komponente aufhalten. Ohne ihn gilt ein laufender Container als bereit, und Migrationen können einer noch startenden Datenbank zuvorkommen.

Jeder Start und jede Aktualisierung führt up mit --remove-orphans aus, sodass ein Dienst, der aus der Compose-Datei entfernt wurde, stoppt und seinen Port freigibt. Images werden beim Start und bei der Aktualisierung gebaut, außer die Komponente setzt "build": false.

Ein erfundenes Tool acme, dem seine Container, Domains und TLS gehören. Control Center liefert {name} und erfährt alles andere aus status. Es leitet nie die Hostnamen eines Tools ab und bearbeitet nie /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 und destroy sind Pflicht. Control Center wählt create oder start anhand des gelesenen Status. Jedes Verb kann statt argv auch { "shell": "…" } sein.
  • interactive nennt die Verben aus create, start und reset, die ihre benötigten Angaben an einem Terminal erfragen können. Beendet sich ein solches Verb mit Code 3 für eine Person, die Starten gedrückt hat, führt Control Center dasselbe Verb erneut in einem Terminal-Tab aus, und der Start läuft weiter, sobald es mit 0 endet. Dort ist die Bedingung interactive wahr und CC_ENV_INTERACTIVE=1 gesetzt, sodass { "if": "!interactive", "args": ["--json"] } die maschinelle Ausgabe für die nicht interaktive Ausführung beibehält. Ein Start durch einen Agenten oder ein automatischer Start öffnet nie ein Terminal: Die Environment zeigt Aktion nötig und wartet.
  • Ein destroy, das fehlschlägt, entfernt die Environment trotzdem, wenn status danach missing meldet, sodass eine Environment, die das Tool nicht mehr hat, immer entfernt werden kann.
  • list lässt Control Center eine Environment bemerken, die das Tool verloren hat. Sie gilt nur dann als verschwunden, wenn ihr Name in list fehlt und status dann missing meldet. Ausgabe, die sich nicht als Liste lesen lässt, ändert nichts.
  • {service} in logs und exec muss ein einzelnes Wort sein, das nicht mit - beginnt, und einer der Dienste, die das Tool zuletzt gemeldet hat, sofern es welche gemeldet hat.
  • statusMap liest das eigene JSON des Tools mit JSON-Pointern, wobei * auf jedes Element passt. Zustandsregeln sind geordnet, und der erste Treffer gewinnt. Eine Bedingung ist path mit equals oder any bzw. none mit where.
  • keepsDataOnStop: false schaltet den Leerlauf-Stopp aus und ergänzt Stoppen um eine Warnung vor Datenverlust. Setze es, wenn beim Stoppen Daten verloren gehen.
  • routing.mode: "tool" verbindet die Hostnamen des Tools mit dem Browser (VM) und mit Agenten. Die Domain muss auf .test, .localhost oder .internal enden, und eine gemeldete URL außerhalb davon wird verworfen.

Ein Tool, das dir gehört, kann statusMap weglassen und den Statusvertrag ausgeben, der am Ende dieser Seite beschrieben ist.

Nur Prozesse und Tasks, keine Container. Die Web-App findet die API über {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"] }
]
}
  • Jeder Prozess ist ein Terminal-Tab, den du öffnen, lesen und in den du tippen kannst, wenn du Schreibzugriff auf jedes Repository im Bereich hast (siehe Wer darf was speichern). Das Schließen des Tabs stoppt ihn nicht.
  • ready nimmt http (eine vollständige URL), tcp (host:port) oder logMatch (ein regulärer Ausdruck). restart ist on-failure (der Standard), always oder never. restartOn startet den Prozess neu, wenn ein geänderter Pfad passt.
  • options werden zu einem Formular bei Starten, und agentDefault gilt für Läufe, die ein Agent startet.

Eine Desktop-App mit Build-Schritt. Eine App funktioniert gleich, egal womit sie gebaut ist, denn Control Center arbeitet auf Ebene der Betriebssystemfenster und braucht keinen Hook und kein SDK in der App.

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

Eine App startet nicht mit dem Environment. Jemand klickt auf Starten, und prepare läuft zuerst. Neu bauen und starten führt dieses Paar erneut aus. enabledWhen gilt für die App und ihre prepare-Aufgabe, und Starten wird abgelehnt, solange eines von beiden deaktiviert ist. Eine App gilt als laufend, solange ein Prozess ihrer Prozessgruppe läuft, sodass ein Starter, der die App startet und sich dann beendet, in Ordnung ist. Ist innerhalb von etwa 5 Sekunden nach Starten alles verschwunden, zeigt die App einen Fehler mit ihren letzten Logzeilen. Danach wird ein sauberes Beenden als geschlossen angezeigt und ein Absturz zeigt die letzten Logzeilen, und keines von beiden startet sie neu. Ein Serverneustart schließt die App und startet sie nie neu, und der Leerlauf-Stopp lässt eine laufende App in Ruhe.

  • Gib Control Center unter macOS einmalig in den Systemeinstellungen die Rechte Bildschirmaufnahme und Bedienungshilfen. Der Server-Host braucht eine GUI-Sitzung: Ein Headless-Server verweigert den App-Start.
  • Starte die Binärdatei direkt. open -a übergibt die App an LaunchServices, und sie verlässt den Prozessbaum, den Control Center verfolgt, sodass die App direkt nach dem Start einen Fehler anzeigt.
  • Fenster bleiben auf einem Display. macOS erfasst kein Fenster, das außerhalb aller Displays liegt, eine von einem Agenten genutzte App ist also auf dem Bildschirm des Servers sichtbar. Sie braucht keinen Fokus.
  • "isolate": "home" gibt der App über HOME, XDG_* und CFFIXED_USER_HOME ein privates Home, sodass Kopien aus zwei Bereichen nebeneinander laufen können. NSUserDefaults ist nicht isoliert, Cocoa-Einstellungen und Flutters shared_preferences bleiben also zwischen den Kopien geteilt.
  • isolate gilt nur für den gestarteten Prozess. Ein Toolchain-Launcher wie flutter run braucht das echte Home, kombiniere isolate also mit einer gebauten Binärdatei. Hat die App eine eigene Einstellung wie --user-data-dir, nimm lieber diese.
  • Agenten steuern das Fenster mit app_use, das nur den Prozessbaum dieses Environments erreicht. Ein Agent sieht das Fenster, nicht den Desktop. App-Starts durch Agenten laufen über die Aktionsrichtlinie und fragen standardmäßig nach, und Agenteneingaben pausieren, solange eine Person die Kontrolle hat.
  • "input": "background" (der Standard) sendet Ereignisse an den Prozess. "foreground" aktiviert das Fenster und übernimmt den Mauszeiger.

provision- und archive-Tasks führen Setup und Abbau eines Repos mit seinem Worktree aus. Das Symbol in der Zeile eines Repos unter Einstellungen → Arbeitsbereich → Repositorys öffnet die Definition des Repos.

Diese Tasks folgen dem Worktree, nicht dem Environment, und laufen also auch in Bereichen, in denen niemand auf Starten klickt:

provision archive
Läuft Wenn der Worktree der Rolle erstellt wird, in jedem Bereich Kurz bevor dieser Worktree zerstört wird
Bei Fehler Die Bereitstellung schlägt fehl und der Worktree wird zerstört Wird protokolliert, blockiert das Löschen nie
Standard-Timeout 5 Minuten 2 Minuten
Sieht CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME Dasselbe

Ein Repo ohne Stack braucht nur eine Definition mit seinen Tasks. Da es nichts zu starten gibt, ist keine Anker-Rolle nötig:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • Es gibt noch kein Environment, diese Tasks können also weder {name}, {port.*}, {url.*}, {opt.*} noch enabledWhen nutzen, und sie bekommen das env der Definition nicht.
  • Nur eine Definition darf provision- und archive-Tasks für ein Repo enthalten. Andere dürfen es für alles Weitere trotzdem binden.
  • "when": ["provision", "change"] installiert auch neu, wenn sich eine Lockfile ändert.
  • Ein Task läuft für den Worktree seiner cwd-Rolle, eine Definition mit mehreren Repos kann also jedes Repo einzeln einrichten.
  • Ein Testlauf setzt CC_SCRIPT_TEST=1. Ein erneuter Versuch beginnt mit einem sauberen Worktree, schreibe Tasks also so, dass sie eine Wiederholung überstehen.

Agenten bekommen nie den Docker-Socket. In einem Bereich mit passender Definition bekommt ein Lauf cc-env in seinen PATH. Der Bereich ergibt sich aus dem Lauf, ein Agent kann also nur auf sein eigenes Environment zugreifen, und jeder Befehl läuft über die Aktionsrichtlinie.

Terminalfenster
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>

Mit einer Compose-Komponente erlaubt ein docker-Shim außerdem docker compose mit ps, logs, exec, port, restart und top, und zwar nur gegen das eigene Compose-Projekt dieser Environment. Vor dem Verb dürfen keine Flags stehen, und jedes Verb akzeptiert eine kurze Liste von Optionen: logs kann nicht folgen, und exec akzeptiert nur -T (oder --no-tty). Optionen, die compose auf eine andere Datei oder ein anderes Projekt zeigen lassen (-f, -p, --project-directory, --env-file, --profile), werden abgelehnt, wo immer sie stehen. Alles andere endet mit Exit-Code 5 und „not available in Control Center agent runs“.

Ein Repo, dessen Skills sein eigenes Tool aufrufen, kann das weiter tun. Ein agentPassthrough-Block an einer cli-Komponente legt fest, welche Befehle Agenten ausführen dürfen. Nur Befehle, die die genehmigte Definition deklariert, werden durchgereicht, und jeder läuft auf dem Host, daher gilt für ihn die Regel Befehle auf dem Host ausführen, die standardmäßig zuerst fragt:

"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 nennt die Operation, deren Richtlinie gilt. positionalName erzwingt für dieses Argument das Environment dieses Bereichs, nameFilter filtert die JSON-Ausgabe darauf, und jeder pathFlags-Wert muss innerhalb der Worktrees des Laufs liegen. Ein Befehl, auf den keine Regel passt, endet mit Exit-Code 5.

Dieselben Operationen gibt es als Tools: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app und environment_stop_app. Sandbox-Agenten erreichen ihre Ports direkt und die Hostnamen ihres Environments über den Proxy des Laufs, weise sie also an, Endpunkte aus environment_status zu lesen, statt eine URL zu raten.

Der Code eines Fork-PRs ist nicht vertrauenswürdig, und bei Host-Platzierung läuft er als Betriebssystembenutzer des Servers. policy.forkPrs entscheidet, was passiert:

Wert Wirkung Standard für
rig Die Compose-Datei läuft ohne Rückfrage in einer VM Definitionen nur mit compose- und task-Komponenten
approval Jeder Start braucht einen Admin Alle anderen Definitionen
deny Abgelehnt Keine
  • seedFiles werden nie für einen Fork kopiert, weil sie meist Geheimnisse enthalten. Eine Compose-Datei, die eine davon einbindet, meldet die fehlende Datei beim Namen.
  • provision- und archive-Tasks werden übersprungen, außer die Richtlinie ist rig, dann laufen sie in der VM.
  • Bei Host-Platzierung werden privileged, Host-Namespaces, ein Docker-Socket-Bind, devices und Binds außerhalb der Worktrees des Bereichs auf einem Fork abgelehnt. In vertrauenswürdigen Bereichen gibt es nur eine Warnung.

"placement": "rig" führt compose- und task-Komponenten in einer eigenen microVM aus. Definitionen mit process-, cli- oder app-Komponenten kommen nicht infrage. Die Compose-Datei läuft unverändert, ohne Docker-Socket des Hosts und ohne Betreiber-Zugangsdaten, und der Netzwerkzugriff beschränkt sich auf die Registrys, die ihre Images brauchen. Der Worktree wird live eingehängt.

  • arm64-Gäste. Gäste sind auf Apple Silicon arm64, reine amd64-Images laufen also nicht.
  • Private Registrys werden abgelehnt. Gäste haben keine Registry-Zugangsdaten, ein Image auf einer Registry außerhalb der bekannten öffentlichen wird also abgelehnt, bevor die VM bootet. Ein privates Repository auf einer öffentlichen Registry scheitert, wenn der Gast es zieht.
  • 16 GiB Speicher. Alle Images und Volumes des Stacks teilen sich eine 16-GiB-Disk, und sie lässt sich nicht vergrößern.
  • Der erste Boot ist langsam. Image-Layer gelten pro VM, der erste Boot zieht also alles. Ein gestopptes Rig behält seine Disk.
  • Basis-Images müssen lesbar sein. Ein Dockerfile, das sein Basis-Image über eine Variable benennt, lässt sich nicht planen, weil der Netzwerkzugriff beim Boot feststeht.
  • Lebensdauer. policy.rigTtlHours beendet die VM, standardmäßig nach 24 Stunden.

Eine cli-Komponente ohne statusMap erwartet den nativen Vertrag cc-env/1. Das Verb status gibt dieses Objekt auf stdout aus:

{
"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 ist ready, starting, stopped, failed oder missing. missing führt zu create, stopped und failed führen zu start. Melde missing mit Exit-Code 0: Ein fehlgeschlagenes status zählt als failed.
  • Nur state ist nötig. Unbekannte Felder werden ignoriert, und nicht parsebare Ausgabe erscheint als beeinträchtigt, mit dem Rohtext als Detail.
  • Eine URL muss Loopback, *.localhost oder unter routing.domain sein, sonst wird sie verworfen.
  • needsRecreate: true zeigt Neu erstellen, was Daten verwirft. Control Center handelt nie allein deswegen.
  • Das Verb list gibt ein JSON-Array von Namen oder von Objekten mit einem name aus.

Exit-Codes gelten für jedes Verb:

Code Bedeutung
0 OK
3 Eine Antwort wird an einem Terminal benötigt, etwa ein sudo-Passwort. Ein in interactive aufgeführtes Verb läuft für die Person, die Starten gedrückt hat, erneut in einem Terminal-Tab. Andernfalls öffnet Im Terminal ausführen ein Bereichsterminal mit dem command des Tools eingetippt, aber nicht ausgeführt, danach versucht Erneut versuchen es erneut. Control Center führt nie sudo aus und beantwortet nie eine Eingabeaufforderung
4 Anmeldung nötig. Der command des Tools zeigt, wie
5 Etwas, wovon es abhängt, ist nicht verfügbar, etwa eine Container-Laufzeit, die nicht läuft
Andere Fehler

Die Codes 3, 4 und 5 sind keine Fehler. Die Environment zeigt Aktion nötig und wartet, und der nächste Start knüpft dort an, wo dieser aufgehört hat. Eine Aufgabe, die mit einem dieser Codes endet, bedeutet dasselbe.

Fortschritt geht als zeilenweises JSON an stderr:

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

Während eine Environment startet, listet das Panel die Komponenten auf, die der Start durchläuft, jede mit einem Spinner, einem Häkchen oder einem Kreuz. Eine step-Zeile zeigt, was das Tool gerade tut, und ihr label erscheint unter der eigenen Zeile des Tools; Schritte bekommen nie eine eigene Zeile. Der state eines Schritts ist pending, running, done oder failed, und ein Schritt ohne state läuft. Ein Schritt, der sich erneut unter derselben id (einer Zeichenkette oder einer Zahl, oder demselben label, wenn keine da ist) meldet, ersetzt seine bisherige Meldung, sodass ein Tool mit einem einzigen Spinner dieselbe id behalten und das label ändern kann. Ohne IDs folgen Schritte aufeinander: Ein neuer beendet den vorherigen. Wenn der Befehl endet, endet ein noch laufender Schritt so, wie der Befehl geendet hat.

Eine log-Zeile enthält eine Ausgabezeile, die das Tool in JSON verpackt hat, und wird wie normaler Ausgabetext gelesen. Eine note-Zeile geht in die Ausgabe des Laufs, und eine mit "level": "warn" bleibt außerdem als Warnung an der Environment. Eine letzte Zeile vom Typ error wird zu einem strukturierten Fehler, wobei command zum Kopieren angeboten wird, und die letzten 12 Zeilen der Ausgabe erscheinen unter ihrer message. Ohne sie zeigt Control Center die letzten 20 stderr-Zeilen. Alles, was kein JSON ist, ist normale Logausgabe.