Een fleet-worker draaien

Draai cc_worker op een vrije machine om uitvoeringscapaciteit aan je fleet toe te voegen. Het is een binary in puur Dart — geen Flutter-engine — die zich koppelt aan een cc_server, de mogelijkheden van de host meldt, een hartslag stuurt, geleasede jobs ophaalt, ze uitvoert en procesgebeurtenissen terugstreamt. Hij houdt geen duurzame staat bij: een supervisor herstart hem en hij registreert zich opnieuw.

Je hebt eerst een draaiende cc_server nodig — zie Een headless server draaien.

Een gekoppelde worker registreert zich, stuurt hartslagen en wacht op geleasede jobs. Dien werk in met fleet.submitJob. Agent-dispatch op deze server loopt niet via de fleet; het succesignaal voor deze gids is dat de worker met een verse hartslag in het fleetpaneel verschijnt. De in-process worker die bij het opstarten wordt geregistreerd, heeft een lege runner-map, dus een job die erop wordt geplaatst, retourneert No local runner for job kind ….

Vereisten

De Dart SDK. Deze repo pint zijn SDK met fvm, dus zet fvm voor je commando’s.
Deze repository uitgecheckt op de worker-machine.
Een bereikbare cc_server (loopback voor ontwikkeling, LAN of remote voor productie).
git op het PATH — de worker materialiseert repo’s en voert git-probes uit.

Stap 1: De binary bouwen

cd apps/cc_worker
fvm dart build cli

Dit levert een op zichzelf staande bundel op in ./build/cli/<os_arch>/bundle/bin/cc_worker.

Stap 2: De referentie van de worker aanmaken

Een cc_server accepteert alleen een worker die zich presenteert met het id van een gekoppeld apparaat en een pre-shared key — ook bij een loopbackserver. Maak ze aan op de server-machine (pair kan draaien terwijl de server actief is; het nieuwe apparaat wordt zonder herstart opgepikt):

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

Het drukt een Device id en een Pairing key af — dat zijn de waarden die --device-id en --psk / --psk-file / CC_WORKER_PSK verwachten.

Stap 3: De worker starten

Tegen een gekoppelde server:

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

Tegen een loopbackserver (nog steeds gekoppeld — cc_server voert altijd de PSK-handshake uit):

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

Flag	Beschrijving	Standaard
`--server <url>`	cc_server-URL (`ws://`/`wss://`; `http(s)` en een ontbrekend `/rpc`-pad worden omgezet). Vereist.	—
`--name <name>`	Naam van de worker voor de operator.	hostnaam
`--device-id <id>`	Stabiel id van het gekoppelde apparaat, ook gebruikt als het worker-id.	`cc-worker`
`--psk-file <path>`	Bestand waarvan de eerste niet-lege regel de koppelingssleutel is. Heeft de voorkeur boven `--psk`.	—
`--psk <key>`	Koppelingssleutel op de opdrachtregel. Zichtbaar in `ps` en de shellgeschiedenis — de binary waarschuwt.	—
`--max-jobs <n>`	Harde bovengrens aan het aantal jobs dat dit proces gelijktijdig uitvoert (positief geheel getal).	`4`

De resolutieorde voor de sleutel is --psk-file → CC_WORKER_PSK → --psk. Als je elke bron weglaat, wordt de auth-handshake van de worker overgeslagen; een echte cc_server weigert de sessie dan (auth_denied) in plaats van een ongeauthenticeerde worker te accepteren. Onbekende flags zijn een gebruiksfout (exit 64) — anders dan cc_server gebruikt deze binary package:args en negeert hij typefouten niet.

CC_WORKER_CACHE overschrijft de cachemap voor worktree-materialisatie (standaard: een map cc_worker_cache onder de tijdelijke systeemmap).

De worker registreert zich met fleet.registerWorker, stuurt daarna elke 20 s een hartslag en pollt elke 2 s naar leases. Hij draait tot SIGINT/SIGTERM; zet hem onder systemd of launchd, zodat hij na een crash of herstart opnieuw opstart en zich opnieuw registreert.

