Configurar entornos
Un entorno es la pila en ejecución de un espacio: los servicios que necesita una rama, aislados de todos los demás espacios, visibles en la barra lateral y accesibles para los agentes. Los pull requests también tienen uno, porque una PR ya tiene su propio espacio.
Un administrador del espacio de trabajo escribe una definición una sola vez. Después, los miembros presionan Iniciar en la sección Entorno de la barra lateral de un espacio o una PR. Las definiciones se guardan en la base de datos del espacio de trabajo, así que una rama de funcionalidad nunca cambia lo que Control Center ejecuta, aunque las herramientas sí ejecutan el código de esa rama.
Crear una definición
Sección titulada «Crear una definición»- Abre Ajustes → Espacio de trabajo → Entornos. Solo los administradores del espacio de trabajo pueden cambiar definiciones, y solo el propietario del servidor puede guardar una que se ejecute en el host del servidor (consulta Quién puede guardar qué).
- Haz clic en Nueva definición y luego en Definición en blanco o Crear borrador desde repo. Un borrador busca en el repo archivos compose, un
Procfiley scripts depackage.json, y tú revisas el resultado. - Llena el formulario o usa la pestaña JSON. Los ejemplos de esta página son ese JSON.
- Haz clic en Ejecutar prueba. Inicia un entorno desechable, espera a que esté listo y lo destruye.
Guardar revisa una definición de forma estricta. Un campo desconocido, un valor de tipo incorrecto o una opción mal escrita se rechaza, con su ruta y el nombre válido más cercano, como repos.app.requird: Unknown field. Did you mean "required"?. Se permite un $schema en el nivel superior.
Para mantener una definición en un repo, usa Vincular un archivo del repo. Control Center lee el archivo solo de la rama predeterminada y ejecuta solo la versión que se aprobó: por un administrador del espacio de trabajo, o por el propietario del servidor cuando la definición se ejecuta en el host. Una versión más reciente muestra Actualización disponible y no cambia nada hasta que se aprueba.
Quién puede guardar qué
Sección titulada «Quién puede guardar qué»Una definición de entorno puede ejecutar comandos en el host del servidor como el propio usuario del servidor. Esa decisión es del propietario del servidor, no de un rol del espacio de trabajo:
- Una definición se ejecuta en el host cuando tiene ubicación en el host, una comprobación que ejecuta un comando, o una tarea
provisionoarchive. Esas tareas se ejecutan en el worktree del espacio en el host, sea cual sea la ubicación. - Solo el propietario del servidor puede guardar o aprobar una definición que se ejecuta en el host. Eso incluye aprobar una nueva versión de un archivo de repo vinculado. Un administrador del espacio de trabajo que lo intente ve «Solo el propietario del servidor puede guardar o aprobar un entorno que se ejecuta en el host del servidor. Un administrador del espacio de trabajo puede usar uno que se ejecute en un rig.»
- Un administrador del espacio de trabajo puede guardar y aprobar una definición que se ejecuta por completo en un rig:
"placement": "rig", sin comando de comprobación y sin tareasprovisionniarchive. - Los miembros inician, detienen y usan entornos en cualquiera de los dos casos.
- Una definición que se ejecuta en el host solo se ejecuta después de que el propietario actual del servidor la haya guardado o aprobado. El servidor registra esa aprobación por sí mismo y la verifica antes de cada inicio, comprobación, tarea y sincronización de la cabeza de una pull request. Una definición que el propietario actual no ha aprobado, como una que guardó un propietario anterior, espera bajo su fila en la lista de entornos y en el editor. El propietario del servidor ve «Se ejecuta en este servidor. Apruébalo para permitir que se inicie.» con Aprobar, que la guarda sin cambios; los demás ven «Se ejecuta en este servidor. El propietario del servidor tiene que aprobarlo antes de que pueda iniciarse.»
- Un entorno retenido para esa aprobación dice «El propietario del servidor todavía no ha aprobado este entorno, así que no puede ejecutarse en este servidor.» El propietario del servidor ve en cambio «Todavía no has aprobado este entorno. Se ejecuta en este servidor, así que se iniciará en cuanto apruebes su definición.» con Revisar y aprobar, que abre la definición.
- Las terminales de procesos de un entorno, y la terminal que abre un inicio cuando necesita tu intervención, se ejecutan en el host del servidor. Escribir en una, redimensionarla o cerrarla necesita acceso de escritura a cada repositorio que expone el espacio, legible con tu propio inicio de sesión en la forja: lo mismo que iniciar el entorno. Los demás no pueden llegar a esas terminales en absoluto.
La definición más pequeña
Sección titulada «La definición más pequeña»Un repo compose sencillo solo necesita esto:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Todo lo demás tiene un valor predeterminado: el archivo compose se detecta, se ejecutan todos los servicios, se asignan puertos, se detectan los endpoints HTTP y el entorno toma el nombre de la rama.
Tipos de componentes
Sección titulada «Tipos de componentes»Un entorno es una lista ordenada de componentes. Cada uno espera a que el anterior esté listo, salvo que after indique otros, y la detención se hace en orden inverso. enabledWhen condiciona un componente a una opción o un rol, por ejemplo opt.seed, !opt.seed o repo.web. Un componente cuyo rol es opcional y no está en el espacio se deja fuera de la misma forma, sin necesidad de enabledWhen: no arranca y no tiene {port.*} ni {url.*}, así que otro componente que los lea hace fallar el inicio.
| Tipo | Quién lo ejecuta | Para qué sirve |
|---|---|---|
compose |
El controlador compose de Control Center | Cualquier archivo compose, uno por entorno |
cli |
Tu herramienta. Control Center llama a los verbos asignados y lee JSON | Una herramienta que controla su ciclo de vida, dominios y datos |
process |
Control Center, en una sesión de terminal supervisada | Servidores de desarrollo y workers |
task |
Control Center, una vez por disparador | Instalaciones, migraciones, pruebas |
app |
Control Center, cuando alguien presiona Lanzar | Una aplicación de escritorio |
Los componentes task aceptan una lista when:
| Disparador | Se ejecuta |
|---|---|
provision |
Al crear el worktree (consulta las tareas de worktree más abajo) |
create |
Una vez por entorno, y de nuevo tras un restablecimiento |
start |
En cada inicio |
change |
Tras una sincronización, si una ruta cambiada coincide con onChange |
manual |
Bajo petición: Ejecutar, cc-env run <id> o environment_run_task |
archive |
Justo antes de destruir el worktree |
Una tarea que no tiene nada que hacer en un inicio muestra Inactivo y no aparece en la lista de pasos que se muestra mientras arranca el entorno: una tarea manual o change, o una tarea create que ya se ejecutó.
Un comando dado como array es argv, así que los valores de las opciones nunca pasan por un shell. Una cadena, o script con un array de líneas, se ejecuta con bash -lc. Los marcadores como {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} y {url.<role>} solo se expanden en argv. Los comandos de shell leen los mismos valores como variables CC_ENV_*, por ejemplo $CC_ENV_PORT_WEB. Un marcador desconocido en un componente que participa detiene el inicio antes de ejecutar nada.
Cada comando y cada terminal de espacio reciben además CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> y, en los espacios de PR, CC_PR_NUMBER y CC_PR_IS_FORK. Con un componente compose también reciben COMPOSE_PROJECT_NAME y COMPOSE_FILE, de modo que docker compose exec en una tarea llega al proyecto correcto.
Roles y directorio de trabajo
Sección titulada «Roles y directorio de trabajo»Una definición vincula roles a repos del espacio de trabajo, para que una pila pueda abarcar varios repos:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: un espacio puede iniciar el entorno si contiene al menos un rol ancla. Si coinciden dos definiciones, elige quien lo inicia.required: la pila no puede funcionar sin este repo.whenMissing: qué ocurre cuando el espacio no tiene el rol.addToSpaceañade el repo en su rama predeterminada y es el valor por defecto de los rolesrequired.useSourcepasa tu copia registrada, que debes tratar como de solo lectura.skipdeja la variable sin definir y es el valor por defecto en los demás casos.- Para iniciar hace falta un permiso
writesobre un repo ancla del espacio y acceso de lectura a todos los demás repos vinculados.
Un comando se ejecuta en el primer rol declarado en repos, nunca en otro rol que tenga el espacio, así que una definición de un solo repo nunca lo menciona. Cualquier componente puede cambiarlo con "cwd": { "role": "e2e", "path": "packages/ui" }. Ambos campos son opcionales. Cuando el primer rol podría faltar en un espacio, porque no es required ni el único ancla, cada componente tiene que indicar su rol.
Puertos y URL
Sección titulada «Puertos y URL»Control Center asigna los puertos del host antes de que arranque nada, a partir de un rango común a todo el host (de 42000 a 49999 por defecto, en bloques de 32). Un puerto se mantiene durante toda la vida del entorno, y los puertos de compose solo se enlazan a 127.0.0.1.
- Los puertos de compose no hay que declararlos. Léelos como
{port.postgres.5432}oCC_ENV_PORT_POSTGRES_5432. - Los demás puertos se declaran donde se usan, con
"port": "web"o"ports": ["web", "hmr"], y se leen como{port.web}. Un proceso con puerto también recibePORTyHOST=127.0.0.1.
Los endpoints HTTP reciben una URL en el enrutador del servidor, que escucha en un solo puerto de loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>es la rama como slug, opr-<n>en un espacio de PR.<project>esnaming.projecto, si no, el nombre de la definición.- Los nombres
*.localhostresuelven a loopback, así que no necesitan entradas en hosts ni DNS, y el nombre de host mantiene separadas las cookies entre entornos. - Los puertos de compose que responden HTTP se detectan, y
httpen el componente sustituye esa suposición. Un proceso necesita"endpoint": { "role": "web", "primary": true }, que además hace disponible{url.web}. - En el navegador (VM), usa Abrir en Browser (VM).
https://web--fix-login--shop.localhost/llega allí a la misma ruta. - La etiqueta completa no supera los 63 caracteres, así que los nombres largos se acortan con un hash.
- Dos endpoints no comparten dominio padre. Una aplicación que necesite una misma cookie en ambos debe servirlos desde un solo endpoint.
Para URL que debes registrar por adelantado, como las redirecciones de OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } proporciona un conjunto fijo de nombres.
policy decide cuándo se ejecutan los entornos. autoCreate es off, prSpaces o allSpaces, idleStopMinutes vale 240 por defecto, followPrHead sincroniza un entorno de PR cuando se mueve su head, y maxRunning (6 por defecto) hace que Iniciar ofrezca detener el entorno usado hace más tiempo.
Ejemplo: aplicación compose
Sección titulada «Ejemplo: aplicación compose»Una aplicación web y Postgres en un archivo compose, con un .env ignorado por git, migraciones y una tarea de pruebas. seedFiles copia archivos concretos de tu copia registrada a cada worktree nuevo.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks permite que un servicio sin comprobación de estado propia frene al siguiente componente. Sin ella, un contenedor en marcha cuenta como listo, y las migraciones pueden adelantarse a una base de datos que aún está arrancando.
Cada inicio y cada actualización ejecutan up con --remove-orphans, así que un servicio que se quitó del archivo de compose se detiene y libera su puerto. Las imágenes se construyen al iniciar y al actualizar, salvo que el componente indique "build": false.
Ejemplo: CLI propia
Sección titulada «Ejemplo: CLI propia»Una herramienta inventada, acme, que controla sus contenedores, dominios y TLS. Control Center aporta {name} y averigua todo lo demás con status. Nunca deduce los nombres de host de una herramienta ni edita /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,statusydestroyson obligatorios. Control Center eligecreateostartsegún el estado que lee. Cualquier verbo puede ser{ "shell": "…" }en lugar de argv.interactivenombra los verbos, de entrecreate,startyreset, que pueden pedir lo que necesitan en una terminal. Cuando uno de esos verbos termina con código 3 para una persona que presionó Iniciar, Control Center vuelve a ejecutar el mismo verbo en una pestaña de terminal, y el inicio continúa cuando termina con código 0. Ahí la condicióninteractivees verdadera yCC_ENV_INTERACTIVE=1está definido, así que{ "if": "!interactive", "args": ["--json"] }mantiene la salida para máquinas en la tubería. Un inicio hecho por un agente, o uno automático, nunca abre una terminal: el entorno muestra Requiere acción y espera.- Un
destroyque falla igual elimina el entorno cuando despuésstatusinformamissing, así que un entorno que la herramienta ya no tiene siempre puede eliminarse. listpermite a Control Center notar un entorno que la herramienta ha perdido. Solo se marca como desaparecido cuando su nombre no aparece enlistystatusentonces respondemissing. Una salida que no se puede leer como lista no cambia nada.{service}enlogsyexecdebe ser una sola palabra que no empiece por-, y uno de los servicios que la herramienta informó la última vez, si informó alguno.statusMaplee el JSON propio de la herramienta con punteros JSON, donde*coincide con cada elemento. Las reglas de estado están ordenadas y gana la primera coincidencia. Una condición espathconequals, oanyononeconwhere.keepsDataOnStop: falsedesactiva la detención por inactividad y añade un aviso de pérdida de datos a Detener. Úsalo cuando detener pierda datos.routing.mode: "tool"conecta los nombres de host de la herramienta con el navegador (VM) y con los agentes. El dominio debe terminar en.test,.localhosto.internal, y una URL notificada fuera de él se descarta.
Una herramienta propia puede prescindir de statusMap e imprimir el contrato de estado descrito al final de esta página.
Ejemplo: monorepo pnpm
Sección titulada «Ejemplo: monorepo pnpm»Solo procesos y tareas, sin contenedores. La aplicación web encuentra la API mediante {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"] } ]}- Cada proceso es una pestaña de terminal que puedes abrir, leer y en la que puedes escribir, si tienes acceso de escritura a cada repositorio del espacio (consulta Quién puede guardar qué). Cerrar la pestaña no lo detiene.
readyadmitehttp(una URL completa),tcp(host:port) ologMatch(una expresión regular).restarteson-failure(por defecto),alwaysonever.restartOnreinicia el proceso cuando coincide una ruta cambiada.optionsse convierte en un formulario en Iniciar, yagentDefaultse aplica a las ejecuciones que inicia un agente.
Ejemplo: aplicación de escritorio
Sección titulada «Ejemplo: aplicación de escritorio»Una aplicación de escritorio con un paso de compilación. Una aplicación funciona igual sea cual sea su tecnología, porque Control Center trabaja a nivel de ventanas del sistema operativo y no necesita ningún hook ni SDK en la aplicación.
{ "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" } ]}Una aplicación no arranca con el entorno. Alguien presiona Lanzar y prepare se ejecuta primero. Recompilar y relanzar vuelve a ejecutar ese par. enabledWhen se aplica a la aplicación y a su tarea prepare, y Lanzar se rechaza mientras cualquiera de las dos esté desactivada. Una aplicación cuenta como en marcha mientras algún proceso de su grupo de procesos siga activo, así que está bien un lanzador que arranca la aplicación y termina. Si todo desaparece en unos 5 segundos después de Lanzar, la aplicación aparece como fallida con sus últimas líneas de registro. Después, una salida limpia aparece como cerrada y un fallo muestra las últimas líneas de registro, y ninguno de los dos la reinicia. Un reinicio del servidor cierra la aplicación y nunca la relanza, y la detención por inactividad deja en paz una aplicación en marcha.
Permisos y límites de las aplicaciones de escritorio
Sección titulada «Permisos y límites de las aplicaciones de escritorio»- En macOS, concede a Control Center Grabación de pantalla y Accesibilidad una vez en Ajustes del Sistema. El host del servidor necesita una sesión gráfica: un servidor sin interfaz se niega a lanzar una aplicación.
- Lanza el binario directamente.
open -aentrega la aplicación a LaunchServices y esta sale del árbol de procesos que sigue Control Center, así que la aplicación aparece como fallida justo después de lanzarla. - Las ventanas permanecen en una pantalla. macOS no captura una ventana situada fuera de todas las pantallas, así que una aplicación que usa un agente se ve en la pantalla del servidor. No necesita el foco.
"isolate": "home"da a la aplicación un directorio personal privado medianteHOME,XDG_*yCFFIXED_USER_HOME, para que copias de dos espacios funcionen en paralelo.NSUserDefaultsno se aísla, así que las preferencias de Cocoa yshared_preferencesde Flutter siguen compartidas entre copias.isolatesolo se aplica al proceso lanzado. Un lanzador de cadena de herramientas comoflutter runnecesita el directorio personal real, así que combinaisolatecon un binario compilado. Si la aplicación tiene su propio ajuste, como--user-data-dir, es preferible.- Los agentes manejan la ventana con
app_use, que solo alcanza el árbol de procesos de este entorno. Un agente ve la ventana, no el escritorio. Los lanzamientos de agentes pasan por la política de acciones y preguntan por defecto, y la entrada del agente se detiene mientras una persona tiene el control. "input": "background"(por defecto) envía eventos al proceso."foreground"activa la ventana y toma el control del cursor.
Tareas de worktree
Sección titulada «Tareas de worktree»Las tareas provision y archive ejecutan la configuración y la limpieza de un repo junto con su worktree. El icono de la fila de un repo en Ajustes → Espacio de trabajo → Repositorios abre la definición del repo.
Estas tareas siguen al worktree, no al entorno, así que se ejecutan en espacios donde nadie presiona Iniciar:
provision |
archive |
|
|---|---|---|
| Se ejecuta | Al crear el worktree del rol, en cualquier espacio | Justo antes de destruir ese worktree |
| Si falla | El aprovisionamiento falla y se destruye el worktree | Se registra y nunca bloquea el borrado |
| Tiempo límite predeterminado | 5 minutos | 2 minutos |
| Ve | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Lo mismo |
Un repo sin pila solo necesita una definición con sus tareas. Como no hay nada que iniciar, no necesita rol ancla:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Aún no hay entorno, así que estas tareas no pueden usar
{name},{port.*},{url.*},{opt.*}nienabledWhen, y no reciben elenvde la definición. - Solo una definición puede tener tareas
provisionyarchivepara un repo. Las demás pueden seguir vinculándolo para todo lo demás. "when": ["provision", "change"]también reinstala cuando cambia un archivo de bloqueo.- Una tarea se ejecuta para el worktree de su rol
cwd, así que una definición con varios repos puede configurar cada uno por separado. - Una ejecución de prueba establece
CC_SCRIPT_TEST=1. Un reintento parte de un worktree limpio, así que escribe tareas que aguanten una nueva ejecución.
Agentes
Sección titulada «Agentes»Los agentes nunca reciben el socket de Docker. En un espacio con una definición apta, una ejecución recibe cc-env en su PATH. El espacio viene de la ejecución, así que un agente solo puede actuar sobre su propio entorno, y cada comando pasa por la política de acciones.
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, un shim de docker también permite docker compose con ps, logs, exec, port, restart y top, y solo contra el propio proyecto compose de este entorno. No puede haber opciones antes del verbo, y cada verbo admite una lista corta de opciones: logs no puede seguir la salida y exec solo admite -T (o --no-tty). Las opciones que apuntan compose a otro archivo o proyecto (-f, -p, --project-directory, --env-file, --profile) se rechazan dondequiera que aparezcan. Todo lo demás termina con código 5 y «not available in Control Center agent runs».
Un repo cuyas skills llaman a su propia herramienta puede seguir haciéndolo. Un bloque agentPassthrough en un componente cli declara qué comandos pueden ejecutar los agentes. Solo pasan los comandos que declara la definición aprobada, y cada uno se ejecuta en el host, así que lleva la regla Ejecutar comandos en el host, que pregunta primero de forma predeterminada:
"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 la operación cuya política se aplica. positionalName fuerza ese argumento al entorno de este espacio, nameFilter filtra la salida JSON para él y cada valor de pathFlags debe resolverse dentro de los worktrees de la ejecución. Un comando que no coincide con ninguna regla termina con código 5.
Las mismas operaciones existen como herramientas: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app y environment_stop_app. Los agentes en sandbox llegan directamente a sus puertos y a los nombres de host de su entorno mediante el proxy de la ejecución, así que indícales que lean los endpoints de environment_status en lugar de adivinar una URL.
Pull requests de forks
Sección titulada «Pull requests de forks»El código de una PR de fork no es de confianza, y en la ubicación en el host se ejecuta como el usuario del sistema del servidor. policy.forkPrs decide qué ocurre:
| Valor | Efecto | Predeterminado para |
|---|---|---|
rig |
El archivo compose se ejecuta en una VM sin preguntar | Definiciones solo con componentes compose y task |
approval |
Cada inicio necesita un administrador | Todas las demás definiciones |
deny |
Rechazado | Ninguna |
- Los
seedFilesnunca se copian para un fork, porque suelen ser secretos. Un archivo compose que monte uno indica el archivo que falta por su nombre. - Las tareas
provisionyarchivese omiten salvo que la política searig, en cuyo caso se ejecutan en la VM. - En la ubicación en el host,
privileged, los espacios de nombres del host, un montaje del socket de Docker,devicesy los montajes fuera de los worktrees del espacio se rechazan en un fork. En espacios de confianza solo generan un aviso.
Ubicación en rig
Sección titulada «Ubicación en rig»"placement": "rig" ejecuta los componentes compose y task en una microVM dedicada. Las definiciones con componentes process, cli o app no son aptas. El archivo compose se ejecuta sin cambios, sin socket de Docker del host ni credenciales del operador, y el acceso a la red se limita a los registros que necesitan sus imágenes. El worktree se monta en vivo.
- Invitados arm64. Los invitados son arm64 en Apple Silicon, así que las imágenes solo amd64 no funcionan.
- Los registros privados se rechazan. Los invitados no tienen credenciales de registro, así que una imagen en un registro fuera de los públicos conocidos se rechaza antes de que arranque la VM. Un repositorio privado en un registro público falla cuando el invitado lo descarga.
- 16 GiB de almacenamiento. Todas las imágenes y volúmenes de la pila comparten un disco de 16 GiB, y no se puede ampliar.
- El primer arranque es lento. Las capas de imagen son por VM, así que el primer arranque lo descarga todo. Un rig detenido conserva su disco.
- Las imágenes base deben poder leerse. Un Dockerfile que nombra su imagen base mediante una variable no se puede planificar, porque el acceso a la red queda fijado al arrancar.
- Duración.
policy.rigTtlHourstermina la VM, a las 24 horas por defecto.
Contrato de estado para autores de herramientas
Sección titulada «Contrato de estado para autores de herramientas»Un componente cli sin statusMap espera el contrato nativo, cc-env/1. El verbo status imprime este objeto en 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": "…" }}stateesready,starting,stopped,failedomissing.missinglleva acreate, ystoppedyfailedllevan astart. Informa demissingcon código de salida 0: unstatusfallido cuenta comofailed.- Solo hace falta
state. Los campos desconocidos se ignoran, y una salida que no se puede analizar aparece como degradada, con el texto sin procesar como detalle. - Una URL debe ser de loopback,
*.localhosto estar bajorouting.domain; si no, se descarta. needsRecreate: truemuestra Recrear, que descarta datos. Control Center nunca actúa por sí solo con esto.- El verbo
listimprime un array JSON de nombres, o de objetos con unname.
Los códigos de salida se aplican a todos los verbos:
| Código | Significado |
|---|---|
| 0 | Correcto |
| 3 | Hace falta una respuesta en una terminal, como una contraseña de sudo. Un verbo listado en interactive se ejecuta de nuevo en una pestaña de terminal para la persona que presionó Iniciar. Si no, Ejecutar en el terminal abre un terminal de espacio con el command de la herramienta escrito pero sin ejecutar, y luego Reintentar lo intenta de nuevo. Control Center nunca ejecuta sudo ni responde a una petición |
| 4 | Hace falta iniciar sesión. El command de la herramienta indica cómo |
| 5 | Algo de lo que depende no está disponible, como un entorno de ejecución de contenedores que no está en marcha |
| Otro | Fallo |
Los códigos 3, 4 y 5 no son fallos. El entorno muestra Requiere acción y espera, y el siguiente inicio continúa donde se detuvo aquel. Una tarea que termina con alguno de ellos significa lo mismo.
El progreso va a stderr como JSON delimitado por saltos de línea:
{"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"}Mientras un entorno arranca, el panel enumera los componentes por los que pasa el inicio, cada uno con un spinner, una palomita o una cruz. Una línea step indica lo que la herramienta está haciendo ahora, y su label aparece debajo de la fila propia de la herramienta; los pasos nunca añaden filas. El state de un paso es pending, running, done o failed, y un paso sin state está en ejecución. Un paso que vuelve a informar con el mismo id (una cadena o un número, o la misma label si no lo tiene) sustituye lo que dijo antes, así que una herramienta con un solo spinner puede conservar un mismo id y cambiar la label. Sin ids, los pasos se suceden: uno nuevo cierra el anterior. Cuando el comando termina, un paso que sigue en ejecución termina igual que el comando.
Una línea log lleva una línea de salida que la herramienta envolvió en JSON y se lee como salida normal. Una línea note va a la salida de la ejecución, y una con "level": "warn" también queda en el entorno como aviso. Una última línea de tipo error se convierte en un error estructurado, y se ofrece copiar command, y las últimas 12 líneas de salida se muestran debajo de su message. Sin ella, Control Center muestra las últimas 20 líneas de stderr. Todo lo que no sea JSON es registro normal.