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

Disks and storage

View Markdown

A workspace’s disk is a volume. You never manage one directly: a volume is created with its workspace and goes with it. This page explains where its bytes are, because that decides what survives what.

A volume is a chain of qcow2 layers. The bottom layers belong to the image or snapshot it was cloned from, and are shared with every other workspace cloned from the same place. The top layer is the only one written to.

From time to time the runner seals the top layer, uploads it to the bucket, and starts a new one above it. This is a commit. It happens:

  • when the oldest write not yet in the bucket reaches the volume’s RPO (recovery point objective): 5 minutes unless the installation’s volume_rpo_seconds or the workspace’s preset says otherwise (see the configuration file),
  • once about 1 GiB has been written to the top layer,
  • when a snapshot is taken,
  • when the workspace stops. The stop stays STOPPING until the layer is in the bucket. spin workspace stop --force skips this, and what was written since the last commit stays on the runner alone.

The RPO is how much recent work a runner lost without warning can take with it. An RPO of 0 turns the age trigger off, and the volume then commits only on size, snapshots and stops.

A snapshot is a sealed layer with a name. A clone is a new volume whose chain points at the snapshot’s layers. A diff compares two chains. None of these copies a disk.

WhereSurvives the runner
Sealed layersThe bucket, compressed and encryptedYes
The top layerThe runner’s local diskNo
A copy of the sealed layersThe runner’s local disk, as a cacheRebuilt from the bucket

The bucket is the only place a volume is durable. What a runner holds can be rebuilt from it: a workspace that starts on another runner downloads its layers there. A runner that already holds an image’s layers shares them between every workspace cloned from it.

Every volume has a data key. Each layer is compressed, then encrypted with AES-256-GCM under that key, before it leaves the runner. The data key is itself encrypted under the installation’s key-encryption key, which the control plane keeps in the database, sealed under a key that the database does not hold.

A runner holds no key-encryption key. It asks the control plane for the data key of each volume placed on it, and keeps it in memory only.

A workspace cloned from a snapshot shares the data key of the snapshot’s volume, because it reads the same layers. See Data and encryption for what this means for deletion.

Erasing a workspace deletes its volume: at once where the installation keeps no trash, and otherwise when its days in the trash are up. The bucket keeps every object under Object Lock, so deleted objects become delete markers, and their bytes go when the retention runs out (30 days by default). A layer that another workspace still reads through a clone is kept.

A daily job in the control plane removes what nothing refers to any more.

A runner keeps volumes on its local NVMe disks. A disk holds what its workspace wrote, not its full size, so the control plane charges a runner part of each new volume’s size (50% unless disk_reserve_percent says otherwise) until the volume writes more, and does not place a workspace on a runner without room for it. A runner whose disk fills past 70% stops taking new workspaces until it is back under 65%.

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