Runners
The runners panel — how to pair new runners, understand runner status, manage credentials, and set workspace-level executor defaults.
The Runners panel (/home/runners) lists every CLI agent paired to your account and lets you manage them. A runner must be online and healthy for jobs to be executed — if no runners are paired or all are offline, jobs will queue indefinitely.
Runner status
Each runner card shows a status pill that reflects the most recent heartbeat:
| Status | Meaning |
|---|---|
| Online | The runner is actively heartbeating and ready to accept jobs. |
| Stale | The runner sent a recent heartbeat but has not been heard from for a short while. It may be restarting or temporarily unavailable. |
| Offline | The runner has not heartbeated for an extended period. It is likely stopped. |
| Revoked | The runner's credentials have been revoked. It cannot accept jobs until re-paired. |
| Not registered | A pairing token was issued but the runner CLI has not completed registration yet. |
Runner cards
Each card shows:
- Display name — the name you gave the runner when pairing.
- Runner ID — the internal identifier in monospace, shown beneath the name.
- Status pill — one of the states above.
- Heartbeat — the exact date and time of the last heartbeat, or
—if the runner has never heartbeated. - Version — the
@delegoapp/runnerpackage version the runner is running. A small badge appears next to it when a newer version has been published to npm. - Supported executors — pills showing which agents (Claude Code, Codex) this runner can run. A runner only picks up jobs whose executor matches its declared capabilities.
Pairing a new runner
Click the Pair button in the top-right corner of the panel. A dialog opens with two fields:
- Display name — a label to help you identify this runner in the list (e.g.
laptop,home-server). Maximum 120 characters. - Supported executors — checkboxes to declare which agents this runner has installed: Codex, Claude Code, or both.
After submitting, the dialog shows the one-time pairing command to run on the target machine:
npx -y @delegoapp/runner@latest --relay-url <relay> --pairing-token drs_pair_… --profile <profile> --supported-executors <codex,claude> --background
Copy and run this command on the machine where you want jobs to execute. The pairing token is single-use and expires after 15 minutes. If it expires, close the dialog and pair again — a new token will be issued.
The --background flag (shortcut -b) registers the runner as an OS-level background service (launchd on macOS, systemd on Linux) so it survives reboots and crashes — see Runner installation for how to manage it. Once the runner completes registration, its card will appear in the list and its status will update to Online on the next heartbeat.
Managing existing runners
Each runner card has an actions menu:
Upgrade — only shown when the runner's version is behind the latest published @delegoapp/runner release. Requests a restart from the dashboard; the runner picks this up on its next heartbeat, exits cleanly, and its background service relaunches it on the latest version. Only works for runners started with --background — a runner running in the foreground just prints a message and exits, and needs to be started again by hand.
Rotate — issues a new bearer token to the runner. The runner's current token is invalidated immediately. Use this if you suspect the credentials have been compromised or if the runner is behaving unexpectedly. After rotating, the runner must be re-paired using the new pairing command shown in the dialog.
Remove — permanently removes the runner from your account and revokes its credentials. Running jobs claimed by this runner will fail. You can do the same thing from the runner's machine with delego-runner uninstall --yes (or remove, an alias) — see Runner installation for the CLI's service-management commands.
Workspace settings
Both workspace-level settings live under Relay Settings.
Default executor — the agent used for jobs that carry no executor label. Set this to avoid labelling every issue by hand.
Workspace path — the directory on the runner machine where repositories are cloned. Defaults to ~/delego-runner/workspace when not set. This path is baked into the pairing command the dashboard generates, so if you change it you will need to re-pair any runners that should use the new location.