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

Backups and recovery

View Markdown

An installation’s durable state is in three places:

StateWhereHow it is protected
Users, teams, workspaces, snapshots, settings, secretsPostgreSQL on the control plane’s machine, archived to the database’s bucketA base backup every day and each WAL segment within five minutes, sealed under the installation’s key; the bucket under Object Lock for database_lock_days
Every workspace’s disk and snapshotsThe volumes bucketVersioning, and Object Lock for object_lock_days
The key that opens the installation’s secretsNowhere: derived at every start from a KMS keyKMS answers only a control plane that proves the image it booted; never in the Terraform state

The control plane’s and the proxy’s machines hold nothing that cannot be rebuilt. The proxy’s certificates are kept in a bucket of their own, and the metric store is backed up to the logs bucket.

The encryption key is the installation, and the KMS key it is derived from is the encryption key. Without it, nothing in the database’s archive or its secrets can be opened, and neither can any volume’s key. Nothing in the module makes a new one, and the KMS key refuses to be destroyed by a plan.

What the runner had not uploaded is lost. Every workspace can be moved to another runner by its owner (spin workspace recover), or automatically if the installation allows it. See Runners and hosts.

Losing the control plane’s or the proxy’s machine

Section titled “Losing the control plane’s or the proxy’s machine”

Its autoscaling group starts another. The new one starts from the same release and the same document, and takes over. Workspaces keep running.

The control plane’s machine carries the database, so the new machine restores it before it serves: the newest base backup in the archive, then every WAL segment after it. What the old machine wrote in its last five minutes and had not archived is lost with it. An archive that does not open under the installation’s key is refused, and the control plane does not start on it.

A release replaces the machine the same way, without the loss: the old machine stops writing, archives its last segment and lets go, and the new one restores to that point.

A delete or an overwrite in the database’s bucket is a version that Object Lock holds for database_lock_days. Older base backups are pruned as new ones are taken, so a restore starts from a recent one.

A release older than the one that last started the database refuses to start on it. Going back past a schema change is not something an update or a command does today.

  • The runners’ local disks: they are a cache, and whatever was not uploaded yet.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.