Ejecutar un worker de flota

Ejecuta cc_worker en una máquina de repuesto para agregar capacidad de ejecución a tu flota. Es un binario de Dart puro —sin motor de Flutter— que se empareja con un cc_server, declara las capacidades del host, envía latidos, recoge trabajos en arrendamiento, los ejecuta y transmite de vuelta los eventos de proceso. No guarda ningún estado duradero: un supervisor lo reinicia y el worker se vuelve a registrar.

Necesitas un cc_server en ejecución primero; consulta Ejecutar un servidor headless.

Un worker emparejado se registra, envía latidos y espera trabajos en arrendamiento. Envía trabajo con fleet.submitJob. El despacho de agentes en este servidor no pasa por la flota; la señal de éxito de esta guía es que el worker aparezca en el panel de flota con un latido reciente. El worker en proceso registrado al arranque tiene un mapa de runners vacío, así que un trabajo colocado en él devuelve No local runner for job kind ….

Requisitos previos

El SDK de Dart. Este repositorio fija su SDK con fvm, así que antepone fvm a los comandos.
Este repositorio clonado en la máquina del worker.
Un cc_server accesible (loopback para desarrollo, LAN o remoto para producción).
git en el PATH — el worker materializa repositorios y ejecuta sondas de git.

Paso 1: Compila el binario

cd apps/cc_worker
fvm dart build cli

Esto genera un paquete autocontenido en ./build/cli/<os_arch>/bundle/bin/cc_worker.

Paso 2: Genera la credencial del worker

Un cc_server solo acepta un worker que presente un id. de dispositivo emparejado y una clave precompartida —incluso un servidor de loopback—. Genéralas en la máquina del servidor (pair puede ejecutarse mientras el servidor está activo; el nuevo dispositivo se detecta sin reiniciar):

cc_server pair --data-dir <dir> --device my-worker --label "Build box"

Imprime un Device id y una Pairing key: eso es lo que reciben --device-id y --psk / --psk-file / CC_WORKER_PSK.

Paso 3: Inicia el worker

Contra un servidor emparejado:

./build/cli/<os_arch>/bundle/bin/cc_worker \
  --server wss://host:9030 --device-id my-worker --psk-file /path/to/worker.psk

Contra un servidor de loopback (aun así emparejado — cc_server siempre ejecuta el handshake de PSK):

fvm dart run cc_worker --server ws://localhost:9030 \
  --device-id my-worker --psk-file /path/to/worker.psk

Marca	Descripción	Predeterminado
`--server <url>`	URL de cc_server (`ws://`/`wss://`; `http(s)` y una ruta `/rpc` ausente se normalizan). Obligatoria.	—
`--name <name>`	Nombre del worker visible para el operador.	nombre del host
`--device-id <id>`	Id. de dispositivo emparejado estable, que también se usa como id. del worker.	`cc-worker`
`--psk-file <path>`	Archivo cuya primera línea no vacía es la clave de emparejamiento. Se prefiere sobre `--psk`.	—
`--psk <key>`	Clave de emparejamiento en la línea de comandos. Visible en `ps` y en el historial del shell — el binario advierte.	—
`--max-jobs <n>`	Límite máximo de trabajos que este proceso ejecuta de forma simultánea (entero positivo).	`4`

El orden de resolución de la clave es --psk-file → CC_WORKER_PSK → --psk. Omitir todas las fuentes salta el handshake de autenticación del worker; un cc_server real entonces deniega la sesión (auth_denied) en lugar de aceptar un worker sin autenticar. Las marcas desconocidas son un error de uso (exit 64) — a diferencia de cc_server, este binario usa package:args y no ignora los errores de escritura.

CC_WORKER_CACHE sobrescribe el directorio de caché de materialización de worktrees (predeterminado: un directorio cc_worker_cache dentro del directorio temporal del sistema).

