Skip to Content

Self-hosted runners: run the AI agent on your own machines

Run CodeLynq's development work on your own machines - register a runner, install it, run several jobs at once, serve several organizations and keep it up to date.

By default, runs execute on CodeLynq's own infrastructure. With a self-hosted runner, they execute on a machine you control instead: your server, a build machine or a workstation. CodeLynq sends the instructions, the coding agent works on your hardware, the runner pushes the branch, and CodeLynq opens the pull request as usual.

Setting up runners is for organization admins.

What you need

  • A machine with Linux (for example Ubuntu) or macOS.
  • Python 3.9 or newer, and git. The architecture check needs Python 3.10 or newer.
  • The Claude Code CLI (claude), installed and signed in with claude login. If your organization has set its own AI provider key, the runner uses that key instead.
  • If your organization uses Grok or Codex as its coding agent (organization Settings → General), that agent's command-line tool must be installed on the runner too. If it is missing, the run fails with a message saying so.

1. Switch the organization to self-hosted runs

Go to Settings → Runners and, under Run execution, choose Self-hosted (Runs wait for your own runners). Platform (default) switches back.

While no runner has been seen recently, the tab warns that runs will queue until a runner comes online.

2. Register a runner

  1. Under Runners, click Register runner.
  2. Enter a Runner name, for example build-server-1, and click Register runner.
  3. Copy your runner token now: it is shown only once. Click Done.

3. Install the runner

Under Runner setup, the Runners tab shows a one-line install command for your organization. Copy it, replace clr_... with your runner token, and run it on the machine. It looks like this:

curl -fsSL /api/v1/runner/install.sh | bash -s -- \
  --url  --token 

The installer puts the runner in ~/.codelynq-runner, checks for git and the Claude Code CLI, tells you what is missing, and offers to start the runner automatically when the machine boots.

Installed without a token? Finish the setup with codelynq-runner init --url --token . init checks the environment, saves the settings and offers to install the background service.

Once it is running, the runner shows as Online in the list.

What stays on your machine

With self-hosted runs, CodeLynq does not read your code on its own servers. It never clones your repositories and never receives your source files.

Stays on your machine: the clone of your repository, the build, the coding agent's work, your tests and everything the agent runs.

Reaches CodeLynq:

  • tasks, specs, approvals, comments and the audit trail - what you enter in CodeLynq;
  • the structure map your runner makes of the code: file paths, which file imports which, and the names of the classes and functions they declare - not the code itself;
  • the run's log and the agent's summary, so you can follow the run;
  • what your git host reports on the pull request: CI results and review comments, when CodeLynq continues a pull request.

Reaches your AI provider: the coding agent sends the code it works with to the model, as with any coding agent. With your own key (organization Settings), that goes under your contract with the provider.

Some features need a checkout on CodeLynq's side, so they are not available to self-hosted organizations: Analyse repository in the project settings, the go-live and security checks, and Refresh on the architecture map (your runner updates the map at the start of every run instead).

Checks on self-hosted runs

Self-hosted runs go through fewer automatic checks than runs on CodeLynq's infrastructure. Before choosing, compare:

CodeLynq infrastructureSelf-hosted runner
Spec approved before the runYesYes
Verify command with fix attemptsYesNo - the agent gets your testing strategy in its instructions, and your CI tests the pull request
Self-review before PRYesNo
Security scan before PRYesNo
Generate docs in PRsYes, if onNo
Architecture rulesYesYes, from runner 2.0.0 with Python 3.10+
Pull request opened by CodeLynqYesYes
Fixes for failing CI and review commentsYesYes, from runner 1.9.0
Merge automatically once checks passYes, if onYes, if on

See Quality gates for what each check does.

Commands

CommandWhat it does
codelynq-runner initSet up: URL and token, environment check, settings, optional background service
codelynq-runner runRun in the foreground and pick up work
codelynq-runner install-serviceStart the runner automatically at boot (systemd on Linux, launchd on macOS)
codelynq-runner uninstall-serviceRemove that background service
codelynq-runner statusShow the settings, the service state, the connection to CodeLynq and how many jobs it will run
codelynq-runner doctorDiagnose the machine and the connection; doctor --fix installs missing tools
codelynq-runner add-account --name … --token …Let this runner also work for another organization (1.8.0+)
codelynq-runner remove-account --name …Stop working for an added organization
codelynq-runner --versionShow the runner's version

