Skip to Content

Self-hosted runners: de AI-agent op je eigen machines

Laat het ontwikkelwerk van CodeLynq op je eigen machines draaien - registreer een runner, installeer hem, draai meerdere jobs tegelijk, laat hem voor meerdere organisaties werken en houd hem up-to-date.

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 met claude 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

  1. Klik onder Runners op Runner registreren.
  2. Vul een Naam van de runner in, bijvoorbeeld build-server-1, en klik op Runner registreren.
  3. 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 --token . 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 CodeLynqEigen runner
Spec goedgekeurd vóór de runJaJa
Verificatiecommando met herstelpogingenJaNee - de agent krijgt je teststrategie mee in zijn instructies, en je CI test de pull request
Zelfreview vóór de PRJaNee
Beveiligingsscan vóór de PRJaNee
Documentatie bijwerken in PR'sJa, als het aanstaatNee
ArchitectuurregelsJaJa, vanaf runner 2.0.0 met Python 3.10+
Pull request geopend door CodeLynqJaJa
Herstel bij falende CI en reviewopmerkingenJaJa, vanaf runner 1.9.0
Automatisch mergen zodra de checks slagenJa, als het aanstaatJa, als het aanstaat

Zie Kwaliteitscontroles voor wat elke controle doet.

Commando's

CommandoWat het doet
codelynq-runner initInstellen: URL en token, controle van de omgeving, instellingen, optioneel een achtergrondservice
codelynq-runner runOp de voorgrond draaien en werk oppakken
codelynq-runner install-serviceDe runner automatisch starten bij het opstarten (systemd op Linux, launchd op macOS)
codelynq-runner uninstall-serviceDie achtergrondservice weer verwijderen
codelynq-runner statusDe instellingen tonen, de status van de service, de verbinding met CodeLynq en hoeveel jobs hij tegelijk draait
codelynq-runner doctorDe 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 --versionDe 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 3 draait tot drie jobs tegelijk.
  • --max-jobs auto laat 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 init invoerde, 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 --token .

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.

Test het op een taak uit je eigen backlog

Stuur ons één echte taak. Wij draaien CodeLynq op jouw repository en jij reviewt de pull request. Gratis, binnen 5 werkdagen nadat je de spec hebt goedgekeurd.