# spin admin **Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://spin-stack.github.io/website/reference/status.md); what Spinbox does not do is on [Limitations](https://spin-stack.github.io/website/overview/limitations.md). > spin admin: Administrative commands. ``` 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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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") ```