Run several jobs at once

A runner takes one job at a time. To run more side by side, add --max-jobs to init or run:

  • --max-jobs 3 runs up to three jobs.
  • --max-jobs auto lets the runner decide from the machine's CPU cores and memory.

Each job runs a coding agent plus your project's builds and tests, so the runner limits the number to what the machine can handle, and warns when it lowers your number or when disk space is low. If you know your workloads are light, --force-max-jobs skips that limit. init --max-jobs N saves the setting, so the background service uses it too. codelynq-runner status shows how many jobs it will actually run.

Your plan's limit on runs at the same time applies to all your runners together; extra slots simply stay idle.

One runner for several organizations

From version 1.8.0 one machine can work for more than one CodeLynq organization. Register a runner in each organization (step 2) to get its token, then add it on the machine:

codelynq-runner add-account --name acme --token 

The runner checks the token before saving it. Restart the runner or its service afterwards; codelynq-runner status lists every organization and its connection. To stop working for one, run codelynq-runner remove-account --name acme.

  • The token you entered during init stays the first organization.
  • The runner asks each organization for work in turn, and all of them share --max-jobs, so a busy organization cannot keep the others waiting while a slot is free.
  • Every job talks to CodeLynq with its own organization's token, and each organization's repository cache is kept apart.
  • If an organization revokes its runner, only that organization drops out; the others keep working.

Only combine organizations that trust each other, for example your own companies. All jobs run as the same user on the machine, so a coding agent in one organization's job could read the other organizations' tokens, workspaces and cache. Organizations that must stay separate each need their own runner, under its own user account or in its own container.

Keeping large repositories on the machine

Each job normally downloads the repository from scratch. For large repositories that is most of the wait. From version 1.7.0 the runner can keep a copy of every repository it works on and download only what changed:

codelynq-runner init --repo-cache      # saves the setting, also for the service

The copies hold each repository's full history, so plan the disk space; CODELYNQ_CACHE_DIR chooses where they live. Deleting that folder is always safe: the next job builds it again. Jobs share the cache, so use it on a runner that only works for organizations you trust.

Stopping a runner

Press Ctrl-C once: the runner stops taking new work and lets the jobs in progress finish. Press it again to stop those jobs too - they are reported as failed. A run you cancel in CodeLynq stops on the runner within about a minute.

Upgrading

Run the install command again, without a token:

curl -fsSL /api/v1/runner/install.sh | bash

It replaces the installed version, keeps your settings and restarts the background service if the runner has one. A runner you started with codelynq-runner run in a terminal: stop it and start it again. Runs in progress finish first.

Not sure the runner is on the new version? The Runners tab shows the version each runner reported. A runner that shows no version has never connected: finish its setup with codelynq-runner init --url --token .

Tasks that span several repositories or branches need runner version 1.4.0 or newer. Older runners keep working on everything else and leave those runs to a runner that can handle them. If none of your runners is new enough, CodeLynq does not start such a run and asks you to upgrade. See Work on several branches at once.

Several organizations on one runner need version 1.8.0, the repository cache 1.7.0. Older runners keep working for the organization they were set up for.

The architecture check needs runner version 2.0.0 or newer, on Python 3.10 or newer. Before pushing, the runner reads the structure of the files its agent changed - which files they import and what they declare, not the code - and sends that to CodeLynq, which checks it against your architecture rules and, in Fix mode, has the agent restructure the change. The installer adds the parser this takes; if it cannot (for example without internet access to PyPI), the runner works without the check. Older runners get your architecture in their instructions, but their changes are not checked and their pull requests have no Structure changes section. Runners 1.5 to 1.9 sent the changed source files for this check; CodeLynq no longer asks them to, so upgrade to keep the check.

Manage runners

The Runners list shows each runner with:

  • Online or Offline, and when it was last seen,
  • Active or Revoked,
  • the machine's host name and the runner's version,
  • its capacity, for example 1 job at a time or Running 2 of 3 jobs.

Click Revoke to retire a runner; its token stops working immediately. Runs on your own runner carry a Self-hosted runner badge.

If runs stay queued, check that a runner is online and run codelynq-runner doctor on the machine. A run that makes no progress for hours also shows up in the Inbox as Run stuck.

Test it on a task from your own backlog

Send us one real task. We run CodeLynq on your repository and you review the pull request. Free, within 5 working days of approving the spec.