Standaard draaien runs op de infrastructuur van CodeLynq zelf. Met een self-hosted runner draaien ze op een machine die jij beheert: je server, een buildmachine of een werkstation. CodeLynq stuurt de instructies, de coding agent werkt op jouw hardware, de runner pusht de branch, en CodeLynq opent zoals altijd de pull request.
Runners instellen is voor beheerders van de organisatie.
De runner is een commandoregeltool in het Engels; de commando's hieronder typ je zoals ze er staan.
Wat je nodig hebt
- Een machine met Linux (bijvoorbeeld Ubuntu) of macOS.
- Python 3.9 of nieuwer, en git. De architectuurcontrole heeft Python 3.10 of nieuwer nodig.
- De Claude Code CLI (
claude), geïnstalleerd en ingelogd metclaude login. Heeft je organisatie een eigen API-sleutel van de AI-provider ingesteld, dan gebruikt de runner die sleutel. - Gebruikt je organisatie Grok of Codex als coding agent (Instellingen van de organisatie → Algemeen), dan moet ook de commandoregeltool van die agent op de runner staan. Ontbreekt die, dan mislukt de run met een melding daarover.
1. Zet de organisatie op self-hosted runs
Ga naar Instellingen → Runners en kies onder Uitvoering van runs voor Self-hosted (Runs wachten op je eigen runners). Met Platform (standaard) zet je het terug.
Is er recent geen runner gezien, dan waarschuwt het tabblad dat runs in de wachtrij blijven staan tot er een runner online komt.
2. Een runner registreren
- Klik onder Runners op Runner registreren.
- Vul een Naam van de runner in, bijvoorbeeld
build-server-1, en klik op Runner registreren. - Kopieer nu je runnertoken: het wordt maar één keer getoond. Klik op Klaar.
3. De runner installeren
Onder Runner-installatie toont het tabblad Runners een installatiecommando van één regel voor je organisatie. Kopieer het, vervang clr_... door je runnertoken en voer het uit op de machine. Het ziet er zo uit:
curl -fsSL /api/v1/runner/install.sh | bash -s -- \
--url --token
Het installatiescript zet de runner in ~/.codelynq-runner, controleert of git en de Claude Code CLI aanwezig zijn, vertelt je wat er ontbreekt en biedt aan de runner automatisch te starten als de machine opstart.
Geïnstalleerd zonder token? Rond de installatie af met codelynq-runner init --url . init controleert de omgeving, slaat de instellingen op en biedt aan de achtergrondservice te installeren.
Zodra de runner draait, staat hij als Online in de lijst.
Wat er op je machine blijft
Bij self-hosted runs leest CodeLynq je code niet op zijn eigen servers. Het kloont je repositories nooit en ontvangt je bronbestanden nooit.
Blijft op je machine: de clone van je repository, de build, het werk van de coding agent, je tests en alles wat de agent uitvoert.
Komt bij CodeLynq:
- taken, specs, goedkeuringen, opmerkingen en de audittrail - wat je zelf in CodeLynq invoert;
- de structuurkaart die je runner van de code maakt: bestandspaden, welk bestand welk ander bestand importeert en de namen van de klassen en functies die erin staan - niet de code zelf;
- het log van de run en de samenvatting van de agent, zodat je de run kunt volgen;
- wat je git-host over de pull request meldt: CI-resultaten en reviewopmerkingen, als CodeLynq verder werkt aan een pull request.
Komt bij je AI-provider: de coding agent stuurt de code waarmee hij werkt naar het model, zoals elke coding agent. Met een eigen sleutel (Instellingen van de organisatie) valt dat onder jouw contract met de provider.
Een paar functies hebben een checkout aan de kant van CodeLynq nodig en zijn daarom niet beschikbaar voor self-hosted organisaties: Repository analyseren in de projectinstellingen, de go-live- en beveiligingschecks, en Vernieuwen op de architectuurkaart (je runner werkt de kaart in plaats daarvan bij aan het begin van elke run).
Controles bij self-hosted runs
Self-hosted runs doorlopen minder automatische controles dan runs op de infrastructuur van CodeLynq. Vergelijk ze voordat je kiest:
| Infrastructuur van CodeLynq | Eigen runner | |
|---|---|---|
| Spec goedgekeurd vóór de run | Ja | Ja |
| Verificatiecommando met herstelpogingen | Ja | Nee - de agent krijgt je teststrategie mee in zijn instructies, en je CI test de pull request |
| Zelfreview vóór de PR | Ja | Nee |
| Beveiligingsscan vóór de PR | Ja | Nee |
| Documentatie bijwerken in PR's | Ja, als het aanstaat | Nee |
| Architectuurregels | Ja | Ja, vanaf runner 2.0.0 met Python 3.10+ |
| Pull request geopend door CodeLynq | Ja | Ja |
| Herstel bij falende CI en reviewopmerkingen | Ja | Ja, vanaf runner 1.9.0 |
| Automatisch mergen zodra de checks slagen | Ja, als het aanstaat | Ja, als het aanstaat |
Zie Kwaliteitscontroles voor wat elke controle doet.
Commando's
| Commando | Wat het doet |
|---|---|
codelynq-runner init | Instellen: URL en token, controle van de omgeving, instellingen, optioneel een achtergrondservice |
codelynq-runner run | Op de voorgrond draaien en werk oppakken |
codelynq-runner install-service | De runner automatisch starten bij het opstarten (systemd op Linux, launchd op macOS) |
codelynq-runner uninstall-service | Die achtergrondservice weer verwijderen |
codelynq-runner status | De instellingen tonen, de status van de service, de verbinding met CodeLynq en hoeveel jobs hij tegelijk draait |
codelynq-runner doctor | De machine en de verbinding controleren; doctor --fix installeert ontbrekende tools |
codelynq-runner add-account --name … --token … | Deze runner ook laten werken voor een andere organisatie (1.8.0+) |
codelynq-runner remove-account --name … | Stoppen met werken voor een toegevoegde organisatie |
codelynq-runner --version | De versie van de runner tonen |
Meerdere jobs tegelijk draaien
Een runner voert één job tegelijk uit. Wil je er meer naast elkaar draaien, voeg dan --max-jobs toe aan init of run:
--max-jobs 3draait tot drie jobs tegelijk.--max-jobs autolaat de runner zelf bepalen op basis van de CPU-kernen en het geheugen van de machine.
Elke job draait een coding agent plus de builds en tests van je project, dus de runner beperkt het aantal tot wat de machine aankan. Hij waarschuwt als hij je getal verlaagt of als de schijfruimte krap wordt. Weet je dat je werk licht is, dan slaat --force-max-jobs die beperking over. init --max-jobs N slaat de instelling op, zodat de achtergrondservice hem ook gebruikt. codelynq-runner status toont hoeveel jobs hij echt tegelijk draait.
De limiet van je abonnement op gelijktijdige runs geldt voor al je runners samen; extra plekken blijven dan gewoon leeg.
Eén runner voor meerdere organisaties
Vanaf versie 1.8.0 kan één machine voor meer dan één CodeLynq-organisatie werken. Registreer in elke organisatie een runner (stap 2) voor het token, en voeg het daarna toe op de machine:
codelynq-runner add-account --name acme --token
De runner controleert het token voordat hij het opslaat. Herstart daarna de runner of de service; codelynq-runner status toont elke organisatie en haar verbinding. Wil je stoppen voor een organisatie, gebruik dan codelynq-runner remove-account --name acme.
- Het token dat je bij
initinvoerde, blijft de eerste organisatie. - De runner vraagt om de beurt bij elke organisatie werk op, en ze delen samen
--max-jobs. Een drukke organisatie kan de andere dus niet laten wachten zolang er een plek vrij is. - Elke job praat met CodeLynq via het token van zijn eigen organisatie, en de repository-cache van elke organisatie staat apart.
- Trekt een organisatie haar runner in, dan valt alleen die organisatie weg; de andere werken gewoon door.
Combineer alleen organisaties die elkaar vertrouwen, bijvoorbeeld je eigen bedrijven. Alle jobs draaien als dezelfde gebruiker op de machine, dus een coding agent in een job van de ene organisatie zou de tokens, werkmappen en cache van de andere organisaties kunnen lezen. Organisaties die gescheiden moeten blijven, krijgen elk een eigen runner, onder een eigen gebruikersaccount of in een eigen container.
Grote repositories op de machine bewaren
Normaal downloadt elke job de repository opnieuw. Bij grote repositories is dat het grootste deel van de wachttijd. Vanaf versie 1.7.0 kan de runner van elke repository waar hij aan werkt een kopie bewaren en alleen de wijzigingen ophalen:
codelynq-runner init --repo-cache # slaat de instelling op, ook voor de service
De kopieën bevatten de volledige geschiedenis van elke repository, dus houd rekening met schijfruimte; met CODELYNQ_CACHE_DIR kies je waar ze staan. Die map verwijderen is altijd veilig: de volgende job bouwt hem opnieuw op. Jobs delen de cache, dus gebruik hem op een runner die alleen werkt voor organisaties die je vertrouwt.
Een runner stoppen
Druk één keer op Ctrl-C: de runner neemt geen nieuw werk meer aan en laat lopende jobs afmaken. Druk nog een keer om ook die te stoppen - ze worden dan als mislukt gemeld. Een run die je in CodeLynq stopt, stopt binnen ongeveer een minuut ook op de runner.
Bijwerken
Voer het installatiecommando opnieuw uit, zonder token:
curl -fsSL /api/v1/runner/install.sh | bash
Dat vervangt de geïnstalleerde versie, houdt je instellingen aan en herstart de achtergrondservice als de runner er een heeft. Heb je de runner met codelynq-runner run in een terminal gestart, stop hem dan en start hem opnieuw. Lopende runs worden eerst afgemaakt.
Twijfel je of de runner op de nieuwe versie draait? Het tabblad Runners toont de versie die elke runner doorgaf. Staat er geen versie, dan heeft de runner nooit verbinding gemaakt: maak de installatie af met codelynq-runner init --url .
Taken die meerdere repositories of branches beslaan, hebben runnerversie 1.4.0 of nieuwer nodig. Oudere runners blijven al het andere werk doen en laten zulke runs over aan een runner die ze aankan. Is geen van je runners nieuw genoeg, dan start CodeLynq zo'n run niet en vraagt het je om bij te werken. Zie Op meerdere branches tegelijk werken.
Meerdere organisaties op één runner vragen versie 1.8.0, de repository-cache 1.7.0. Oudere runners blijven werken voor de organisatie waarvoor ze zijn ingesteld.
De architectuurcontrole heeft runnerversie 2.0.0 of nieuwer nodig, op Python 3.10 of nieuwer. Voordat de runner pusht, leest hij de structuur van de bestanden die zijn agent heeft gewijzigd - welke bestanden ze importeren en wat erin gedeclareerd staat, niet de code - en stuurt die naar CodeLynq. Dat controleert de structuur tegen je architectuurregels en laat de agent in de modus Herstellen de wijziging herstructureren. De installer voegt de parser toe die daarvoor nodig is; lukt dat niet (bijvoorbeeld zonder internettoegang tot PyPI), dan werkt de runner zonder de controle. Oudere runners krijgen je architectuur mee in hun instructies, maar hun wijzigingen worden niet gecontroleerd en hun pull requests hebben geen sectie Structure changes. Runners 1.5 tot en met 1.9 stuurden voor deze controle de gewijzigde bronbestanden; CodeLynq vraagt daar niet meer om, dus werk bij om de controle te houden.
Runners beheren
De lijst Runners toont per runner:
- Online of Offline, en wanneer hij voor het laatst is gezien,
- Actief of Ingetrokken,
- de hostnaam van de machine en de versie van de runner,
- de capaciteit, bijvoorbeeld 1 job tegelijk of Voert 2 van 3 jobs uit.
Klik op Intrekken om een runner buiten gebruik te stellen; het token werkt dan meteen niet meer. Runs op je eigen runner hebben het label Self-hosted runner.
Blijven runs in de wachtrij staan, controleer dan of er een runner online is en voer codelynq-runner doctor uit op de machine. Een run die urenlang niet verder komt, verschijnt ook in de inbox als Run vastgelopen.