Skip to main content

​
Runners

​
What it is

A runner is a host that runs your fleets. It takes work from agentsfleetd, runs it inside a sandbox, and reports the result back. You enrol every runner from the dashboard. The host holds one token and nothing else. It never holds a database credential, a cache credential, or vault access.

​
Why it exists

Fleet code has to run on a machine somewhere. Keeping that machine outside the control plane means a compromised host cannot read another tenant’s data. Runners are replaceable. When one stops answering, its unfinished work goes to another runner, so no event is lost.

​
How it behaves

​
Enrolling a host

Open Admin → Runners → Add runner and fill in the policy. agentsfleetd mints a runner token and shows it once. Copy it before you close the dialog, because it is never shown again. Put that token on the host, then start agentsfleet-runner. The host reads two required variables and one optional variable: No policy value is read from the host. A runner that carried its own isolation setting could disagree with the dashboard, and nothing would compare the two.

​
The policy you assign

Policy travels down from the dashboard. Change it under Admin → Runners → Edit policy and the host applies it on its next heartbeat. Nobody logs in to the host. The three isolation settings differ in what enforces the boundary:

​
The states a runner shows

The runner page shows two facts side by side: what you have told the runner to do, and whether the host is answering. The first is the admin state. You set it with the actions below. It moves on its own in one case only: a draining runner becomes drained once its last lease finishes. The second is liveness. The host reports it through its heartbeat; you cannot set it.

​
When a runner stops taking work

A runner reports what its kernel can actually enforce on every heartbeat. agentsfleetd compares that report against the policy you assigned. When the host cannot meet the assignment, the runner is marked degraded and is sent no work. The reason names the one missing piece, such as cgroup controllers not delegated. Fix that piece, or lower the assignment, and the next heartbeat clears the mark. The runner page carries the verdict of those checks beside the runner’s state and labels. It reads checks passed, N checks failed, checks stale, checks pending, or checks never run. Select it to read the full report, check by check. You can also stop a runner deliberately:
  • Cordon stops new work reaching it.
  • Drain lets its current work finish, then leaves it idle.
  • Revoke ends its token, so the host’s next request is refused.
A runner that simply disappears needs no action. Its work expires and another runner takes it. Work already reported is never run twice.

​
Limits

  • Allowlist egress is not enforced yet. A runner assigned it reads degraded and takes no work until that enforcement ships. Use No egress or Allow all egress today.
  • None is refused outside development. A release build of agentsfleetd rejects it at startup.
  • Raising Workers past the count the host started with needs a restart. Lowering it takes effect on the next heartbeat.
  • A host can lie about what it enforces. The capability report is self-declared, so treat placement as something you decide, not something the host proves.