@microck/raft 0.4.0 → 0.6.0

package/docs/contract.md

@@ -17,14 +17,16 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 - npm publishes `@microck/raft` with the same Python sources as the wheel and source archive. Its executable is `raft`; Linux and Python 3.11.8+ are required. Installation runs no scripts and downloads no workspace images.
 - `raft --version` reports the release version without reading host configuration. The Python package, npm metadata and release tag must agree before publication.
 - Releases include Python wheels, source archives, npm tarballs and both native images with checksums. The release workflow verifies installation outside the checkout and publishes npm with provenance before creating the GitHub release.
+- **Self-update**: `raft self-update [--check | --version X.Y.Z]` takes the latest version from the GitHub releases API and compares versions numerically. It upgrades only npm global installs (through the registry, at the same prefix) and uv tools (a release wheel verified against the release `SHA256SUMS`), and refuses checkouts and other layouts. It never downgrades without `--version`, never changes hosts, and prints `raft doctor` as the next step. `--check` exits `100` when a newer release exists.
+- **Release notice**: At most once per 24 hours a command checks the latest release in the background and, if it is newer, prints one stderr line after the command. It never installs, prompts, changes stdout or exit status, or waits more than 2 seconds; failures stay silent. `RAFT_NO_UPDATE_CHECK=1` disables it, and `self-update` and `--version` skip it.
 
 ## Infrastructure and deployment
 
 - **Strict infrastructure validation**: Deployment refuses conflicting storage or network names and incomplete infrastructure rather than overwriting or repairing state.
-- **Storage pool sizing**: Existing owned Btrfs pools must retain the configured 60 GiB size; drift is rejected without automatic resizing.
+- **Storage pool sizing**: The shared Btrfs pool `raft-data` must retain its configured 60 GiB size. The own-disk pool `raft-disks` is opt-in: deployment creates it only when `--disk-pool SIZE` is given, on a fresh host or on any later redeploy, as a loop-backed LVM thin pool (`lvm.use_thinpool=true`) of SIZE whose file is allocated in full on the host disk and whose thin pool uses `--discards nopassdown`. A fresh host needs 80 GiB free, plus SIZE when `--disk-pool` is given; adding the pool later needs SIZE plus 20 GiB free. A host without `raft-disks` is healthy. An existing `raft-disks` keeps its size, a different explicit `--disk-pool` is refused, and a pool with another driver or thick volumes is rejected. Deployment never resizes either pool.
 - **Firewall precedence**: Redeployment reapplies firewall rules. Incus startup requires successful firewall application before the daemon starts, including socket activation.
 - **Guided onboarding**: `raft host add LOCATION --ssh TARGET` probes the target read-only and refuses unsupported hosts, including macOS, before any change. It prints the exact plan and applies it only after an interactive yes or `--yes`; `--dry-run` stops after the plan. It runs the same deployer as `deploy/deploy.py`, imports an image only after its SHA-256 matches (release `SHA256SUMS` or the local archive digest) and its architecture matches the host, then registers the location with the image fingerprint. It finishes with `doctor` and a disposable create/exec/destroy smoke test; if either fails, it removes the new location from the configuration and leaves host changes for a rerun. It uses existing key-based SSH and never collects passwords or changes SSH, other firewall rules or IP configuration. It requires the deployment files from the npm package or a source checkout.
-- **CLI coverage**: The single-operator workflow spans lifecycle, execution, files, snapshots, jobs, tunnels, backup, and capacity inspection; see the [command reference](./reference/cli.md).
+- **CLI coverage**: The single-operator workflow spans lifecycle, execution, files, snapshots, jobs, tunnels, backup, and advisory capacity inspection; see the [command reference](./reference/cli.md).
 
 ## Configuration and lifecycle defaults
 
@@ -33,38 +35,45 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 | Host identification | Configuration requires named SSH targets using letters, digits, underscores, or hyphens. |
 | Qualified handles | Every handle includes location and instance name (`<location>:<name>`). |
 | Image pinning | Workspace creation requires the immutable 64-hex image fingerprint, not an updating alias. |
