@microck/raft 0.3.0 → 0.5.0

package/docs/guides/config-policy.mdx

@@ -0,0 +1,179 @@
+---
+title: Defaults and note policies
+description: Set controller defaults for new boxes and require box note fields on a host.
+---
+
+# Defaults and note policies
+
+Raft has two kinds of settings:
+
+| Setting | Stored in | Applies to | Change with |
+| --- | --- | --- | --- |
+| Defaults for `new` | `~/.config/raft/config.json` on the controller | That controller only | `raft config set` and `raft config unset` |
+| Required box note fields | Incus project `raft` on each host | Every controller that uses the host | `raft policy` |
+
+`raft config` prints both: the effective defaults with their source, and each
+location's policy.
+
+```sh title="CONTROLLER: Inspect defaults and policies"
+raft config
+```
+
+```json title="Example output"
+{
+  "file": "/root/.config/raft/config.json",
+  "defaults": {
+    "location": {
+      "value": "lab",
+      "source": "config"
+    },
+    "ttl": {
+      "value": 3600,
+      "source": "config"
+    },
+    "cpu": {
+      "value": 1,
+      "source": "built-in"
+    },
+    "memory": {
+      "value": "2GiB",
+      "source": "built-in"
+    },
+    "disk": {
+      "value": "shared",
+      "source": "built-in"
+    }
+  },
+  "policy": {
+    "lab": {
+      "require": [
+        "purpose",
+        "owner"
+      ],
+      "changed": "2026-10-21T09:12:44Z by ubuntu from me@laptop"
+    }
+  }
+}
+```
+
+`raft config` contacts every configured host to read its policy. It fails and
+names the location when a host is unreachable.
+
+## Defaults for new
+
+Set a default for any of `location`, `ttl`, `cpu`, `memory` and `disk`:
+
+```sh title="CONTROLLER: Prefer bigger, longer boxes on paris"
+raft config set location paris
+raft config set ttl 3600
+raft config set cpu 4
+raft config set memory 16GiB
+raft config set disk 20GiB
+raft config unset cpu
+```
+
+Each command prints the old and new value. `raft new` takes an explicit flag
+first, then the configured default, then the built-in default (first configured
+location, 600 seconds, 1 CPU, 2 GiB, the shared pool). `resume`, `fork`,
+`extend` and `recover` take no defaults: their TTL and target are deliberate
+choices, and omitted sizes on resume and fork keep the source limits.
+
+Size defaults (`cpu`, `memory`, `disk`) apply only where the built-in sizes do:
+to boxes created from the image. A box from `new --from` keeps the snapshot's
+location, CPU, RAM and disk, and a fork keeps its source's, whatever
+`config.json` says. Only a flag changes them:
+
+| Command | CPU and RAM | Disk |
+| --- | --- | --- |
+| `new` | Flag, then config, then 1 CPU / 2 GiB | Flag, then config, then the shared pool |
+| `new --from` | Flag, then the snapshot's | `--disk SIZE`, then the snapshot's |
+| `fork` | Flag, then the source's | The source's |
+
+A `disk` default needs own box disks on the target host. On a location without
+the `raft-disks` pool, or with too little unreserved space, `raft new` fails with
+the same error as `--disk` and names the configured value as the cause:
+
+```text
+$ raft new --purpose "Run the tests"
+raft: lab has no raft-disks pool, so own box disks are not enabled there; nothing was created. Enable them with python3 deploy/deploy.py --location lab --disk-pool SIZE. The 20GiB own disk comes from defaults.disk in /root/.config/raft/config.json; give --disk shared or --disk SIZE, or run raft config unset disk
+```
+
+`--disk shared` puts one box on the shared pool despite a `disk` default. It is
+refused with `--from`, which keeps the snapshot's disk.
+
+The file accepts a value exactly when the same text is accepted as the flag.
+An unknown key, a bad value or malformed JSON makes `raft new` fail with the file
+path and the key; Raft never ignores part of the file. Repair a bad key with
+`raft config set KEY VALUE` or `raft config unset KEY`. Writes are atomic, keep
+mode `0600` and remove the file when no default remains.
+
+Scripts and CI jobs that need stable sizing should pass `--location`, `--ttl`,
+`--cpu`, `--memory` and `--disk` explicitly, because defaults differ between
+controllers.
+
+## Required box note fields
+
+A host policy makes every box on that host carry the listed [box note](../reference/cli.md#note)
+fields. `purpose` is always part of a note, so a policy must include it:
+
+```sh title="CONTROLLER: Require an owner on lab"
+raft policy lab --require purpose,owner
+raft policy lab --clear
+```
+
+With that policy, a command that would leave a box without an owner fails before
+it changes anything and says how to fix it:
+
+```text
+$ raft new --location lab --purpose "Run the tests"
+raft: location lab requires --owner (host policy). Add it: raft new --purpose "..." --owner "..." [--next "..."]
+```
+
+The policy covers every command that creates a box or changes its note:
+
+| Command | Note checked |
+| --- | --- |
+| `new`, including `new --from` | The note given to `new`; a snapshot's note is never inherited |
+| `fork` | The note given to `fork`, otherwise the source box's note |
+| `recover` | The note given to `recover`, otherwise the note in the archive |
+| `note BOX` | The new note; `--clear` is rejected while a policy requires fields |
+
+On `fork` and `recover`, `--purpose`, `--owner` and `--next` replace the whole
+note, like `raft note`. Give all the fields the copy needs; omitted fields are
+not taken from the source. `recover` without note flags can only check the
+archived note after import. When it fails, Raft deletes the imported box in the
+same locked step and reports the error. Pass the note to `recover` to fail before
+the upload instead.
+
+The controller checks the policy first, so the error arrives before any work.
+The host checks it again in the same locked transaction that writes the note,
+so a policy change cannot race a creation. That transaction checks the
+requested size against the host and reserves own-disk space first; any refusal
+comes before Incus creates the box.
+
+## Audit trail
+
+`raft policy` prints the change, for example
+`lab: required note fields none -> purpose,owner`. The host records the last
+change in the project key `user.raft.require.changed` (UTC time, the SSH account
+and the controller's self-reported user and hostname) and writes a `raft` entry
+to the host journal:
+
+```sh title="HOST: Review policy changes"
+sudo incus project get raft user.raft.require
+sudo incus project get raft user.raft.require.changed
+sudo journalctl -t raft
+```
+
+## Limits
+
+Note policies are a guardrail for agents, not a security boundary:
+
+- Anyone with SSH and sudo on the host can change or remove the policy, or create
+  boxes with native `incus` commands that skip it.
+- Controllers older than the release that added policies do not check them.
+  Upgrade every controller that uses a host before relying on its policy.
+- The controller identity in `user.raft.require.changed` is reported by the
+  controller and is not verified. The SSH account comes from `sudo`.
+- Raft checks that required fields are present and nonempty, not that their text
+  is accurate.

package/docs/guides/docker.mdx

@@ -64,7 +64,15 @@ docker run --rm my-app
 
 ## Managing disk space
 
-Nested container layers and volumes reside on the shared 60 GiB `raft-data` Btrfs storage pool.
+Nested container layers and volumes live in the box's filesystem. By default that is the shared 60 GiB `raft-data` Btrfs pool, where one box's Docker data can fill the pool for every box.
+
+On hosts with own box disks enabled, give Docker-heavy boxes their own disk. Docker data stays inside it, and builds fail with "No space left on device" at the cap instead of filling the host:
+
+```sh title="CONTROLLER: Create a box with its own 40 GiB disk"
+box=$(raft new --disk 40GiB --ttl 3600 --purpose "Docker image builds")
+```
+
+See [Own box disks](../reference/capacity.mdx#own-box-disks).
 
 Prune dangling images without deleting active container data:
 

package/docs/guides/long-running-services.mdx

@@ -28,8 +28,8 @@ Use `raft new --disposable` for temporary work. A fork is persistent unless
 `--disposable` is explicitly supplied; recovered boxes are persistent.
 Back up work before stopping a disposable box.
 
-Persistent stopped boxes still occupy a saved slot and storage. Each host allows
-four saved boxes. `raft prune --older-than 7` previews old stopped boxes;
+Persistent stopped boxes still occupy storage. Raft does not cap how many boxes
+a host keeps. `raft prune --older-than 7` previews old stopped boxes;
 `--yes` applies deletion. There is no automatic persistent-box retention cleanup.
 
 ## Read and reset the deadline

package/docs/guides/meta.json

@@ -9,6 +9,7 @@
     "background-jobs",
     "long-running-services",
     "scripting-ci",
+    "config-policy",
     "desktop-services",
     "snapshots-forks",
     "backup-recovery",

package/docs/guides/project-setup.mdx

@@ -94,9 +94,10 @@ raft exec "$copy" -- ls -la /workspace/my-project
 ```
 
 The template stays on its source host. Its source box can be running when you
-copy the saved snapshot. `new --from` uses normal creation defaults when sizing
-is omitted: 1 CPU and 2 GiB RAM. The new box has its own handle, MAC address,
-deadline, and saved slot.
+copy the saved snapshot. `new --from` keeps the snapshot's CPU, RAM and disk
+unless `--cpu`, `--memory` or `--disk SIZE` overrides them; `--disk` gives it an
+own disk of a new size. The new box has its own handle, MAC address
+and deadline.
 
 The snapshot includes packages, project files, credentials, and enabled services.
 It does not include process memory. Changing the original after snapshot creation

package/docs/guides/scripting-ci.mdx

@@ -19,11 +19,13 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | --- | --- |
 | `new`, `fork`, `recover` | One location-qualified handle |
 | `exec --detach` | One `rfcmd-` job ID |
-| `list` | JSONL: one object per box, with `box`, `state`, `stopAt` |
+| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `disk`, `note` |
 | `info` | One pretty-printed native Incus metadata JSON object |
 | `usage` | One JSON object containing running resource counters |
-| `limits --json` | One JSON object per location (JSONL across multiple hosts) |
+| `capacity --json` | One JSON object per location (JSONL across multiple hosts) |
 | `locations` | One JSON object per configured location (JSONL) |
+| `config` | One pretty-printed JSON object with `file`, `defaults`, `policy` |
+| `config set/unset`, `policy` | One line describing the change |
 | `prune` | JSONL candidates or deleted records with `box`, `action` |
 | `status` | systemd `ActiveState`, `SubState`, `ExecMainStatus` property lines |
 | `logs` | Guest journal text |
@@ -31,23 +33,35 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | Other inspection/maintenance commands | Human-readable text or no output |
 
 `list` emits nothing when there are no boxes. `stopAt` is the host Unix deadline
-as a string, or an empty string when absent. `info` uses native Incus keys rather
+as a string, or an empty string when absent. `disk` is `"shared"` or the box's
+own disk size, such as `"20GiB"`. `note` is the box note object with
+`purpose` and optional `owner` and `next`, or `null`. `info` uses native Incus keys rather
 than a normalized Raft schema. `usage` includes `memoryBytes`, `memoryLimit`,
 `cpuTime`, `effectiveCpus`, `filesystemUsedBytes`, `filesystemAvailableBytes`, and
-`filesystemScope`; disk values describe the shared pool, not an individual box.
-See [Capacity limits](../reference/capacity-limits.mdx) for capacity calculations.
+`filesystemScope`; disk values describe the shared pool, or the box's own disk
+when it has one. See [Box sizing and capacity](../reference/capacity.mdx) for the
+advisory capacity fields.
 
 These examples require `jq` on the controller:
 
 ```sh title="CONTROLLER: Parse records without mixing stderr"
 raft list --location lab | jq -r 'select(.state == "Running") | .box'
-raft limits --location lab --json | jq '{location, savedSlots, warnings}'
+raft capacity --location lab --json | jq '{location, headroom, warnings}'
 raft prune --location lab --older-than 7 | jq -r '.box'
 ```
 
+`raft new` fills omitted options from the controller's
+`~/.config/raft/config.json`, so the same script can create different boxes on
+different controllers. Pass `--location`, `--ttl`, `--cpu`, `--memory` and
+`--disk` in CI.
+Hosts can also require box note fields; give `--purpose`, `--owner` and `--next`
+so a policy cannot fail the job. See [Defaults and note policies](./config-policy.mdx).
+
 Do not redirect `2>&1` into machine-readable output. Recovery reports its allocated
 handle on stderr before import finishes; only a successful completion prints the
-final handle on stdout.
+final handle on stdout. Once a day Raft may also print a release notice on
+stderr. Set `RAFT_NO_UPDATE_CHECK=1` in jobs that pin a CLI version or compare
+stderr.
 
 ## Exit codes and job results
 
@@ -57,6 +71,7 @@ final handle on stdout.
 | Synchronous `exec` | Transport/command return code; preserves payload exit status when transport succeeds |
 | Recognized runtime/configuration failure | `1`, with `raft: ...` on stderr |
 | Argument parsing failure | `2`, with argparse diagnostics on stderr |
+| `self-update --check` finds a newer release | `100` |
 | Caught keyboard interruption | `130` |
 
 SSH transport failures may return SSH's status rather than the payload's result.
@@ -72,7 +87,7 @@ running job's initial `ExecMainStatus=0` as completion. See
 ready. Probe a harmless command before running setup. This Bash example waits up
 to about a minute plus transport time, executes an uploaded project check, and
 attempts to stop the persistent box on exit. It assumes `./my-project/check.sh`
-exists and the configured host has a free saved slot:
+exists:
 
 ```bash title="CONTROLLER or trusted Linux CI runner"
 set -euo pipefail
@@ -109,10 +124,10 @@ raft upload "$box" ./my-project /workspace/my-project --recursive
 raft exec "$box" -- bash -lc 'cd /workspace/my-project && bash ./check.sh'
 ```
 
-The stopped box remains available for inspection and still consumes a saved slot.
+The stopped box remains available for inspection and still uses disk space.
 Destroy it after collecting needed files, or preview old stopped boxes with prune.
 For disposable CI boxes, deletion on stop/expiry removes artifacts and snapshots;
-download results before cleanup. A new box or a retry still consumes a saved slot.
+download results before cleanup. A new box or a retry uses its own disk space.
 
 Command readiness does not mean Docker or a web application is ready. Probe the
 specific dependency (`docker info`, an HTTP health endpoint, or systemd status)

package/docs/guides/snapshots-forks.mdx

@@ -75,7 +75,7 @@ echo "Created fork: $copy"
 - **Instance-only copy**: Uses Incus `--instance-only`. Filesystem data, installed packages, and `/workspace` files are copied; source snapshots are not inherited.
 - **Immediate start**: `raft fork` launches the new container immediately with the specified TTL while the source remains stopped.
 - **Fresh network identity**: The fork receives a new container name, a fresh MAC address on `rfbr0`, and an independent IP address.
-- **Capacity accounting**: The fork counts toward the location's four-saved-box limit and uses storage from the shared 60 GiB Btrfs pool.
+- **Disk**: The fork keeps the source disk. Both kinds fork in seconds as copy-on-write snapshots: a shared-pool source within the shared 60 GiB Btrfs pool, an own-disk source as a thin snapshot that reserves its full size in `raft-disks`.
 
 Destroy the clone when finished to release capacity:
 
@@ -89,7 +89,13 @@ raft destroy "$copy"
 copy=$(raft new --from "$box/pre-upgrade" --ttl 600)
 ```
 
-The source box can be running because Raft copies the saved snapshot. The new box stays on the same host, uses normal creation sizing defaults and has a fresh network identity. Filesystem secrets are copied too.
+The source box can be running because Raft copies the saved snapshot. The new box stays on the same host, keeps the snapshot's CPU, RAM and disk unless `--cpu`, `--memory` or `--disk` overrides them, and has a fresh network identity. Copies are copy-on-write snapshots, so starting many boxes from one prepared snapshot is fast; on own disks each copy still reserves its full size. Filesystem secrets are copied too.
+
+Add `--disk SIZE` to copy the snapshot onto an own disk of a new size, for example to give a full box more room:
+
+```sh
+bigger=$(raft new --from "$box/pre-upgrade" --disk 40GiB --ttl 600)
+```
 
 Remove a snapshot you no longer need:
 
@@ -104,4 +110,4 @@ copy=$(raft fork "$box" --ttl 600 --cpu 2 --memory 4GiB)
 raft resume "$box" --ttl 600 --memory 2GiB
 ```
 
-Omitted sizing values keep the source limits. Forks are persistent by default; add `--disposable` to delete a clone when it stops or expires.
+Omitted CPU and RAM values keep the source limits; the disk never changes on fork or resume. Forks are persistent by default; add `--disposable` to delete a clone when it stops or expires.

package/docs/guides/troubleshooting.mdx

@@ -22,11 +22,11 @@ raft doctor
 - Compatibility of the installed expiry worker with the CLI
 - Active status of host systemd services (`incus`, `raft-expire.timer`, `raft-network.service`)
 - Host root filesystem disk usage (`df -h /`)
-- Status and usage of the `raft-data` Btrfs pool
+- Status and usage of the shared `raft-data` Btrfs pool, and of the `raft-disks` LVM thin pool when own box disks are enabled (otherwise `own box disks: not enabled (redeploy with --disk-pool SIZE)`)
 - Count of existing saved containers
 
 <Callout type="info" title="Doctor scope">
-`raft doctor` reports runtime daemon, expiry-worker compatibility, and storage status. It does not validate image fingerprints, inspect nftables bridge rules, enforce admission caps, or emit 5 GiB low-disk warnings.
+`raft doctor` reports runtime daemon, expiry-worker compatibility, and storage status. It does not validate image fingerprints, inspect nftables bridge rules, or emit 5 GiB low-disk warnings. A host without `raft-disks` is healthy: own box disks are opt-in.
 </Callout>
 
 ### Expiry worker differs from the CLI
@@ -120,13 +120,25 @@ The configuration file contains valid JSON that is `{}` or is not an object (an
 #### "Build an image and configure its full immutable fingerprint before creating boxes"
 The `image` field is missing or is not a 64-character hexadecimal SHA-256 fingerprint. Supply the full fingerprint from `sudo incus --project raft image list raft-dev --format json`.
 
-### Admission and capacity errors
+### Sizing and disk errors
 
-#### "Location already holds four boxes"
-Raft enforces a hard limit of four saved boxes per location. Both running and stopped containers count toward this limit. Destroy unused boxes with `raft destroy <box>` before creating, forking, or recovering a box.
+Raft has no box count limit and no size budget. These errors come from the
+request itself or from the host:
+
+#### "Requested N CPUs, but this host has M" or "Requested SIZE RAM, but this host has N GiB"
+The request is larger than the whole host. Ask for at most the host's CPUs and RAM; `raft capacity` shows both.
+
+#### "LOCATION has no raft-disks pool, so own box disks are not enabled there"
+Own box disks are opt-in and this host was deployed without them. Nothing was created. Enable them with `python3 deploy/deploy.py --location <location> --disk-pool SIZE`, which needs SIZE plus 20 GiB free on the host, or create the box without `--disk`. Boxes without `--disk` keep working meanwhile.
+
+#### "own box disks would need N GiB more of raft-disks"
+Each own disk, each snapshot of one, and the cached image reserve their full size in `raft-disks`, so Raft refused the request before creating anything. Destroy own-disk boxes or snapshots you no longer need, choose a smaller `--disk`, or use the shared pool. `raft capacity` shows the unreserved space. See [Reservation accounting](../reference/capacity.mdx#reservation-accounting).
+
+#### "No space left on device" inside an own-disk box
+The box filled its own disk. Delete files or Docker data inside the box. For a persistent box you can also move to a larger disk: stop it with `raft stop "$box"` (snapshots need a stopped box), take `raft snapshot "$box" <snapshot>`, then create the copy with `raft new --from "$box/<snapshot>" --disk <larger size>`. Do not stop a `--disposable` box for this: stopping deletes it.
 
 #### Low disk warnings
-`raft limits` warns when free space on host disk or the `raft-data` pool falls below 5 GiB. This warning is diagnostic and does not halt container operations. Clean up dangling images, old snapshots, or unused containers to free space.
+`raft capacity` warns when free space on host disk or the `raft-data` pool falls below 5 GiB. This warning is diagnostic and does not halt container operations. Clean up dangling images, old snapshots, or unused containers to free space.
 
 ### Network and forwarding issues
 

package/docs/guides/upgrades.mdx

@@ -10,7 +10,7 @@ parts of Raft. Updating one does not automatically update the others.
 
 | Component | Update method | Effect on existing boxes |
 | --- | --- | --- |
-| Controller CLI | Install the chosen npm or Python release | Changes controller commands; does not rewrite guest files |
+| Controller CLI | `raft self-update`, or install the chosen npm or Python release | Changes controller commands; does not rewrite guest files |
 | Host worker and firewall | Run the chosen release's deployer per host | Replaces host policy code and reapplies filtering |
 | Pinned development image | Import an image and change the configuration fingerprint | Used for future image-based `new`; existing boxes keep their files |
 
@@ -33,7 +33,14 @@ stopping one. Schedule redeployment when interruptions are acceptable.
 
 ## Update the controller
 
-For an npm installation:
+`raft self-update` installs the latest release through the channel that
+installed the CLI, and `raft self-update --version 0.2.0` installs a chosen
+one. `raft self-update --check` only reports. For npm installs, npm checks the
+registry integrity hash of a package published with provenance. For uv tools,
+Raft downloads the release wheel and refuses it unless its SHA-256 matches the
+release `SHA256SUMS`. See [`self-update`](../reference/cli.md#self-update).
+
+To install a release by hand instead, for an npm installation:
 
 ```sh title="CONTROLLER: Install a pinned CLI release"
 npm install -g @microck/raft@0.2.0
@@ -54,7 +61,10 @@ and check which executable your shell uses with `command -v raft`.
 
 For an editable source installation, updating the checkout changes the installed
 tool's source. Keep uncommitted work separate and run `uv sync --locked` for the
-chosen checkout. Raft has no `self-update` command.
+chosen checkout. `self-update` refuses source checkouts.
+
+Updating the CLI changes no host. Continue below, and run `raft doctor` first: it
+reports each host whose worker differs from the new CLI.
 
 ## Redeploy each host
 

package/docs/index.mdx

@@ -33,6 +33,7 @@ Stopping a workspace preserves files and packages on disk. Resuming resets its r
 | Run detached commands with systemd logs | [Background jobs](./guides/background-jobs.mdx) |
 | Manage deadlines and restart services after resume | [Lifetime and persistent services](./guides/long-running-services.mdx) |
 | Automate the CLI and parse its output | [Scripting and CI](./guides/scripting-ci.mdx) |
+| Set defaults for new boxes or require box note fields | [Defaults and note policies](./guides/config-policy.mdx) |
 | Forward guest ports or open noVNC desktop | [Desktop and private services](./guides/desktop-services.mdx) |
 | Capture disk state or clone workspaces | [Snapshots and forks](./guides/snapshots-forks.mdx) |
 | Export portable backups across hosts | [Backup and recovery](./guides/backup-recovery.mdx) |

package/docs/operations.mdx

@@ -15,7 +15,7 @@ Install the CLI from npm on your Linux controller, confirm key-based SSH to the
 host, then let `raft host add` do the remaining steps:
 
 ```sh title="CONTROLLER: Onboard a host"
-npm install -g @microck/raft@0.3.0
+npm install -g @microck/raft@0.5.0
 ssh ubuntu@192.0.2.10 true
 raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
 raft host add lab --ssh ubuntu@192.0.2.10
@@ -44,7 +44,7 @@ Connect to your host over SSH, verify its host key fingerprint, and install base
 ```sh title="HOST: Install baseline system packages"
 sudo apt-get update
 sudo apt-get install -y --no-install-recommends \
-  ca-certificates curl gnupg python3 openssh-server iptables btrfs-progs
+  ca-certificates curl gnupg python3 openssh-server iptables btrfs-progs lvm2 python3-yaml
 ```
 
 Verify passwordless `sudo` on the host:
@@ -62,7 +62,7 @@ sudo -n true && echo "Passwordless sudo is functional"
 On your Linux controller with Python 3.11.8+, install the published CLI:
 
 ```sh title="CONTROLLER: Install published CLI"
-npm install -g @microck/raft@0.3.0
+npm install -g @microck/raft@0.5.0
 raft --version
 ```
 
@@ -70,7 +70,7 @@ Installation does not configure hosts or download images. Clone the matching
 release to obtain the deployment scripts and example configuration:
 
 ```sh title="CONTROLLER: Obtain deployment scripts"
-git clone --branch v0.3.0 https://github.com/Microck/raft.git raft
+git clone --branch v0.5.0 https://github.com/Microck/raft.git raft
 cd raft
 ```
 
@@ -132,15 +132,17 @@ Run the automated host deployer from your controller:
 
 ```sh title="CONTROLLER: Provision host infrastructure"
 python3 deploy/deploy.py --location lab
+# Optional: enable own box disks with a pool of this size, now or on any later redeploy
+python3 deploy/deploy.py --location lab --disk-pool 100GiB
 ```
 
 <details>
 <summary>Infrastructure created by the deployer</summary>
 
 The deployer runs over SSH and configures the host:
-1. Installs Incus 6.0 LTS and nftables packages.
+1. Installs Incus 6.0 LTS, LVM, nftables and python3-yaml packages.
 2. Creates the isolated `raft` Incus project.
-3. Creates a 60 GiB Btrfs storage pool (`raft-data`).
+3. Creates the shared 60 GiB Btrfs storage pool (`raft-data`). With `--disk-pool SIZE`, also creates the LVM thin pool for [own box disks](./reference/capacity.mdx#own-box-disks) (`raft-disks`) of SIZE, allocates its file on the host disk in full and stops it passing discards to that file. Without `--disk-pool` own box disks stay disabled, which is a healthy state. A later redeploy with `--disk-pool` adds the pool; no redeploy resizes either pool.
 4. Creates private bridge interface `rfbr0` (`10.232.0.1/24`) with NAT.
 5. Configures nftables bridge filters to block inter-workspace traffic and restrict host access.
 6. Installs and enables `raft-network.service` and `raft-expire.timer` units.
@@ -159,16 +161,16 @@ Workspaces require an unprivileged Debian 13 development image matching the host
 
 <Tab value="Download release image">
 
-Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.3.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.5.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
 
 <Tabs items={["ARM64", "AMD64"]}>
 
 <Tab value="ARM64">
 
 ```sh title="HOST (ARM64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/raft-dev-arm64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/manifest-arm64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/manifest-arm64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
@@ -179,9 +181,9 @@ sha256sum --ignore-missing -c SHA256SUMS && \
 <Tab value="AMD64">
 
 ```sh title="HOST (AMD64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/raft-dev-amd64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/manifest-amd64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/manifest-amd64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev
@@ -260,4 +262,4 @@ Check that Incus, the network service, and the expiration timer are active. For
 
 Proceed to [First working box](./first-box.mdx) to launch, verify, and manage your first workspace.
 
-For later releases, follow [Upgrades and image changes](./guides/upgrades.mdx).
+For later releases, run `raft self-update` and follow [Upgrades and image changes](./guides/upgrades.mdx).