El worker se registra con fleet.registerWorker, luego envía latidos cada 20 s y sondea arrendamientos cada 2 s. Se ejecuta hasta recibir SIGINT/SIGTERM; ponlo bajo systemd o launchd para que se reinicie y vuelva a registrarse tras un fallo o un reinicio.

Paso 4: Verifícalo en el panel de flota

Abre Observabilidad en la app de escritorio o la web, cambia a la pestaña En vivo y desplázate hasta el final. Trabajadores enumera cada worker registrado con su plataforma, núcleos, claves de capacidad y último latido; Trabajos enumera los trabajos distribuidos entre ellos.

Que tu worker aparezca ahí con un latido reciente es la confirmación de que el emparejamiento y el registro funcionaron.

Desde el mosaico de un worker puedes drenarlo (terminar los trabajos actuales, no tomar nuevos arrendamientos), reanudar un worker que se está drenando, revocar su credencial o eliminar la fila.

Las filas de workers y trabajos viven en el global.db del servidor: el worker mismo no escribe nada en disco más allá de la caché de materialización.

Qué anuncia el worker

Al registrarse, el worker autodetecta sus capacidades y el planificador compara los trabajos con ellas. No las configuras a mano:

SO y arquitectura (macos/linux/windows, arm64/x64) — sondas exactas, con reserva a uname -m / PROCESSOR_ARCHITECTURE
Núcleos y RAM — recuento exacto de núcleos; la RAM se degrada a 0 cuando no se puede sondear
flutter — se establece cuando hay un SDK de Flutter accesible (flutter sin más, luego fvm flutter); los trabajos de render golden lo requieren
sandbox — native-macos en macOS, native-linux en Linux. Esto es una pista de colocación, no una promesa: el worker anuncia el backend que su plataforma tiene, pero no envuelve en uno los trabajos que ejecuta. A diferencia de cc_server, cc_worker lanza un trabajo en arrendamiento directamente
always-on y parallel — un cc_worker dedicado siempre anuncia ambas, así que es elegible para lotes de evaluación y otra capacidad paralela desechable

La detección es de mejor esfuerzo: todo lo que no puede sondear se degrada a un valor predeterminado seguro en lugar de fallar al arrancar.

Qué ejecutaría el worker

El protocolo de arrendamiento transporta seis tipos de trabajo:

Tipo	Qué es
`agentRun`	Una sola ejecución de agente (despacho)
`pipelineStep`	La ejecución de un paso de pipeline
`codeIndex`	La compilación del índice de código de un repo
`goldenRender`	Una renderización visual golden de la interfaz (requiere `flutter`)
`benchmark`	Una ejecución de benchmark de rendimiento
`evalBatch`	Un lote de evaluación (prefiere capacidad `parallel`)

La ejecución es una implementación real de subprocesos con streaming, no un runtime de agente embebido completo. Cuando un arrendamiento lleva repoRemote, el worker hace git clone --depth 1 en un directorio de caché con clave de remoto y SHA, y luego git fetch y git checkout. Para agentRun ejecuta en el directorio de trabajo el comando indicado por CC_JOB_COMMAND del entorno del arrendamiento, transmitiendo stdout y stderr de vuelta como eventos; sin CC_JOB_COMMAND devuelve el prompt tal cual para que el transporte se ejercite de todos modos de extremo a extremo. Los demás tipos ejecutan comandos reales pequeños (git rev-parse HEAD, git --version) como sondas honestas. Las credenciales con alcance de trabajo del entorno del arrendamiento se inyectan en cada subproceso y nunca se escriben en un registro.

Los eventos se agrupan en lotes y se vacían cada 250 ms o cada 32 eventos; cada trabajo termina con un evento done y un informe de finalización. El modelo son latidos más arrendamientos de TTL corto: si un worker pierde el contacto, su arrendamiento expira y el servidor reclama el trabajo para reintentarlo. No hay estado duradero en el worker ni consenso ni robo de trabajo entre workers.

Guías relacionadas

Conceptos relacionados

Implementación y clientes