spin admin

Administrative commands for managing runners and registration tokens.

These commands require admin privileges.

Usage:
  spin admin [flags]
  spin admin [command]

Available Commands:
  costs       What the installation cost this month, by service, its forecast and its budget
  jobs        The control plane's periodic work, and running a job now
  logs        Search what the installation's processes logged
  runner      Manage registered runners
  storage     What the object store holds, and taking out what nothing needs
  token       Manage runner registration tokens
  versions    What is running where: this control plane, each runner and its machine
  volume      Re-key a workspace's disk

Flags:
  -h, --help   help for admin

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin [command] --help" for more information about a command.

spin admin costs

What the installation cost in a month, as its cloud's bill says, by service; what the month
is forecast to end at, and its budget. As the control plane last read the bill - a few times a day -
never the cloud itself.

Usage:
  spin admin costs [flags]
  spin admin costs [command]

Available Commands:
  by          What each workspace, team or owner cost this month, and what nobody did

Flags:
  -h, --help           help for costs
      --month string   the month, as 2026-10 (default: this month)

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin costs [command] --help" for more information about a command.

spin admin costs by

A month of the bill shared out: the runners by what each workspace held of them - cores and
memory, half each - and the volumes' bucket by what its volumes kept. What nobody caused is said
apart and never spread: the runners' capacity nobody held (idle), the bucket's bytes no workspace
keeps (images, unreferenced), and the platform's own cost by service.

Usage:
  spin admin costs by <workspace|team|owner> [flags]

Flags:
  -h, --help           help for by
      --month string   the month, as 2026-10 (default: this month)

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin jobs

The control plane's periodic work, and running a job now

Usage:
  spin admin jobs [flags]
  spin admin jobs [command]

Available Commands:
  list        Every job, how often it runs and how its last run went
  run         Run a job now rather than when it is next due

Flags:
  -h, --help   help for jobs

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin jobs [command] --help" for more information about a command.

spin admin jobs list

Every job, how often it runs and how its last run went

Usage:
  spin admin jobs list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin jobs run

Run a job now rather than when it is next due. It is not waited for: spin admin jobs list
says how it went. Refused while it is running.

Usage:
  spin admin jobs run <job> [flags]

Flags:
  -h, --help   help for run

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin logs

Search what the control plane, the proxy and the runners logged, newest first.

The query is Quickwit's query language; empty is everything in the window.

Examples:
  spin admin logs
  spin admin logs 'severity_text:error' --since 24h
  spin admin logs 'service_name:runner AND body.message:"no host"' --limit 20

Usage:
  spin admin logs [query] [flags]

Flags:
  -h, --help             help for logs
      --limit int32      how many records, newest first: 1 to 1000 (default 100)
      --since duration   how far back to look, at most 744h (31 days) (default 1h0m0s)

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin runner

Manage registered runners

Usage:
  spin admin runner [flags]
  spin admin runner [command]

Available Commands:
  activate    Let a drained or cordoned runner take new workspaces again
  drain       Stop a runner taking new workspaces, until it is activated
  list        List all runners
  policy      What a runner may do, as against what it is
  revoke      Revoke a runner's access, for a machine that should never connect again

Flags:
  -h, --help   help for runner

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin runner [command] --help" for more information about a command.

spin admin runner activate

Let a drained or cordoned runner take new workspaces again.

A revoked runner is not brought back by this: its machine cannot connect again.

Usage:
  spin admin runner activate <runner-id> [flags]

Flags:
  -h, --help   help for activate

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin runner drain

Stop a runner taking new workspaces, until it is activated (spin admin runner activate).

Existing workspaces continue to run until stopped.

With --suspend, every running workspace is suspended off the runner: its memory
and disk go to the object store, and it is resumed on another runner on its own.
The command returns once each is suspended or has failed to be. With
--leave-stopped as well - a drain that shrinks the fleet - they stay stopped,
and each resumes on another runner when its owner starts it.

Usage:
  spin admin runner drain <runner-id> [flags]

Flags:
  -h, --help            help for drain
      --leave-stopped   With --suspend: leave them stopped until their owners start them (a drain that shrinks the fleet)
      --suspend         Suspend the runner's running workspaces so they resume elsewhere

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin runner list

