Operating hosts
Runners are also called hosts. An administrator manages them in Admin → Runners or with
spin admin runner. For how runners join, scale and go away, see
Runners and hosts.
Seeing them
Section titled “Seeing them”spin admin runner listspin admin versions # the control plane's release, and each runner's and its machine'sspin admin versions says what is running where. A runner’s page in the dashboard shows its
state, its capacity and its workspaces.
Drain and activate
Section titled “Drain and activate”spin admin runner drain <runner-id> # takes no new workspace; the running ones stayspin admin runner drain <runner-id> --suspend # and moves the running ones off, with memoryspin admin runner activate <runner-id>Drain a runner that should stop taking work for a while. It stays drained until someone activates it. If workspaces wait for a host while a runner is up, check that the runner is not drained: the waiting workspace says the connected runners take no new workspace.
A runner whose local disk is more than 70% full is cordoned automatically, and uncordoned when it falls under 65%. The automatic cordon never clears one a person set.
Revoke
Section titled “Revoke”spin admin runner revoke <runner-id>Revoke is for a machine that should never connect again, and cannot be undone. Taking a runner out, and bringing it back says what each action leaves behind, what a revoke refuses, and how the capacity comes back.
Replacing a runner’s machine on AWS
Section titled “Replacing a runner’s machine on AWS”A runner of the group that should go for good is given back to it, which terminates the machine and is asked for one less. It drains as it goes, and one that is the only home of a workspace’s disk is refused, naming them:
spin admin runner remove <runner-id>spin admin runner remove <runner-id> --taken--taken is for a machine that may be compromised: its credentials are deleted and it is cut off
before its group is asked anything, and every disk whose key it was given is marked for re-keying,
as a revoke does. With --leave-workspaces as well, it goes even where workspaces’ disks are only
there; each of those runs again only once it is recovered onto another runner.
After a revoke, or when a runner is wedged, terminate its instance without lowering the group’s size. The group starts another, which joins by its role:
aws autoscaling describe-auto-scaling-instances \ --query 'AutoScalingInstances[?AutoScalingGroupName==`<name>-runners`].[InstanceId,LifecycleState,HealthStatus]' \ --output tableaws autoscaling terminate-instance-in-auto-scaling-group \ --instance-id <i-...> --no-should-decrement-desired-capacityIf nothing is waiting for a host, the control plane may already have scaled the group to zero, and there is nothing to replace.
Workspaces on a runner that is gone
Section titled “Workspaces on a runner that is gone”A workspace whose runner was revoked or is gone stops, in the record, and its owner moves it: see A workspace on a runner that is gone. The thresholds that let the control plane move them on its own are in the installation settings.
A runner outside the group
Section titled “A runner outside the group”A machine that is not in the autoscaling group joins with a registration token:
spin admin token create --description "lab machine" --expires 1hA token is one-time unless --reusable, lasts 24 hours unless --expires says otherwise (at
most 30 days), and is shown once. --team makes a runner that only takes the team’s workspaces.
The same flags set what the runner advertises and whether it is preemptible.
Such a machine needs KVM, and must run the control plane’s release of Spinbox: a host of any other is refused, and the refusal says so.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

