Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

Runners: taking one out, and bringing it back

View Markdown

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).

ActionWhat happens to the hostIts workspacesUndo
DrainDRAINING: connected, takes no new workspacekeep runningActivate
Cordon (an update with --evacuate, a revoke)CORDONED: the same, by another handkeep runningActivate
ActivateACTIVE: placement may choose it again--
Revokecredentials deleted, stream cut, CORDONED; its workspaces’ supervisor credentials revokedrefused while any is on it, unless left on purposenone: 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.

The control plane says, for every placement it could not make:

WRN SelectHost: no suitable host found connected_hosts=1 outcome=host_takes_no_work

and 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:

Terminal window
spin admin runner list
spin admin runner activate <runner-id>

or Activate runner in the runner’s menu. The next placement chooses it.

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:

Terminal window
spin admin runner revoke <runner-id> --leave-workspaces

Once 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=401

The 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’s install.join.token_at names 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 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:

Terminal window
spin workspace recover <workspace>
spin workspace recover <workspace> --accept-data-loss

The 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.