List all runners

Usage:
  spin admin runner list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin runner policy

Show or set what this installation decides about one runner.

A runner reads what it *is* - where the control plane is, who to trust, where it keeps its
data - from its own environment, before it can reach anything. Everything else it is told
here, on its heartbeat, and it reports back the revision it is running under: "declared" and
"running" being different for more than a moment is a runner that did not take it.

With no flags this shows the policy. Any flag writes it, and a write is the whole policy:
what you do not pass is the installation saying nothing about that setting, which leaves the
runner on its own default.

Usage:
  spin admin runner policy <runner-id> [flags]

Flags:
      --cpu-cores int32                         cores this runner advertises; unset advertises what it has
      --disk-gb int32                           disk this runner advertises; unset advertises what it has
  -h, --help                                    help for policy
      --max-workspace-cpu-cores int32           the cores one workspace may grow to there
      --max-workspace-io-mb-per-second int32    MiB one workspace may read, and write, a second there; unset is no bound
      --max-workspace-io-ops-per-second int32   I/O operations one workspace may read, and write, a second there; unset is no bound
      --max-workspace-memory-mb int32           the memory one workspace may grow to there
      --memory-mb int32                         memory this runner advertises; unset advertises what it has
      --preemptible                             a stop on this runner is the machine being taken away, not a restart
      --preemption-metadata-url string          where that cloud's metadata service answers; empty is its own link-local address
      --preemption-source string                the cloud that announces a reclaim: aws, gcp or azure (implies --preemptible)
      --shutdown-grace duration                 how long this runner stays up after a stop signal so its workspaces can be moved off it
      --writeback-background-bytes int          dirty page cache at which this runner starts writing back (vm.dirty_background_bytes), below the limit
      --writeback-limit-bytes int               dirty page cache this runner holds before a writer waits (vm.dirty_bytes); unset is what it booted with

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin runner revoke

Revoke a runner's access to the platform: for a machine being replaced, or one that may
be compromised.

The runner is disconnected and its credentials deleted: that machine cannot come back, and
the capacity returns only with a new machine. To stop a runner taking new workspaces for a
while, drain it instead (spin admin runner drain).

A runner that holds workspaces' disks is refused, naming them: each could then run only once
recovered onto another runner (spin workspace recover), losing what this one had not published.
--leave-workspaces revokes it anyway.

Usage:
  spin admin runner revoke <runner-id> [flags]

Flags:
  -h, --help               help for revoke
      --leave-workspaces   revoke although workspaces are on this host; each runs again only once recovered elsewhere
  -y, --yes                Skip confirmation

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin storage

What the object store holds, and taking out what nothing needs

Usage:
  spin admin storage [flags]
  spin admin storage [command]

Available Commands:
  list        Every volume in the store, whose it is and whether it may be removed
  remove      Remove an image, an extension release, an unclaimed volume or an orphan from the store
  untag-image Take a ref off the image it names

Flags:
  -h, --help   help for storage

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin storage [command] --help" for more information about a command.

spin admin storage list

Every volume in the store, whose it is and whether it may be removed, as storage-gc last
read the store (it reads it daily; the dashboard reads it now).

Usage:
  spin admin storage list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin storage remove

Remove an image, an extension release, an unclaimed volume or an orphan from the store:
its row, then its volume, whose key is destroyed. Its layers go at storage-gc's next run.

An image its ref still names is untagged first (spin admin storage untag-image); the newest
release of an extension, one a workspace runs, and a workspace's disk are refused.

Usage:
  spin admin storage remove <volume-id> [flags]

Flags:
  -h, --help   help for remove
  -y, --yes    Skip confirmation

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin storage untag-image

Take a ref off the image it names: no new workspace is given it by that ref, and the next
publish under the ref is what it names. The disks already cloned from it go on reading
it; once none does, it can be removed (spin admin storage remove).

Usage:
  spin admin storage untag-image <ref> [flags]

Flags:
  -h, --help   help for untag-image

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin token

Manage runner registration tokens

Usage:
  spin admin token [flags]
  spin admin token [command]

Available Commands:
  create      Create a runner registration token
  list        List registration tokens
  revoke      Revoke a registration token

Flags:
  -h, --help   help for token

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin token [command] --help" for more information about a command.

