Configurare gli ambienti
Un ambiente è lo stack in esecuzione di uno spazio: i servizi di cui ha bisogno un branch, isolati da tutti gli altri spazi, visibili nella barra laterale e raggiungibili dagli agenti. Ne ricevono uno anche le pull request, perché una PR ha già il proprio spazio.
Un amministratore dello spazio di lavoro scrive una definizione una sola volta. I membri premono poi Avvia nella sezione Ambiente della barra laterale di uno spazio o di una PR. Le definizioni risiedono nel database dello spazio di lavoro, quindi un branch di funzionalità non cambia mai ciò che Control Center esegue, anche se gli strumenti eseguono comunque il codice di quel branch.
Creare una definizione
Sezione intitolata “Creare una definizione”- Apri Impostazioni → Spazio di lavoro → Ambienti. Solo gli amministratori dello spazio di lavoro possono modificare le definizioni, e solo il proprietario del server può salvare quelle che girano sull’host del server (vedi Chi può salvare cosa).
- Fai clic su Nuova definizione, poi su Definizione vuota o Crea bozza dal repo. Una bozza cerca nel repo file compose, un
Procfilee script dipackage.json, e tu controlli il risultato. - Compila il modulo oppure usa la scheda JSON. Gli esempi in questa pagina sono quel JSON.
- Fai clic su Esegui test. Avvia un ambiente usa e getta, attende che sia pronto e lo distrugge.
Salva controlla una definizione in modo rigoroso. Un campo sconosciuto, un valore del tipo sbagliato o una scelta scritta male viene rifiutato, con il suo percorso e il nome valido più vicino, come repos.app.requird: Unknown field. Did you mean "required"?. Un $schema di primo livello è ammesso.
Per tenere una definizione in un repo, usa Collega un file del repo. Control Center legge il file solo dal branch predefinito ed esegue solo la versione che è stata approvata: da un amministratore dello spazio di lavoro, oppure dal proprietario del server quando la definizione gira sull’host. Una versione più recente mostra Aggiornamento disponibile e non cambia nulla finché non viene approvata.
Chi può salvare cosa
Sezione intitolata “Chi può salvare cosa”Una definizione di ambiente può eseguire comandi sull’host del server come utente del server stesso. È una decisione del proprietario del server, non di un ruolo nello spazio di lavoro:
- Una definizione gira sull’host quando ha un posizionamento sull’host, un controllo che esegue un comando, oppure un task
provisionoarchive. Questi task vengono eseguiti nel worktree dello spazio sull’host, qualunque sia il posizionamento. - Solo il proprietario del server può salvare o approvare una definizione che gira sull’host. Ciò include l’approvazione di una nuova versione di un file del repo collegato. Un amministratore dello spazio di lavoro che ci prova vede «Solo il proprietario del server può salvare o approvare un ambiente che viene eseguito sull’host del server. Un amministratore dello spazio di lavoro può usarne uno eseguito in un rig.»
- Un amministratore dello spazio di lavoro può salvare e approvare una definizione che gira interamente in un rig:
"placement": "rig", nessun comando di controllo e nessun taskprovisionoarchive. - I membri avviano, fermano e usano gli ambienti in entrambi i casi.
- Una definizione che gira sull’host viene eseguita solo dopo che il proprietario del server attuale l’ha salvata o approvata. Il server registra da sé quell’approvazione e la verifica prima di ogni avvio, controllo, task e sincronizzazione della testa di una pull request. Una definizione che il proprietario attuale non ha approvato, come una salvata da un proprietario precedente, resta in attesa sotto la sua riga nell’elenco degli ambienti e nell’editor. Il proprietario del server vede «Viene eseguito su questo server. Approvalo per consentirne l’avvio.» con Approva, che la salva invariata; tutti gli altri vedono «Viene eseguito su questo server. Il proprietario del server deve approvarlo prima che possa avviarsi.»
- Un ambiente in attesa di questa approvazione dice «Il proprietario del server non ha ancora approvato questo ambiente, quindi non può essere eseguito su questo server.» Il proprietario del server vede invece «Non hai ancora approvato questo ambiente. Viene eseguito su questo server, quindi si avvierà quando approverai la sua definizione.» con Esamina e approva, che apre la definizione.
- I terminali dei processi di un ambiente, e il terminale che un avvio apre quando serve un tuo intervento, girano sull’host del server. Scrivere in uno di essi, ridimensionarlo o chiuderlo richiede l’accesso in scrittura a ogni repository che lo spazio espone, leggibile tramite il tuo accesso personale al forge: lo stesso richiesto per avviare l’ambiente. Chiunque altro non può raggiungere affatto quei terminali.
La definizione più piccola
Sezione intitolata “La definizione più piccola”A un semplice repo compose basta questo:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Tutto il resto ha un valore predefinito: il file compose viene individuato, ogni servizio viene eseguito, le porte vengono assegnate, gli endpoint HTTP vengono rilevati e l’ambiente prende il nome dal branch.
Tipi di componenti
Sezione intitolata “Tipi di componenti”Un ambiente è un elenco ordinato di componenti. Ognuno attende che il precedente sia pronto, a meno che after non ne indichi altri, e l’arresto avviene in ordine inverso. enabledWhen subordina un componente a un’opzione o a un ruolo, ad esempio opt.seed, !opt.seed o repo.web. Un componente il cui ruolo è facoltativo e manca nello spazio viene escluso allo stesso modo, senza bisogno di enabledWhen: non si avvia e non ha {port.*} né {url.*}, quindi un altro componente che li legge fa fallire l’avvio.
| Tipo | Chi lo esegue | A cosa serve |
|---|---|---|
compose |
Il driver compose di Control Center | Qualsiasi file compose, uno per ambiente |
cli |
Il tuo strumento. Control Center chiama i verbi mappati e legge JSON | Uno strumento che gestisce ciclo di vita, domini e dati |
process |
Control Center, in una sessione di terminale supervisionata | Server di sviluppo e worker |
task |
Control Center, una volta per trigger | Installazioni, migrazioni, test |
app |
Control Center, quando qualcuno preme Lancia | Un’app desktop |
I componenti task accettano un elenco when:
| Trigger | Quando viene eseguito |
|---|---|
provision |
Alla creazione del worktree (vedi i task di worktree più avanti) |
create |
Una volta per ambiente, e di nuovo dopo un ripristino |
start |
A ogni avvio |
change |
Dopo una sincronizzazione, se un percorso modificato corrisponde a onChange |
manual |
Su richiesta: Esegui, cc-env run <id> o environment_run_task |
archive |
Subito prima che il worktree venga distrutto |
Un task senza nulla da fare durante un avvio mostra Inattivo ed è escluso dall’elenco dei passaggi mostrato mentre l’ambiente si avvia: un task manual o change, oppure un task create già eseguito.
Un comando dato come array è argv, quindi i valori delle opzioni non passano mai da una shell. Una stringa, o script con un array di righe, viene eseguita con bash -lc. I segnaposto come {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} e {url.<role>} vengono espansi solo in argv. I comandi shell leggono gli stessi valori come variabili CC_ENV_*, ad esempio $CC_ENV_PORT_WEB. Un segnaposto sconosciuto in un componente che partecipa blocca l’avvio prima che venga eseguito qualcosa.
Ogni comando e terminale di spazio riceve anche CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> e, negli spazi delle PR, CC_PR_NUMBER e CC_PR_IS_FORK. Con un componente compose ricevono anche COMPOSE_PROJECT_NAME e COMPOSE_FILE, così docker compose exec in un task raggiunge il progetto giusto.
Ruoli e directory di lavoro
Sezione intitolata “Ruoli e directory di lavoro”Una definizione lega dei ruoli ai repo dello spazio di lavoro, così uno stack può coprire più repo:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: uno spazio può avviare l’ambiente se contiene almeno un ruolo àncora. Se due definizioni corrispondono, sceglie chi avvia.required: lo stack non può funzionare senza questo repo.whenMissing: cosa succede quando allo spazio manca il ruolo.addToSpaceaggiunge il repo sul suo branch predefinito ed è il valore predefinito per i ruolirequired.useSourcepassa il tuo checkout registrato, da trattare in sola lettura.skiplascia la variabile non impostata ed è il valore predefinito negli altri casi.- Per avviare servono un permesso
writesu un repo àncora dello spazio e l’accesso in lettura a tutti gli altri repo legati.
Un comando viene eseguito nel primo ruolo dichiarato in repos, mai in un altro ruolo presente nello spazio, quindi una definizione con un solo repo non ne parla mai. Qualsiasi componente può cambiarlo con "cwd": { "role": "e2e", "path": "packages/ui" }. Entrambi i campi sono facoltativi. Quando il primo ruolo potrebbe mancare in uno spazio, perché non è required né l’unico ruolo di ancoraggio, ogni componente deve indicare il proprio ruolo.
Porte e URL
Sezione intitolata “Porte e URL”Control Center assegna le porte dell’host prima che qualcosa si avvii, da un intervallo unico per tutto l’host (da 42000 a 49999 per impostazione predefinita, in blocchi da 32). Una porta resta la stessa per tutta la vita dell’ambiente, e le porte compose si legano solo a 127.0.0.1.
- Le porte compose non vanno dichiarate. Leggile come
{port.postgres.5432}oCC_ENV_PORT_POSTGRES_5432. - Le altre porte si dichiarano dove servono, con
"port": "web"o"ports": ["web", "hmr"], e si leggono come{port.web}. Un processo con una porta riceve anchePORTeHOST=127.0.0.1.
Gli endpoint HTTP ricevono un URL sul router del server, che ascolta su un’unica porta di loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>è il branch come slug, oppurepr-<n>in uno spazio di PR.<project>ènaming.project, altrimenti il nome della definizione.- I nomi
*.localhostsi risolvono sul loopback, quindi non richiedono voci hosts né DNS, e il nome host tiene separati i cookie tra gli ambienti. - Le porte compose che rispondono in HTTP vengono rilevate, e
httpsul componente sostituisce il rilevamento. Un processo ha bisogno di"endpoint": { "role": "web", "primary": true }, che rende disponibile anche{url.web}. - Nel browser (VM), usa Apri in Browser (VM).
https://web--fix-login--shop.localhost/lì raggiunge la stessa rotta. - L’intera etichetta resta entro 63 caratteri, quindi i nomi lunghi vengono accorciati con un hash.
- Due endpoint non condividono un dominio padre. Un’app che ha bisogno di un cookie su entrambi deve servirli da un unico endpoint.
Per gli URL da registrare in anticipo, come i redirect OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } fornisce un insieme fisso di nomi.
policy decide quando gli ambienti sono in esecuzione. autoCreate è off, prSpaces o allSpaces, idleStopMinutes vale 240 per impostazione predefinita, followPrHead sincronizza l’ambiente di una PR quando la sua head si sposta e maxRunning (predefinito 6) fa sì che Avvia proponga di fermare l’ambiente usato meno di recente.
Esempio: app compose
Sezione intitolata “Esempio: app compose”Un’app web e Postgres da un unico file compose, con un .env ignorato da git, migrazioni e un task di test. seedFiles copia file specifici dal tuo checkout registrato in ogni nuovo worktree.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks permette a un servizio senza un proprio controllo di integrità di trattenere il componente successivo. Senza, un container in esecuzione conta come pronto e le migrazioni possono anticipare un database ancora in avvio.
Ogni avvio e ogni aggiornamento eseguono up con --remove-orphans, quindi un servizio rimosso dal file compose si ferma e libera la sua porta. Le immagini vengono costruite all’avvio e all’aggiornamento, a meno che il componente non imposti "build": false.
Esempio: CLI personalizzata
Sezione intitolata “Esempio: CLI personalizzata”Uno strumento immaginario acme che gestisce i propri container, domini e TLS. Control Center fornisce {name} e ricava tutto il resto da status. Non deduce mai i nomi host di uno strumento e non modifica mai /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,statusedestroysono obbligatori. Control Center scegliecreateostartin base allo stato che legge. Qualsiasi verbo può essere{ "shell": "…" }invece di argv.interactiveindica i verbi, tracreate,startereset, che possono chiedere ciò che serve su un terminale. Quando uno di questi verbi termina con codice 3 per una persona che ha premuto Avvia, Control Center esegue di nuovo lo stesso verbo in una scheda del terminale, e l’avvio prosegue quando termina con codice 0. Lì la condizioneinteractiveè vera eCC_ENV_INTERACTIVE=1è impostato, quindi{ "if": "!interactive", "args": ["--json"] }mantiene l’output per macchina nella pipe. Un avvio da parte di un agente, o uno automatico, non apre mai un terminale: l’ambiente mostra Azione richiesta e attende.- Un
destroyche fallisce rimuove comunque l’ambiente quandostatuspoi segnalamissing, così un ambiente che lo strumento non ha più può essere sempre rimosso. listpermette a Control Center di accorgersi di un ambiente che lo strumento ha perso. Viene segnato come scomparso solo quando il suo nome manca inlistestatusallora rispondemissing. L’output che non si può leggere come elenco non cambia nulla.{service}inlogsedexecdeve essere una sola parola che non inizia con-, e uno dei servizi che lo strumento ha riportato per ultimo, quando ne ha riportato qualcuno.statusMaplegge il JSON dello strumento con puntatori JSON, dove*corrisponde a ogni elemento. Le regole di stato sono ordinate e vince la prima corrispondenza. Una condizione èpathconequals, oppureanyononeconwhere.keepsDataOnStop: falsedisattiva l’arresto per inattività e aggiunge un avviso di perdita dati a Ferma. Impostalo quando l’arresto perde dati.routing.mode: "tool"collega i nomi host dello strumento al browser (VM) e agli agenti. Il dominio deve terminare con.test,.localhosto.internal, e un URL segnalato al di fuori viene scartato.
Uno strumento di cui sei autore può fare a meno di statusMap e stampare il contratto di stato descritto alla fine di questa pagina.
Esempio: monorepo pnpm
Sezione intitolata “Esempio: monorepo pnpm”Solo processi e task, senza container. L’app web trova l’API tramite {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"] } ]}- Ogni processo è una scheda di terminale che puoi aprire, leggere e in cui puoi digitare, se hai accesso in scrittura a ogni repository dello spazio (vedi Chi può salvare cosa). Chiudere la scheda non lo ferma.
readyaccettahttp(un URL completo),tcp(host:port) ologMatch(un’espressione regolare).restartèon-failure(predefinito),alwaysonever.restartOnriavvia il processo quando un percorso modificato corrisponde.optionsdiventa un modulo su Avvia, eagentDefaultsi applica alle esecuzioni avviate da un agente.
Esempio: app desktop
Sezione intitolata “Esempio: app desktop”Un’app desktop con un passaggio di build. Un’app funziona allo stesso modo con qualsiasi tecnologia, perché Control Center lavora al livello delle finestre del sistema operativo e non ha bisogno di hook o SDK nell’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" } ]}Un’app non si avvia con l’ambiente. Qualcuno preme Lancia e prepare viene eseguito prima. Ricompila e rilancia ripete la coppia. enabledWhen si applica all’app e al suo task prepare, e Lancia viene rifiutato finché uno dei due è disattivato. Un’app risulta in esecuzione finché un processo del suo gruppo di processi è attivo, quindi va bene un lanciatore che avvia l’app ed esce. Se tutto scompare entro circa 5 secondi da Lancia, l’app risulta fallita con le ultime righe di log. Dopo, un’uscita pulita appare come chiusa e un crash mostra le ultime righe di log, e nessuno dei due la riavvia. Un riavvio del server chiude l’app e non la rilancia mai, e l’arresto per inattività lascia stare un’app in esecuzione.
Autorizzazioni e limiti delle app desktop
Sezione intitolata “Autorizzazioni e limiti delle app desktop”- Su macOS, concedi una volta a Control Center Registrazione schermo e Accessibilità in Impostazioni di Sistema. L’host del server ha bisogno di una sessione grafica: un server headless rifiuta di avviare un’app.
- Avvia direttamente il binario.
open -apassa l’app a LaunchServices, che la porta fuori dall’albero dei processi seguito da Control Center, quindi l’app risulta fallita subito dopo l’avvio. - Le finestre restano su uno schermo. macOS non cattura una finestra parcheggiata fuori da ogni schermo, quindi un’app usata da un agente è visibile sullo schermo del server. Non serve che abbia il focus.
"isolate": "home"dà all’app una home privata tramiteHOME,XDG_*eCFFIXED_USER_HOME, così copie di due spazi possono girare affiancate.NSUserDefaultsnon è isolato, quindi le preferenze Cocoa eshared_preferencesdi Flutter restano condivise tra le copie.isolatesi applica solo al processo avviato. Un launcher di toolchain comeflutter runha bisogno della home reale, quindi abbinaisolatea un binario compilato. Se l’app ha una propria impostazione, come--user-data-dir, preferisci quella.- Gli agenti guidano la finestra con
app_use, che raggiunge solo l’albero dei processi di questo ambiente. Un agente vede la finestra, non il desktop. Gli avvii da parte degli agenti passano dalla policy delle azioni e per impostazione predefinita chiedono conferma, e l’input dell’agente si ferma mentre una persona ha il controllo. "input": "background"(predefinito) invia gli eventi al processo."foreground"attiva la finestra e prende il controllo del cursore.
Task di worktree
Sezione intitolata “Task di worktree”I task provision e archive eseguono la configurazione e la chiusura di un repo insieme al suo worktree. L’icona sulla riga di un repo in Impostazioni → Spazio di lavoro → Repository apre la definizione del repo.
Questi task seguono il worktree, non l’ambiente, quindi vengono eseguiti anche negli spazi dove nessuno preme Avvia:
provision |
archive |
|
|---|---|---|
| Viene eseguito | Alla creazione del worktree del ruolo, in qualsiasi spazio | Subito prima che quel worktree venga distrutto |
| In caso di errore | Il provisioning fallisce e il worktree viene distrutto | Registrato, non blocca mai l’eliminazione |
| Timeout predefinito | 5 minuti | 2 minuti |
| Vede | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Lo stesso |
A un repo senza stack basta una definizione con i suoi task. Non essendoci nulla da avviare, non serve un ruolo àncora:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Non esiste ancora un ambiente, quindi questi task non possono usare
{name},{port.*},{url.*},{opt.*}oenabledWhen, e non ricevono l’envdella definizione. - Solo una definizione può contenere task
provisionearchiveper un repo. Le altre possono comunque legarlo per tutto il resto. "when": ["provision", "change"]reinstalla anche quando cambia un lockfile.- Un task viene eseguito per il worktree del suo ruolo
cwd, quindi una definizione con più repo può configurare ogni repo separatamente. - Un’esecuzione di test imposta
CC_SCRIPT_TEST=1. Un nuovo tentativo parte da un worktree pulito, quindi scrivi task che reggano una riesecuzione.
Gli agenti non ricevono mai il socket Docker. In uno spazio con una definizione idonea, un’esecuzione riceve cc-env nel proprio PATH. Lo spazio deriva dall’esecuzione, quindi un agente può agire solo sul proprio ambiente, e ogni comando passa dalla policy delle azioni.
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>Con un componente compose, uno shim docker consente anche docker compose con ps, logs, exec, port, restart e top, e solo sul progetto compose proprio di questo ambiente. Prima del verbo non può esserci alcun flag, e ogni verbo accetta un breve elenco di opzioni: logs non può seguire l’output, e exec accetta solo -T (o --no-tty). Le opzioni che indirizzano compose verso un altro file o progetto (-f, -p, --project-directory, --env-file, --profile) vengono rifiutate ovunque compaiano. Tutto il resto esce con codice 5 e “not available in Control Center agent runs”.
Un repo le cui skill chiamano il proprio strumento può continuare a farlo. Un blocco agentPassthrough su un componente cli dichiara quali comandi possono eseguire gli agenti. Passano solo i comandi che la definizione approvata dichiara, e ognuno gira sull’host, quindi vale la regola Eseguire comandi sull’host, che chiede prima per impostazione predefinita:
"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 indica l’operazione di cui si applica la policy. positionalName forza quell’argomento sull’ambiente di questo spazio, nameFilter filtra l’output JSON su di esso e ogni valore di pathFlags deve risolversi nei worktree dell’esecuzione. Un comando che non corrisponde ad alcuna regola esce con codice 5.
Le stesse operazioni esistono come strumenti: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app e environment_stop_app. Gli agenti in sandbox raggiungono direttamente le proprie porte e i nomi host del proprio ambiente tramite il proxy dell’esecuzione, quindi di’ loro di leggere gli endpoint da environment_status invece di indovinare un URL.
Pull request da fork
Sezione intitolata “Pull request da fork”Il codice di una PR da fork non è attendibile, e con il posizionamento sull’host viene eseguito come utente di sistema del server. policy.forkPrs decide cosa succede:
| Valore | Effetto | Predefinito per |
|---|---|---|
rig |
Il file compose viene eseguito in una VM senza conferma | Definizioni con soli componenti compose e task |
approval |
Ogni avvio richiede un amministratore | Tutte le altre definizioni |
deny |
Rifiutato | Nessuna |
- I
seedFilesnon vengono mai copiati per un fork, perché di solito sono segreti. Un file compose che ne monta uno segnala il file mancante per nome. - I task
provisionearchivevengono saltati, a meno che la policy non siarig: in quel caso vengono eseguiti nella VM. - Con il posizionamento sull’host,
privileged, i namespace dell’host, un bind del socket Docker,devicese i bind al di fuori dei worktree dello spazio vengono rifiutati su un fork. Negli spazi attendibili generano solo un avviso.
Posizionamento in rig
Sezione intitolata “Posizionamento in rig”"placement": "rig" esegue i componenti compose e task in una microVM dedicata. Le definizioni con componenti process, cli o app non sono idonee. Il file compose viene eseguito senza modifiche, senza socket Docker dell’host e senza credenziali dell’operatore, e l’accesso alla rete è limitato ai registri necessari alle sue immagini. Il worktree viene montato dal vivo.
- Guest arm64. I guest sono arm64 su Apple Silicon, quindi le immagini solo amd64 non funzionano.
- I registri privati vengono rifiutati. I guest non hanno credenziali di registro, quindi un’immagine su un registro esterno a quelli pubblici noti viene rifiutata prima dell’avvio della VM. Un repository privato su un registro pubblico fallisce quando il guest lo scarica.
- 16 GiB di spazio. Tutte le immagini e i volumi dello stack condividono un disco da 16 GiB, che non può essere ampliato.
- Il primo avvio è lento. I layer delle immagini sono per VM, quindi il primo avvio scarica tutto. Un rig fermo conserva il disco.
- Le immagini di base devono essere leggibili. Un Dockerfile che indica l’immagine di base tramite una variabile non può essere pianificato, perché l’accesso alla rete è fissato all’avvio.
- Durata.
policy.rigTtlHourstermina la VM, dopo 24 ore per impostazione predefinita.
Contratto di stato per gli autori di strumenti
Sezione intitolata “Contratto di stato per gli autori di strumenti”Un componente cli senza statusMap si aspetta il contratto nativo, cc-env/1. Il verbo status stampa questo oggetto su stdout:
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}stateèready,starting,stopped,failedomissing.missingporta acreate,stoppedefailedportano astart. Segnalamissingcon codice di uscita 0: unostatusfallito conta comefailed.- Serve solo
state. I campi sconosciuti vengono ignorati, e un output non analizzabile appare come degradato, con il testo grezzo come dettaglio. - Un URL deve essere di loopback,
*.localhosto sottorouting.domain, altrimenti viene scartato. needsRecreate: truemostra Ricrea, che scarta i dati. Control Center non agisce mai da solo su questo valore.- Il verbo
liststampa un array JSON di nomi, o di oggetti con unname.
I codici di uscita valgono per ogni verbo:
| Codice | Significato |
|---|---|
| 0 | OK |
| 3 | Serve una risposta in un terminale, come una password di sudo. Un verbo elencato in interactive viene rieseguito in una scheda del terminale per la persona che ha premuto Avvia. Altrimenti Esegui nel terminale apre un terminale di spazio con il command dello strumento digitato ma non eseguito, poi Riprova riprova. Control Center non esegue mai sudo e non risponde mai a un prompt |
| 4 | Accesso richiesto. Il command dello strumento indica come |
| 5 | Ciò da cui dipende non è disponibile, come un runtime di container che non è in esecuzione |
| Altro | Errore |
I codici 3, 4 e 5 non sono errori. L’ambiente mostra Azione richiesta e attende, e il successivo avvio riprende da dove si era fermato. Un task che termina con uno di questi codici significa lo stesso.
L’avanzamento va su stderr come JSON delimitato da newline:
{"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"}Mentre un ambiente si avvia, il pannello elenca i componenti che l’avvio attraversa, ciascuno con uno spinner, un segno di spunta o una croce. Una riga step indica che cosa sta facendo lo strumento in questo momento, e la sua label compare sotto la riga dello strumento; i passaggi non aggiungono mai righe. Lo state di un passaggio è pending, running, done o failed, e un passaggio senza state è in esecuzione. Un passaggio che si aggiorna con lo stesso id (una stringa o un numero, oppure la stessa label se manca) sostituisce quanto detto prima, quindi uno strumento con un solo spinner può mantenere lo stesso id e cambiare la label. Senza id, i passaggi si susseguono: uno nuovo chiude quello precedente. Quando il comando termina, un passaggio ancora in corso si chiude nello stesso modo in cui si è chiuso il comando.
Una riga log contiene una riga di output che lo strumento ha incapsulato in JSON, e viene letta come output normale. Una riga note va nell’output dell’esecuzione, e una con "level": "warn" resta anche sull’ambiente come avviso. Un’ultima riga di tipo error diventa un errore strutturato, con command proposto da copiare, e le ultime 12 righe di output compaiono sotto il suo message. Altrimenti Control Center mostra le ultime 20 righe di stderr. Tutto ciò che non è JSON è normale output di log.