The runner fleet

SupaCloud runs each agent task inside its own container. By default that container runs on the same machine as the SupaCloud server — the single-host deployment, which is all most installs ever need. The runner fleet is the opt-in mode where that work is instead dispatched to one or more separate machines (“runners” / “worker nodes”) that pull jobs from the server.

You probably do not need this yet

A single host happily runs many agents at once. Reach for the runner fleet only when you have a concrete reason: agent work competing with the web server for CPU/RAM, a machine with a GPU or a special toolchain, or compute contributed by a third party. With hub mode off (the default) a deployment behaves exactly as if the fleet did not exist.

The model: pull, not push

A runner is outbound-only. It opens an HTTPS connection to the server, authenticates with its own bearer token, and asks “is there work for me?” The server never connects back to the runner, so a runner works behind NAT, a home router, or a corporate proxy with no inbound ports to open. When a runner claims a job the server hands back a self-contained launch payload — the resolved image, environment and per-run secrets for that one task — which the runner runs to completion and streams the live events back. The runner holds no copy of the server’s database and no long-lived platform secrets.

How dispatch chooses a runner

When hub mode is on and a task launches, the server picks a runner with a single decision function. Out of the box that is simply “the first online runner whose advertised capabilities fit the task’s image.” Everything beyond that is an opt-in lever layered on top, each one off by default so a zero-config fleet keeps the simple behaviour:

• Capabilities & labels — a runner advertises the images it can run and free-form labels (e.g. gpu, eu-west); a task can require a label subset.
• Drain / cordon — quiesce a runner gracefully: it finishes its in-flight work but receives nothing new, so you can upgrade or retire a node without killing running tasks.
• Concurrency cap — a runner advertises how many tasks it will run at once; the server stops sending more once it is full.
• Least-loaded + weight — when enabled, send each new task to the least-busy runner, with a weight so a bigger machine absorbs proportionally more.
• Priority — a higher-priority task is claimed ahead of others waiting in a runner’s queue.
• Pin — force a specific task onto a specific runner; if that runner is busy or offline the task waits for it (rather than silently running elsewhere).

Admins configure these — see the admin how-to Steer & monitor runners. As a user you rarely think about them: you launch a task, and it runs.

Reliability

The server tracks each runner’s heartbeat. A runner that goes quiet past a bounded window is marked offline and is no longer selected, and any work it had accepted but never started is re-surfaced so it is not stuck behind a dead machine. Live events from a remote run flow into the same event log a local run uses, with secrets redacted on the way in, so the task timeline looks identical whether it ran next to the server or on a runner three time zones away.

A naming clash to know about

“Runner fleet” unfortunately names two unrelated things in SupaCloud:

1. The task-runner fleet — this page: separate machines that run agent tasks.
2. The connector runner_fleet placement — an execution-placement option for marketplace connector / script Wasm, where that sandboxed code runs on a connector-capable runner instead of in the server process.

They share the runner registry and the pull transport but are otherwise separate features. When this documentation says “runner fleet” unqualified, it means the task-runner fleet above.