-| Lifecycle defaults | Defaults to first configured location, 1 CPU, 2 GiB RAM, and 600-second lifetime. Supported choices are 1 or 2 CPUs, 1/2/4/8 GiB RAM, and 60 to 2,592,000 seconds (30 days) TTL. |
-| Admission limit | Hard ceiling of four saved boxes per host, including stopped boxes. |
+| Lifecycle defaults | Built-in defaults are the first configured location, 1 CPU, 2 GiB RAM, the shared pool, a persistent box and 600-second lifetime. `~/.config/raft/config.json` can override them for `new` only; explicit flags win, and `--persistent` overrides a `disposable` default. Boxes from a snapshot (`new --from`) and forks keep the source's CPU, RAM and disk instead of any default, configured or built-in; each flag overrides only its own value. `--cpu` takes any positive whole number, `--memory` any positive whole GiB (`16GiB`), `--disk` a positive whole GiB or `shared`, and TTL 60 to 2,592,000 seconds (30 days). |
+| Box count and size | Raft limits neither how many boxes a host holds nor their size. CPU or RAM limits larger than the whole host (CPU count, or `MemTotal` rounded up to whole GiB) are refused under the host lock before any change, because Incus would clip them silently. Other failures come from Incus, such as too little pool space. |
 | TTL calculation | Running TTL begins after launch completes, using the host clock. Cold image preparation does not consume TTL. |
 | Host locking | Creation, lifecycle transitions, and expiry are serialized by host file lock (`/run/lock/raft-incus.lock`). Noninteractive transactions close controller stdin so commands cannot wait for piped input while holding this lock. Exec, SSH, and file-transfer paths remain unchanged. Piped input to `raft exec` is unsupported. Native Incus admin calls bypass CLI policy. |
 
-## Capacity and admission inspection
+## Locations, notes and capacity inspection
 
-`raft locations` lists configured locations as JSONL with `location`, `default` and `note` fields without contacting hosts. `raft note LOCATION TEXT` and `raft note LOCATION --clear` edit the optional `note` field in the controller configuration atomically, preserving location order and mode `0600`. Notes are advisory guidance; Raft shows them in `locations`, `limits` and on stderr from `new`, and never enforces them.
+`raft locations` lists configured locations as JSONL with `location`, `default` and `note` fields without contacting hosts. `raft note LOCATION TEXT` and `raft note LOCATION --clear` edit the optional `note` field in the controller configuration atomically, preserving location order and mode `0600`. Notes are advisory guidance; Raft shows them in `locations`, `capacity` and on stderr from `new`, and never enforces them.
 
-Boxes accept an optional note with a fixed template: `purpose` (required), `owner` and `next`, all nonempty strings. `raft new --purpose TEXT [--owner TEXT] [--next TEXT]` and `raft note BOX ...` store it as JSON in the box's `user.raft.note` Incus key; `raft note BOX --clear` removes it. Each edit replaces the whole note. `raft list` reports it as `note`, or `null`. `new` always writes the key, so `new --from` never inherits a snapshot's note; forks and recovered backups keep it. Box notes are advisory and never change lifecycle policy.
+Boxes accept an optional note with a fixed template: `purpose` (required), `owner` and `next`, all nonempty strings. `raft new --purpose TEXT [--owner TEXT] [--next TEXT]` and `raft note BOX ...` store it as JSON in the box's `user.raft.note` Incus key; `raft note BOX --clear` removes it. Each edit replaces the whole note. `raft list` reports it as `note`, or `null`, reports each box's `disk` as `"shared"` or its own disk size, and reports `deleteAt`, the Unix time retention deletes a stopped box, or `""`. `new` always writes the key, so `new --from` never inherits a snapshot's note. Forks and recovered backups keep it unless `fork` or `recover` gets note flags, which replace the whole note. Box notes never change lifecycle behavior.
 
-`raft limits [--location NAME] [--json]` inspects hosts without modifying state. It reports effective CPUs, total and available RAM, saved and active box counts, active resource limits, and disk space.
+## Controller defaults and host policies
 