Stap 4: Verifieer hem in het fleetpaneel

Open Observeerbaarheid in de desktop- of webapp, schakel over naar het tabblad Live en scroll naar onderen. Workers vermeldt elke geregistreerde worker met zijn platform, cores, capability-sleutels en laatste hartslag; Jobs vermeldt de jobs die erover verdeeld zijn.

Dat je worker daar met een recente hartslag verschijnt, is de bevestiging dat koppeling en registratie zijn gelukt.

Vanaf de tegel van een worker kun je hem Leegmaken (lopende jobs afmaken, geen nieuwe leases aannemen), een worker die aan het leegmaken is Hervatten, zijn referentie Intrekken of de rij Verwijderen.

Worker- en jobrijen staan in global.db van de server — de worker zelf schrijft niets naar schijf buiten de materialisatiecache.

Wat de worker meldt

Bij registratie detecteert de worker zijn mogelijkheden automatisch en matcht de scheduler jobs daaraan. Je configureert deze niet handmatig:

OS en architectuur (macos/linux/windows, arm64/x64) — exacte probes, met terugval op uname -m / PROCESSOR_ARCHITECTURE
Cores en RAM — exact aantal cores; RAM degradeert naar 0 wanneer dat niet te sonderen is
flutter — ingesteld wanneer een Flutter-SDK bereikbaar is (kale flutter, dan fvm flutter); golden-render-jobs vereisen het
sandbox — native-macos op macOS, native-linux op Linux. Dit is een plaatsingshint, geen belofte: de worker meldt de backend die zijn platform heeft, maar hij hult de jobs die hij uitvoert er niet in. Anders dan cc_server start cc_worker een geleasede job rechtstreeks
always-on en parallel — een toegewijde cc_worker meldt beide altijd, zodat hij in aanmerking komt voor eval-batches en andere wegwerpbare parallelle capaciteit

Detectie is best-effort: alles wat hij niet kan sonderen, degradeert naar een veilige standaard in plaats van het opstarten te laten mislukken.

Wat de worker zou uitvoeren

Het lease-protocol draagt zes soorten jobs:

Soort	Wat het is
`agentRun`	Eén enkele agent-run (dispatch)
`pipelineStep`	De uitvoering van één pipelinestap
`codeIndex`	Een build van de code-index van een repo
`goldenRender`	Een visuele golden render van de UI (vereist `flutter`)
`benchmark`	Een prestatiebenchmark
`evalBatch`	Een eval-batch (geeft de voorkeur aan `parallel`-capaciteit)

Uitvoering is een echte implementatie met subprocess-streaming, geen volledige ingebedde agentruntime. Wanneer een lease repoRemote meedraagt, doet de worker git clone --depth 1 naar een cachemap die op remote en SHA is gesleuteld, en daarna git fetch en git checkout. Voor agentRun voert hij het commando in CC_JOB_COMMAND uit de lease-omgeving uit in de werkmap, waarbij stdout en stderr als gebeurtenissen worden teruggestreamd; zonder CC_JOB_COMMAND kaatst hij de prompt terug, zodat het transport toch end-to-end wordt doorlopen. De andere soorten voeren kleine echte commando’s uit (git rev-parse HEAD, git --version) als eerlijke probes. Referenties met jobbereik in de lease-omgeving worden in elk subproces geïnjecteerd en nooit naar een log geschreven.

Gebeurtenissen worden gebundeld en elke 250 ms of elke 32 gebeurtenissen weggeschreven; elke job eindigt met een done-gebeurtenis en een voltooiingsrapport. Het model is hartslagen plus leases met een korte TTL: als een worker het contact verliest, verloopt zijn lease en ruimt de server de job op voor een nieuwe poging. Er is geen duurzame staat op de worker en geen consensus of work-stealing tussen workers.

Gerelateerde gidsen

Gerelateerde concepten

Deployment en clients