spin admin token create

Create a token for registering a new runner: one-time, or with --reusable a pool's.

The token will be displayed only once. Save it securely.

A pool's token registers every machine that presents it until it expires or is revoked: what
an autoscaling group's machines take, with nobody at them. Keep it short-lived and rotate it
(the control plane's own machine can mint one with `controlplane registration-token`).

The policy flags are what every runner the token registers starts with, as `spin admin runner
policy` would set them: a spot group's runners need to know from their first heartbeat that
a stop is a reclaim. A runner registering again keeps what was decided about it since.

Examples:
  spin admin token create --description "Host us-east-1"
  spin admin token create --description "Team runner" --team engineering
  spin admin token create --description "Temp runner" --expires 1h
  spin admin token create --description "spot group" --reusable --expires 168h \
    --preemption-source aws --shutdown-grace 100s

Usage:
  spin admin token create [flags]

Flags:
      --cpu-cores int32                         cores each host it registers advertises; unset advertises what it has
      --description string                      Description for the token
      --disk-gb int32                           disk each host it registers advertises; unset advertises what it has
      --expires duration                        how long the token registers hosts; unset is the control plane's 24 hours, and at most 30 days
  -h, --help                                    help for create
      --max-workspace-cpu-cores int32           the cores one workspace may grow to there
      --max-workspace-io-mb-per-second int32    MiB one workspace may read, and write, a second there; unset is no bound
      --max-workspace-io-ops-per-second int32   I/O operations one workspace may read, and write, a second there; unset is no bound
      --max-workspace-memory-mb int32           the memory one workspace may grow to there
      --memory-mb int32                         memory each host it registers advertises; unset advertises what it has
      --preemptible                             a stop on each host it registers is the machine being taken away, not a restart
      --preemption-metadata-url string          where that cloud's metadata service answers; empty is its own link-local address
      --preemption-source string                the cloud that announces a reclaim: aws, gcp or azure (implies --preemptible)
      --reusable                                a pool's token: it registers every host that presents it until it expires
      --shutdown-grace duration                 how long each host it registers stays up after a stop signal so its workspaces can be moved off it
      --team string                             The team to scope the runner to, by id, path or me
      --writeback-background-bytes int          dirty page cache at which each host it registers starts writing back (vm.dirty_background_bytes), below the limit
      --writeback-limit-bytes int               dirty page cache each host it registers holds before a writer waits (vm.dirty_bytes); unset is what it booted with

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin token list

List registration tokens

Usage:
  spin admin token list [flags]

Flags:
  -h, --help           help for list
      --include-used   Include already-used tokens

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin token revoke

Revoke a registration token

Usage:
  spin admin token revoke <token-id> [flags]

Flags:
  -h, --help   help for revoke

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin versions

What is running where: this control plane, each runner and its machine

Usage:
  spin admin versions [flags]

Flags:
  -h, --help   help for versions

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin volume

Re-key a workspace's disk

Usage:
  spin admin volume [flags]
  spin admin volume [command]

Available Commands:
  rekey       Copy a workspace's disk under a key of its own and destroy the old one
  rekeys      The disks being re-keyed, and the ones a revoked host's keys marked for it

Flags:
  -h, --help   help for volume

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

Use "spin admin volume [command] --help" for more information about a command.

spin admin volume rekey

Copy a workspace's disk, whole, under a key of its own, point the workspace at the copy and
delete the disk - which destroys the key it was under, and every snapshot of the disk with it: those
are what that key opens. What to do when the key is assumed taken, by a host that held it.

The workspace must be stopped or quarantined. A disk something was cloned from is refused.

Usage:
  spin admin volume rekey <workspace> [flags]

Flags:
  -h, --help   help for rekey
  -y, --yes    Skip confirmation

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")

spin admin volume rekeys

The disks being re-keyed, and the ones a revoked host's keys marked for it

Usage:
  spin admin volume rekeys [flags]

Flags:
  -h, --help   help for rekeys

Global Flags:
      --config string    config file (default is $HOME/.spin/config.yaml)
  -o, --output string    text for a person, or json: one document of what the API answered, and no prose (default "text")
      --profile string   named profile to use; SPIN_PROFILE names it when this flag does not (default "default")