-- **Reserve calculations**: Recommends running boxes after reserving 1 CPU and the larger of 2 GiB or 10% host RAM.
-- **Total capacity**: Assumes an empty dedicated host, capped at four boxes.
-- **Additional running**: Subtracts active configured limits and evaluates available RAM minus host reserves. Every non-`Stopped` state (including `Frozen`) counts as active.
-- **New box capacity**: Bounded by remaining saved-box slots: `min(more running, max(0, 4 - saved boxes))`.
-- **Advisory estimates**: CPU and memory calculations are advisory planning estimates, not admission guarantees. Disk space below 5 GiB triggers diagnostic warnings. The four-saved-box admission cap is strictly enforced.
+- **Controller defaults**: `~/.config/raft/config.json` holds `{"defaults": {...}}` with optional `location`, `ttl`, `cpu`, `memory`, `disk` and `disposable` for `new`. Precedence is explicit flag, then configured default, then built-in default. `cpu`, `memory` and `disk` apply only to boxes from the image: `new --from` keeps the snapshot's location, CPU, RAM and disk unless a flag overrides them, and `--disk shared` is refused there. `ttl` and `disposable` apply to `new --from` as well, because a snapshot carries no lifecycle; `new --disposable` and `--persistent` are mutually exclusive overrides. `fork` takes no defaults and is persistent without `--disposable`. A `disk` default on a host without `raft-disks`, or larger than its unreserved space, fails like `--disk` and names `defaults.disk` as the source. Other commands take no defaults. A value is valid exactly when the same text is valid for the flag. Unknown keys, bad values and malformed JSON fail `new` with the file path and key, before any host access. `raft config set/unset` validate first, write atomically under a controller lock, keep mode `0600`, print the change and can repair the key they edit. The file is separate from `incus.json`, so location names never collide with setting names.
+- **Policy storage**: `raft policy LOCATION [--require FIELDS|none] [--delete-stopped-after HOURS|never]` sets either host policy or both; each option changes only its own. Required box note fields, which must include `purpose`, live in the Incus project key `user.raft.require`, and `--require none` empties it. Stopped-box retention lives in `user.raft.delete-stopped-after` as a positive whole number of hours, with the time it was set in `user.raft.delete-stopped-after.since`; `never` empties both. Both values are validated before any host change. Each change runs under the host lock, prints the old and new value, records UTC time, the SSH account (`SUDO_USER`) and the self-reported controller user and hostname in the policy's `.changed` key, and logs to the host journal with tag `raft`. Redeployment leaves these keys unchanged.
+- **Note policy enforcement**: `new` (including `--from`), `fork`, `recover` and `raft note BOX` check the note the box will carry. The controller reads the policy first and fails with the missing flags and a complete corrected command before changing anything. The host repeats the check inside the transaction that writes the note, under the host lock, so a concurrent policy change cannot be missed. That transaction also holds the oversize and own-disk reservation checks; all of them run before Incus creates anything. `fork` checks the given note or, without one, the source note read under the lock. `recover` checks a given note before upload; an archived note is checked after import, and a failing import is deleted in the same transaction. `note --clear` and replacement notes that drop a required field are rejected.
+- **Retention enforcement**: The host expiry worker deletes a stopped Raft box, with its snapshots, once the hours have passed since the later of its `user.raft.stopped-at` and the policy's `.since` time, so setting, shortening or renewing a policy never deletes a box sooner than its hours after the change. It runs on the 15-second timer and on `raft gc`, under the host lock, and writes each deletion to the host journal with tag `raft`. Running boxes are never touched. A stopped Raft box without `user.raft.stopped-at`, from a guest poweroff, a native stop, a failed start or `raft recover`, gets the worker's current time as its stop time, never an earlier guess, whether or not a policy is set. A malformed retention value makes the worker delete nothing by retention, still enforce deadlines, and exit nonzero; the CLI reports it with the fix. Setting retention requires the current worker protocol; clearing it does not.
+- **Policy scope**: Policies are guardrails for agents, not access controls. Anyone with host SSH and sudo can change them or create boxes with native Incus commands, and controllers without note policy support do not check it. A native `incus start` leaves a stale stop time that retention trusts. `raft config` reports every location's policies and last changes.
+
+`raft capacity [--location NAME] [--json]` inspects hosts without modifying state. Text and JSON (`notice`) lead with: "Advisory estimate only. Raft enforces no box count or size budget; create the boxes your task needs." It reports effective CPUs, total and available RAM, saved and active box counts, active resource limits, headroom, free space in the host disk and the shared pool, and for `raft-disks` its data space, reserved and used bytes and metadata use (`boxDiskPool`, `null` when own box disks are not enabled).
+
+- **Reserve calculations**: Estimates leave out 1 CPU and the larger of 2 GiB or 10% host RAM.
+- **Example shapes**: `estimates` lists shapes doubling from 1 CPU / 2 GiB at 2 GiB per CPU while they fit an empty host, with `fitEmptyHost` and `fitNow` counts. No count is capped.
+- **Headroom**: Subtracts active configured limits and keeps available RAM above the reserve. Every non-`Stopped` state (including `Frozen`) counts as active.
+- **Advisory only**: Nothing in the report blocks creation, resume or fork. Disk space below 5 GiB and `raft-disks` thin pool metadata above 80% trigger warnings; a missing `raft-disks` does not.
 
 ## Container lifecycle and execution
 
 - **Stop and resume**: Stop terminates guest processes and preserves disk contents; stopped boxes retain disk but do not reserve guest RAM. Resume starts the container anew with an explicit TTL without restoring process memory.
 - **Lifetime extension**: `raft extend --ttl` resets a running box's deadline from current host time without restarting; stopped boxes require `raft resume`.
