Runner installation

The Delego runner is a lightweight CLI process that runs on your own hardware. It is the only part of Delego that actually executes code — the relay in the cloud coordinates work, but the runner is what opens the worktree, invokes the agent, and pushes the result.

Why it runs on your machine

The runner is intentionally local. When a job starts, the runner shells out to whichever coding agent you have installed — Claude Code or Codex — using your own authenticated session, exactly the same way you'd run it by hand in a terminal. Your credentials never leave your machine and no model traffic passes through the relay.

This design has a few practical consequences:

• Your subscriptions stay safe. Because the agent runs as your own terminal process, there is nothing for the provider to distinguish from ordinary local use. Claude Code and Codex subscriptions work exactly as intended.
• You control the environment. The runner inherits your shell environment, your SSH keys, your GitHub auth, your installed tools. If something works on your machine by hand, it will work through the runner too.
• Each job gets an isolated workspace. The runner creates a fresh git worktree for every job, so it never touches your current branch or uncommitted changes. When the job finishes, the worktree is cleaned up.

Where the runner can run

The runner is a Node.js process. It can run on anything that supports Node 20 or newer and can reach the relay over HTTPS:

• Your main development laptop.
• A spare or older machine you have available.
• A home server running continuously.
• A VPS or cloud VM.

The machine does not need to be publicly accessible — the runner polls the relay, so only outbound HTTPS from the runner to the relay is required.

Running multiple runners

Each runner process handles one job at a time. If you want jobs to run in parallel, start multiple runner processes. You can pair as many runners as you like to a single Delego account — each one shows up in the dashboard independently with its own status and heartbeat.

Runners can be on the same machine (as separate processes or terminal sessions) or spread across multiple machines. The relay claims jobs across runners using a lock that prevents two runners from picking up the same job simultaneously, so parallel execution is safe with no extra configuration.

Prerequisites

The runner itself is a thin orchestrator. The tools it shells out to must be installed and authenticated on the same machine.

Node.js 20 or newer. The runner is published on npm as @delegoapp/runner and executes on Node.

A coding agent — Claude Code or Codex — already authenticated in your terminal. The runner invokes whichever one is selected by the executor label on the Linear issue. You only need to install the agent(s) you plan to use.

GitHub CLI (gh), authenticated. Delego uses gh to push branches and open pull requests on your behalf.

Git. Used to create the worktrees that jobs run in.

Pairing the runner

Once the prerequisites are in place, go to Runners → Add runner in the dashboard. The dashboard generates a one-time pairing command that looks like:

npx -y @delegoapp/runner@latest --relay-url <relay> --pairing-token drs_pair_… --profile <profile> --supported-executors <codex,claude> --background

Run this command on the machine where you want jobs to execute. The runner registers itself with the relay, stores the resulting bearer token locally, and begins polling for jobs. The pairing token is single-use and expires after 15 minutes — if it expires before you run the command, generate a new one from the dashboard.

Running as a background service

The pairing command includes --background (shortcut -b) by default, which registers the runner as an OS-level service instead of a foreground process:

• macOS — a launchd LaunchAgent (~/Library/LaunchAgents).
• Linux — a systemd user unit (~/.config/systemd/user).

The service restarts automatically on crash and on reboot, and it always launches @delegoapp/runner@latest — so upgrading the runner is just restarting it. This is what powers the Upgrade button on the Runners panel: when the dashboard requests a restart, the runner exits cleanly and the OS service relaunches it on the newest version.

A runner started without --background still works, but stays in the foreground: it needs its terminal to stay open, and an upgrade requires you to stop and re-run it by hand.

Managing the service

Once paired, delego-runner (or npx @delegoapp/runner) accepts these subcommands, which act on the OS service and don't need --relay-url:

uninstall, remove, and clear require --yes because they're unrecoverable — the runner is revoked on the relay, so resuming afterwards needs a fresh pairing token from the dashboard. If the relay can't be reached when one of these runs, the revoke is skipped with a warning but local cleanup (service + credentials) still completes — remove the runner manually from the dashboard in that case.

If you only want to pause a runner without losing its pairing, use stop; you can bring it back later with start. After uninstall or remove, pair the runner again from the dashboard to create fresh credentials and reinstall the background service.