Runners: taking one out, and bringing it back
What an administrator does to a runner from Admin → Runners (or spin admin runner), what
each action leaves behind, and how to undo it. The states are
internal/lifecycle’s; placement leaves out every host that is not ACTIVE (refusingPlacement
in internal/controlplane/server/workspaceserver).
| Action | What happens to the host | Its workspaces | Undo |
|---|---|---|---|
| Drain | DRAINING: connected, takes no new workspace | keep running | Activate |
Cordon (an update with --evacuate, a revoke) | CORDONED: the same, by another hand | keep running | Activate |
| Activate | ACTIVE: placement may choose it again | - | - |
| Revoke | credentials deleted, stream cut, CORDONED; its workspaces’ supervisor credentials revoked | refused while any is on it, unless left on purpose | none: a new machine |
Drain is what you want when a runner should stop taking work for a while. Revoke is for a machine that should never connect again - it is being replaced, or it may be compromised: it cannot come back as the same host, and Activate does not undo it.
Nothing starts, and a runner is up
Section titled “Nothing starts, and a runner is up”The control plane says, for every placement it could not make:
WRN SelectHost: no suitable host found connected_hosts=1 outcome=host_takes_no_workand a waiting workspace says “the connected runners take no new workspace”. Every connected host is drained or cordoned. List them and activate the one that should take work:
spin admin runner listspin admin runner activate <runner-id>or Activate runner in the runner’s menu. The next placement chooses it.
Revoking a runner
Section titled “Revoking a runner”A runner that holds any workspace’s disk - running, stopped or failed - is refused, and the refusal names them: revoked, each could run again only by being moved to another runner, giving up what this one had not published. Delete or move them first, or revoke leaving them:
spin admin runner revoke <runner-id> --leave-workspacesOnce revoked, the control plane refuses everything the runner sends, and the runner does not stop trying:
WRN Invalid or expired runner token host_id=<host-id>WRN Request failed ... path=/spin.agent.v1.VolumeService/Heartbeat status=401The host id is burned: its row stays CORDONED and disconnected, and nothing placed will reach it.
Bring the capacity back by giving the installation a new machine, which joins as a new host:
- On AWS, replace the instance in the runners’ group. spin-stack/spin-terraform-aws’s README has the command, under Operating it. The group starts another, which joins by its role.
- Self-hosted, boot the machine again with a new registration token
(
spin admin token create) where its document’sinstall.join.token_atnames it: spin-boot’s join spends it and the host registers again.
If the machine may be compromised, do not reuse its disk.
A workspace on a runner that is gone
Section titled “A workspace on a runner that is gone”A workspace whose runner was revoked or declared dead stops at once - in the record, since nothing runs there any more - and a start of it says to move it. Once a live runner is up, Move to another runner on the workspace’s page, or:
spin workspace recover <workspace>spin workspace recover <workspace> --accept-data-lossThe first changes nothing and says how much its old runner had not published; the second moves it there, and the workspace is stopped, to be started when its owner is ready. A runner that is only restarting is waited for instead, and the workspace comes back with nothing lost.
Setting the installation’s rehome threshold (rehome_after_seconds,
rehome_max_unpublished_bytes) makes the control plane move them itself, under that cost.
Generated by task reference from spin/docs/runners.md at 51f7e0dea.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