-- **Host worker contract**: `doctor`, disposable creation/fork, and retention cleanup require the current worker protocol. `doctor` checks it without running expiry or changing boxes, and reports the failing location. A mismatch fails before executing deletion policy or creating a disposable box; deploy the current checkout explicitly. Installing a new CLI does not update host workers.
-- **Disposable lifecycle**: `new --disposable` opts a box into deletion on stop or TTL expiry, including its snapshots. Clones and recovered boxes default to persistent; fork accepts an explicit `--disposable`.
-- **Retention cleanup**: `prune --older-than DAYS` previews persistent stopped boxes with a recorded stop timestamp. `--yes` deletes matching boxes under the host lifecycle lock. Running boxes and boxes without a recorded stop time are excluded. No automatic persistent-box deletion is enabled.
-- **Resizing**: Resume and fork accept optional supported CPU/RAM overrides, preserving omitted values. Resume validates stopped state under the lock before changing sizing.
-- **Expiration cleanup**: The host timer checks expirations every 15 seconds, stopping expired persistent containers and deleting expired disposable containers. Expiry may be delayed by graceful shutdown, long locked transactions, and host outage until startup.
-- **Destroy**: Removes the container instance and its snapshots, releasing storage. Destroy confirms absence; SSH failure is not proof of deletion. Disposable boxes created with `new --disposable` are deleted on explicit stop or expiry. Persistent boxes still require explicit destroy for deletion.
+- **Host worker contract**: `doctor`, disposable creation/fork, prune and setting a retention policy require the current worker protocol (2 since 0.6.0, which added retention). `doctor` checks it without running expiry or changing boxes, and reports the failing location. A mismatch fails before executing deletion policy or creating a disposable box; deploy the current checkout explicitly. Installing a new CLI does not update host workers.
+- **Disposable lifecycle**: `new --disposable`, or a configured `disposable` default without `--persistent`, opts a box into deletion on stop or TTL expiry, including its snapshots. Clones and recovered boxes default to persistent whatever the default; fork accepts an explicit `--disposable`.
+- **Manual cleanup**: `prune --older-than DAYS` previews persistent stopped boxes with a recorded stop timestamp. `--yes` deletes matching boxes under the host lifecycle lock. Running boxes and boxes without a recorded stop time are excluded. Automatic deletion of persistent stopped boxes happens only under a host retention policy.
+- **Resizing**: Resume and fork accept optional CPU/RAM overrides, preserving omitted values. Resume validates stopped state under the lock before changing sizing. Neither changes a box's disk.
+- **Expiration cleanup**: The host timer checks expirations every 15 seconds, stopping expired persistent containers, deleting expired disposable containers and applying stopped-box retention. Expiry may be delayed by graceful shutdown, long locked transactions, and host outage until startup.
+- **Destroy**: Removes the container instance and its snapshots, releasing storage. Destroy confirms absence; SSH failure is not proof of deletion. Disposable boxes created with `new --disposable` are deleted on explicit stop or expiry. Persistent boxes still require explicit destroy, prune or a retention policy for deletion.
 - **Execution transport**: Incus exec and file APIs travel over authenticated host SSH without a public Incus listener or injected credentials. Interactive SSH runs a PTY over host SSH and Incus exec.
 - **State inspection and tunnels**: `raft list` and `raft info` read native metadata without guest process counters during shutdown; tunnels use the managed NIC.
-- **Resource reporting**: `raft usage` reports running cgroup memory, CPU microseconds, CPU affinity, and shared pool space. It does not provide per-box disk accounting or billing.
+- **Resource reporting**: `raft usage` reports running cgroup memory, CPU microseconds, CPU affinity, and filesystem space with `filesystemScope`: the shared pool, or `own SIZE box disk`. It provides no billing.
 - **Recursive transfers**: `upload/download --recursive` require a running workspace and Python 3.11.8+ in the guest. They stream a tar archive and publish a new destination directory atomically without overwriting or merging. Relative links contained within the tree, regular files, directories and internal hardlinks are supported; escaping paths/links and special files are rejected. Source entries are pinned with no-follow descriptors before metadata inspection, file reads or directory descent, so pathname replacement cannot redirect access outside the selected tree. Failed transfers leave existing destinations unchanged.
 - **Directory transfer completion**: The receiver verifies the sender's exact archive byte count before publication. A truncated stream, including one ending between complete entries, is rejected without publishing a partial tree.
 - **File transfer failures**: Controller write errors return an error before replacing a download destination or publishing a backup archive.
@@ -79,10 +88,11 @@ Boxes accept an optional note with a fixed template: `purpose` (required), `owne
 
 ## Storage, snapshots, and cloning
 
-- **Storage pool**: A dedicated 60 GiB Btrfs pool per host supports snapshots and clones. Nested container subvolumes prevent strict per-box quota enforcement. The native compressed image cache resides outside the shared pool, so host disk space still matters.
+- **Shared pool**: Boxes default to a dedicated 60 GiB Btrfs pool per host with instant snapshots and clones. Btrfs quotas cannot bound a box there, because nested subvolumes (Docker's, for example) escape them. The native compressed image cache resides outside both pools, so host disk space still matters.
+- **Own box disks**: `new --disk SIZE` puts the box's root on an LVM thin volume of SIZE in `raft-disks`, formatted ext4. All guest writes, including Docker data, land in that filesystem, so writes fail with ENOSPC at SIZE. New own-disk boxes are thin snapshots of the cached image volume, and forks, templates and snapshots of own-disk boxes are thin snapshots of their source. The pool is never overcommitted: under the host lock, before `new`, `new --from`, `fork`, `snapshot` or `recover` adds thin volumes to `raft-disks`, Raft sums the sizes of every thin volume in the pool (from `lvs`) plus the new ones and refuses, before creating anything, if the total exceeds the thin pool's data space. A new volume counts as the larger of its size and its source's; the first own-disk box on a host also counts the image volume (`volume.size`, or 10 GiB); a recovered backup counts its size once per snapshot plus once. `restore` reserves nothing. On a host without `raft-disks`, `new --disk` and recovery of an own-disk backup fail before creating anything and name the deploy command that enables the pool. `fork` and `new --from` keep the source disk; `new --from ... --disk SIZE` copies onto an own disk of SIZE. A disk too small for its contents fails creation.
 - **Stopped-state requirement**: Snapshots, restores and forks require a stopped source for consistent disk contents. Operations run under the host lifecycle lock.
 - **Snapshot restore**: `raft restore` rolls back disk blocks via `--diskonly`, retaining container configuration, limits, and MAC address.
-- **Snapshot management**: `snapshot-delete <box> <name>` removes one named snapshot under the lock. `new --from LOCATION:BOX/SNAPSHOT` creates a same-host box from that snapshot, with normal creation defaults and a fresh network identity. The source may run; the named snapshot is immutable. Templates retain filesystem secrets.
+- **Snapshot management**: `snapshot-delete <box> <name>` removes one named snapshot under the lock. `new --from LOCATION:BOX/SNAPSHOT` creates a same-host box from that snapshot, with the snapshot's CPU, RAM and disk unless `--cpu`, `--memory` or `--disk` overrides them, and a fresh network identity. The source may run; the named snapshot is immutable. Templates retain filesystem secrets.
 - **Workspace forks**: `raft fork` copies filesystem data and secrets to a new container with an independent Incus name, fresh MAC address, and renewed TTL. Source snapshots are not inherited.
 
 ## Background jobs and desktop
@@ -94,5 +104,5 @@ Boxes accept an optional note with a fixed template: `purpose` (required), `owne
 
 - **Export safeguards**: `raft backup` exports stopped containers and snapshots to a local archive. Destination path must not exist, requires mode `0600`, and uses atomic hard-link publication.
 - **Host locking**: Export holds the host lifecycle lock, temporarily delaying expiry checks on the source host.
-- **Recovery admission**: `raft recover` imports archives into a stopped container with a fresh name, new MAC address, and cleared TTL, while enforcing the four-box admission limit. Recovery never overwrites existing boxes.
+- **Recovery**: `raft recover` imports archives into a stopped container with a fresh name, new MAC address, and cleared TTL. It reads the archive's recorded pool from `backup/index.yaml`: own-disk backups return to `raft-disks` with their size after the reservation check, failing on a host without the pool, and other archives land in `raft-data`. The host note policy applies after the reservation check. Recovery never overwrites existing boxes.
 - **Archive security**: Archives contain full container filesystems, including credentials. Native archive configuration is not sanitized; backups do not imply scheduled off-host uploads. Store archives privately and import only trusted exports.

package/docs/first-box.mdx

@@ -83,4 +83,4 @@ raft destroy "$box"
 - [Troubleshooting](./guides/troubleshooting.mdx): Diagnose common errors and inspect host services.
 - [Upgrades and image changes](./guides/upgrades.mdx): Update the controller, hosts, and image pins.
 
-For temporary work, create with `--disposable`. Stopping or expiry then deletes the box and its snapshots. For persistent boxes, `raft prune --older-than 7` previews old stopped workspaces; add `--yes` only after reviewing the candidates.
+For temporary work, create with `--disposable`. Stopping or expiry then deletes the box and its snapshots. For persistent boxes, `raft prune --older-than 7` previews old stopped workspaces; add `--yes` only after reviewing the candidates. A host can also delete boxes left stopped automatically; `raft config` shows each location's `deleteStoppedAfterHours`.

package/docs/guides/backup-recovery.mdx

@@ -53,8 +53,8 @@ echo "Recovered workspace: $recovered"
 
 - **Architecture compatibility**: Target host must match the native CPU architecture (ARM64 to ARM64, AMD64 to AMD64). Cross-architecture recovery is not supported.
 - **Fresh network identity**: The container receives a new name in project `raft`, a new MAC address on `rfbr0`, and no inherited TTL deadline.
-- **Stopped initial state**: Recovered workspaces remain stopped until started with `raft resume "$recovered" --ttl <SECONDS>`.
-- **Enforced admission limit**: The destination location must hold fewer than four boxes.
+- **Stopped initial state**: Recovered workspaces remain stopped until started with `raft resume "$recovered" --ttl <SECONDS>`. Under a host [retention policy](./config-policy.mdx#delete-boxes-left-stopped), the recovered box's clock starts when the host worker first sees it, within about 15 seconds; resume it before the policy's hours pass.
+- **Disk placement**: A backup of a box with its own disk returns to an own disk of the same size in `raft-disks`. The destination needs own box disks enabled and enough unreserved pool space for the box and each of its snapshots; otherwise recovery fails before importing. Other backups land in the shared pool.
 - **Interrupted recovery**: Follow [Host crash during recovery](./troubleshooting.mdx#host-crash-during-recovery). Inspect the reported handle and container state before deleting any staging file.
 
 Start and verify the recovered workspace:

package/docs/guides/config-policy.mdx

@@ -0,0 +1,253 @@
+---
+title: Defaults and host policies
+description: Set controller defaults for new boxes, require box note fields on a host and delete boxes left stopped.
+---
+
+# Defaults and host 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 --require` |
+| Stopped-box retention | Incus project `raft` on each host | Every box on the host | `raft policy --delete-stopped-after` |
+
+`raft config` prints both kinds: the effective defaults with their source, and
+each location's policies.
+
+```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"
+    },
+    "disposable": {
+      "value": true,
+      "source": "config"
+    }
+  },
+  "policy": {
+    "lab": {
+      "require": [
+        "purpose",
+        "owner"
+      ],
+      "requireChanged": "2026-10-21T09:12:44Z by ubuntu from me@laptop",
+      "deleteStoppedAfterHours": 48,
+      "deleteStoppedAfterSince": 1792573964,
+      "deleteStoppedAfterChanged": "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`, `disk` and
+`disposable`:
+
+```sh title="CONTROLLER: Prefer bigger, longer, temporary 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 set disposable true
+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, persistent). `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.
+
+With `disposable true`, every `raft new` box is deleted, with its snapshots, when
+it stops or expires. `raft new --persistent` keeps one box anyway, and
+`--disposable` overrides `disposable false` the same way. The default applies to
+`new --from` too: a snapshot has no lifecycle of its own. A fork stays
+persistent unless it gets `--disposable`, whatever the default says, like every
+other fork setting.
+
+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 | Disposable |
+| --- | --- | --- | --- |
+| `new` | Flag, then config, then 1 CPU / 2 GiB | Flag, then config, then the shared pool | Flag, then config, then persistent |
+| `new --from` | Flag, then the snapshot's | `--disk SIZE`, then the snapshot's | Flag, then config, then persistent |
+| `fork` | Flag, then the source's | The source's | `--disposable`, else persistent |
+
+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 boxes should pass `--location`, `--ttl`,
+`--cpu`, `--memory`, `--disk` and `--disposable` or `--persistent` 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 --require none
+```
+
+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.
+
+## Delete boxes left stopped
+
+A retention policy makes a host delete boxes that stay stopped too long, with
+their snapshots. Use it when agents create boxes and forget them:
+
+```sh title="CONTROLLER: Delete boxes stopped for 48 hours on lab"
+raft policy lab --delete-stopped-after 48
+raft policy lab --delete-stopped-after never
+```
+
+The host expiry worker applies it every 15 seconds, and on `raft gc`, even when
+no controller is online. It deletes a stopped box once the given hours have
+passed since the later of:
+
+- the box's stop, recorded in `user.raft.stopped-at` by `raft stop` and expiry;
+- the policy change, recorded in `user.raft.delete-stopped-after.since`.
+
+So a new or shorter policy never deletes a box sooner than its hours after the
+change, including boxes that were stopped long before. Lengthening it or setting
+it again restarts the grace period the same way.
+
+| Box | What retention does |
+| --- | --- |
+| Running, including one whose TTL has not expired | Nothing |
+| Stopped with `raft stop` or expiry | Deleted HOURS after the later of the stop and the policy change |
+| Stopped another way: a poweroff inside the box, a native `incus stop`, a failed start or `raft recover` | The worker records the time it first sees the box stopped, and the clock starts then |
+| Resumed before its deadline | Nothing; `resume` clears the stop time, and the next stop starts a new clock |
+
+`raft list` shows when each stopped box will go, as `deleteAt`:
+
+```sh title="CONTROLLER: Stopped boxes and their deletion times"
+raft list --location lab | jq -r 'select(.deleteAt != "") | "\(.box) \(.deleteAt | tonumber | todate)"'
+```
+
+Retention deletes the whole box. Keep anything you need with
+[`raft backup`](./backup-recovery.mdx) before the deadline, or resume the box to
+reset its clock. Snapshots live inside the box and are deleted with it.
+
+Retention needs the current host worker. On a host deployed by an older release,
+`--delete-stopped-after HOURS` fails with
+`Host expiry worker differs from this CLI; deploy the current Raft checkout first`
+and changes nothing; redeploy the host, see
+[Upgrades and image changes](./upgrades.mdx). Clearing it with `never` works on
+any worker.
+
+`raft prune --older-than DAYS` remains a manual, previewed cleanup that works
+with or without a retention policy.
+
+## Audit trail
+
+`raft policy` prints each change, for example
+`lab: required note fields none -> purpose,owner` or
+`lab: delete stopped boxes after never -> 48 hours`. The host records the last
+change of each policy in a `.changed` project key (UTC time, the SSH account and
+the controller's self-reported user and hostname) and writes a `raft` entry to
+the host journal. The worker adds a journal entry for every box retention
+deletes:
+
+```sh title="HOST: Review policy changes and retention deletions"
+sudo incus project get raft user.raft.require
+sudo incus project get raft user.raft.require.changed
+sudo incus project get raft user.raft.delete-stopped-after
+sudo incus project get raft user.raft.delete-stopped-after.changed
+sudo journalctl -t raft
+```
+
+## Limits
+
+Host policies are a guardrail for agents, not a security boundary:
+
+- Anyone with SSH and sudo on the host can change or remove a policy, or create
+  boxes with native `incus` commands that skip the note policy.
+- Retention trusts `user.raft.stopped-at`. The worker clears it when it sees a
+  box running, but a native `incus start` and stop between two worker runs (15
+  seconds apart) keeps the old stop time, so the box can be deleted on the next
+  run. Use `raft resume`, which clears the stop time.
+- Controllers older than the release that added note policies do not check
+  them. Upgrade every controller that uses a host before relying on one. The
+  host worker enforces retention whatever the controller version.
+- The controller identity in the `.changed` keys 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

@@ -24,13 +24,19 @@ Raft has no option to disable automatic expiry.
 | `resume --ttl SECONDS` | Starts the saved box with a new deadline | Only possible while the box still exists |
 | `destroy` | Deletes the box and snapshots | Deletes the box and snapshots |
 
-Use `raft new --disposable` for temporary work. A fork is persistent unless
+Use `raft new --disposable` for temporary work, or
+`raft config set disposable true` to make it the default on this controller;
+`raft new --persistent` then keeps one box. 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;
-`--yes` applies deletion. There is no automatic persistent-box retention cleanup.
+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. To delete them automatically, set a host retention
+policy: with `raft policy lab --delete-stopped-after 48`, the host deletes any
+box left stopped for 48 hours, and `raft list` shows each one's `deleteAt`.
+Resuming a box resets its clock. See
+[Defaults and host policies](./config-policy.mdx#delete-boxes-left-stopped).
 
 ## 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`, `note` |
+| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `deleteAt`, `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,24 +33,38 @@ 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. `note` is the box note object with
+as a string, or an empty string when absent. `deleteAt` is the Unix time the
+location's retention policy deletes a stopped box, in the same form, or an empty
+string. `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`,
+`--disk` and `--disposable` or `--persistent` in CI.
+Hosts can also require box note fields; give `--purpose`, `--owner` and `--next`
+so a policy cannot fail the job. A host retention policy can delete a box left
+stopped between jobs; see [Defaults and host 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
 
@@ -58,6 +74,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.
@@ -73,7 +90,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
@@ -110,10 +127,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, even when `raft config` sets `disposable true`; add `--disposable` to delete a clone when it stops or expires.