@microck/raft 0.4.0 → 0.6.0

package/docs/reference/cli.md

@@ -14,6 +14,12 @@ Syntax:
 and `raft --version` prints the installed version without loading configuration.
 Output is command-specific; see [Scripting and CI](../guides/scripting-ci.mdx).
 
+At most once a day, after a command finishes, Raft checks GitHub for a newer
+release and prints one line on stderr, such as
+`raft 0.7.0 is available (you have 0.6.0). Run: raft self-update`. It never
+installs anything or changes stdout, and network failures stay silent. See
+[`self-update`](#self-update) to turn it off.
+
 Workspaces are referenced by location-qualified handles formatted as `<location>:<instance-name>` (for example `lab:rf-a1b2c3d4e5f60718`).
 
 ## Command index
@@ -28,7 +34,9 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 | Port forwarding and desktop | [`forward`](#forward), [`desktop`](#desktop) |
 | Backup and recovery | [`backup`](#backup), [`recover`](#recover) |
 | Locations | [`host add`](#host-add), [`locations`](#locations), [`note`](#note) |
-| Host inspection and maintenance | [`limits`](#limits), [`doctor`](#doctor), [`list`](#list), [`gc`](#gc), [`prune`](#prune) |
+| Defaults and policies | [`config`](#config), [`policy`](#policy) |
+| Host inspection and maintenance | [`capacity`](#capacity), [`doctor`](#doctor), [`list`](#list), [`gc`](#gc), [`prune`](#prune) |
+| CLI maintenance | [`self-update`](#self-update) |
 
 ## Workspace lifecycle commands
 
@@ -36,19 +44,29 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 
 Create and launch a new workspace container.
 
-`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
+`raft new [--location LOCATION] [--ttl TTL] [--cpu N] [--memory SIZE] [--disk SIZE] [--disposable | --persistent] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
+
+- `--location LOCATION`: Target host location in `~/.config/raft/incus.json`. Built-in default: first configured location.
+- `--ttl TTL`: Lifetime in seconds before automatic stop (`60` to `2592000`). Built-in default: `600`.
+- `--cpu N`: CPU limit, any whole number from `1` up to the host's CPU count. Built-in default: `1`, or the snapshot's with `--from`.
+- `--memory SIZE`: Memory limit in whole GiB, for example `16GiB`, up to the host's RAM. Built-in default: `2GiB`, or the snapshot's with `--from`.
+- `--disk SIZE`: Give the box its own disk of SIZE in whole GiB, for example `20GiB`, instead of the shared pool. Needs a host deployed with `--disk-pool`. The box, and Docker inside it, cannot write past SIZE, and the pool reserves SIZE when the box is created. `--disk shared` asks for the shared pool, overriding a configured `disk`. Built-in default: the shared pool, or with `--from` the snapshot's disk. See [Box sizing and own disks](./capacity.mdx#own-box-disks).
 
-- `--location LOCATION`: Target host location in `~/.config/raft/incus.json`. Defaults to first configured location.
-- `--ttl TTL`: Lifetime in seconds before automatic stop (`60` to `2592000`). Default: `600`.
-- `--cpu {1,2}`: CPU core count managed by Incus. Default: `1`.
-- `--memory {1GiB,2GiB,4GiB,8GiB}`: Memory limit. Default: `2GiB`.
+An omitted option takes the controller default set with [`config`](#config),
+then the built-in default. With `--from`, configured `cpu`, `memory` and `disk`
+defaults do not apply: the box keeps the snapshot's size unless a flag overrides
+it, and `--disk shared` is refused.
 
-- `--disposable`: Delete the box and snapshots on stop or expiry. Off by default.
-- `--from LOCATION:BOX/SNAPSHOT`: Copy a named snapshot on its source host instead of the configured image. Normal creation sizing applies; the source can be running. Cannot target a different location.
-- `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Record a [box note](#note). `--owner` and `--next` need `--purpose`. Without them the box starts with no note, including boxes created `--from` a noted snapshot.
+- `--disposable`: Delete the box and snapshots on stop or expiry. Built-in default: persistent.
+- `--persistent`: Keep the box and its disk on stop or expiry, overriding a configured `disposable` default. Cannot be combined with `--disposable`.
+- `--from LOCATION:BOX/SNAPSHOT`: Copy a named snapshot on its source host instead of the configured image. The box keeps the snapshot's CPU, RAM and disk unless `--cpu`, `--memory` or `--disk` overrides them; the source can be running. Cannot target a different location.
+- `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Record a [box note](#note). `--owner` and `--next` need `--purpose`. Without them the box starts with no note, including boxes created `--from` a noted snapshot. A host [policy](#policy) can require fields.
 
 Returns the qualified workspace handle. If the location has a note, `new` prints
-it to stderr; stdout still contains only the handle.
+it to stderr; stdout still contains only the handle. Raft limits neither the
+number of boxes nor their size; requests larger than the whole host, own disks
+on a host without `raft-disks`, or own disks larger than the unreserved
+`raft-disks` space, fail with the reason before anything is created.
 
 ### `stop`
 
@@ -62,12 +80,13 @@ Terminates guest processes and stops the container. Persistent boxes retain file
 
 Start a stopped workspace with a renewed lifetime deadline.
 
-`raft resume <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}]`
+`raft resume <box> --ttl TTL [--cpu N] [--memory SIZE]`
 
 - `--ttl TTL`: Lifetime in seconds from resumption (`60` to `2592000`). Required.
 
 CPU/RAM overrides on resume apply before startup. Omitted values stay unchanged.
-A running box is rejected before changing its limits.
+A running box is rejected before changing its limits. Resume never changes the
+box's disk.
 
 ### `extend`
 
@@ -83,7 +102,7 @@ Permanently delete a workspace container and its snapshots.
 
 `raft destroy <box>`
 
-Stops the container if running, removes all associated Btrfs snapshots, and releases host storage.
+Stops the container if running, removes all associated snapshots, and releases its storage, including an own disk.
 
 ## Execution and inspection commands
 
@@ -109,13 +128,13 @@ Open an interactive root terminal session inside the workspace over host SSH and
 
 ### `info`
 
-Display container metadata from Incus in JSON format, including status, IP addresses, resource limits, and timestamps.
+Display container metadata from Incus in JSON format, including status, IP addresses, resource limits, and timestamps. `expanded_devices.root` shows the disk: `pool: raft-data` for the shared pool, or `pool: raft-disks` with the own disk's `size`.
 
 `raft info <box>`
 
 ### `usage`
 
-Display active resource consumption for a running workspace: cgroup memory, CPU microseconds, CPU affinity, and shared-pool disk space.
+Display active resource consumption for a running workspace: cgroup memory, CPU microseconds, CPU affinity, and filesystem space. `filesystemScope` says whether the space is the shared pool or the box's own disk.
 
 `raft usage <box>`
 
@@ -175,6 +194,8 @@ Create a named point-in-time snapshot of a stopped workspace. Names use alphanum
 
 `raft snapshot <box> <name>`
 
+A snapshot of a box with its own disk is a thin snapshot that reserves the box's disk size in `raft-disks`; it fails before anything is created when the pool lacks unreserved space.
+
 ### `snapshots`
 
 List existing snapshots and creation timestamps for a workspace.
@@ -197,11 +218,13 @@ Roll back a stopped workspace filesystem to a named snapshot using `--diskonly`,
 
 Clone a stopped workspace into an independent container on the same host and start it.
 
-`raft fork <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable]`
+`raft fork <box> --ttl TTL [--cpu N] [--memory SIZE] [--disposable] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
 
 - `--ttl TTL`: Lifetime in seconds for the clone. Required.
+- `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Replace the clone's whole note. Without them the clone keeps the source note.
 
-Omitted CPU/RAM values inherit the source limits. The clone is persistent unless `--disposable` is supplied, regardless of the source policy.
+Omitted CPU/RAM values inherit the source limits; controller defaults never apply to forks. The clone keeps the source's disk: the shared pool, or an own disk of the same size as a thin snapshot, which reserves that size in `raft-disks`. To copy a box onto a disk of another size, snapshot it and use `new --from BOX/SNAPSHOT --disk SIZE`. The clone is persistent unless `--disposable` is supplied, regardless of the source and of a configured `disposable` default.
+The note the clone ends up with must satisfy the host [policy](#policy).
 
 Returns the qualified handle of the clone.
 
@@ -240,12 +263,17 @@ Export a stopped workspace and its snapshots to a compressed archive on the cont
 
 Import a portable backup archive onto a host as a fresh stopped workspace.
 
-`raft recover <source> --location LOCATION`
+`raft recover <source> --location LOCATION [--purpose TEXT [--owner TEXT] [--next TEXT]]`
 
 - `<source>`: Path to archive file on controller.
 - `--location LOCATION`: Target host location. Required.
+- `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Replace the recovered box's whole note. Without them it keeps the archived note.
+
+Under a host [policy](#policy), a given note is checked before the upload. An
+archived note is checked after import; if it fails, the imported box is deleted
+in the same locked step.
 
-Returns the qualified handle of the imported stopped workspace.
+Returns the qualified handle of the imported stopped workspace. A backup of a box with its own disk is recovered onto an own disk of the same size in `raft-disks`, which must exist on the destination and have room to reserve that size for the box and each of its snapshots; any other backup lands in the shared pool.
 
 ## Location commands
 
@@ -253,19 +281,20 @@ Returns the qualified handle of the imported stopped workspace.
 
 Check, provision and register a new workspace host, then prove it works.
 
-`raft host add LOCATION --ssh TARGET [--image-release TAG | --image-archive PATH | --build] [--dry-run] [--yes]`
+`raft host add LOCATION --ssh TARGET [--image-release TAG | --image-archive PATH | --build] [--disk-pool SIZE] [--dry-run] [--yes]`
 
 - `LOCATION`: New location name. Existing locations are rejected.
 - `--ssh TARGET`: Key-based SSH target, such as `ubuntu@192.0.2.10` or an `~/.ssh/config` alias. Accept the host key interactively first.
 - `--image-release TAG`: Download `raft-dev-<arch>.tar.gz` from this release on the host and verify it against the release `SHA256SUMS`. Default: the CLI's own version.
 - `--image-archive PATH`: Upload and import a local image archive instead.
 - `--build`: Build the image on the host from Debian 13 instead.
+- `--disk-pool SIZE`: Enable [own box disks](./capacity.mdx#own-box-disks) with a `raft-disks` thin pool of SIZE, in whole GiB. Default: not enabled. The pool's file takes its full size on the host disk when created. To enable them on a host that is already deployed, run `python3 deploy/deploy.py --location LOCATION --disk-pool SIZE`. An existing pool keeps its size; a different explicit value is refused.
 - `--dry-run`: Probe the host and print the plan without changing anything.
 - `--yes`: Apply the plan without the interactive prompt. Without a terminal, `--yes` is required.
 
 Before any change, a read-only probe checks SSH, passwordless sudo, Ubuntu 22.04 or
 24.04, ARM64 or AMD64, python3, at least 2 CPUs, 8 GiB RAM and, for a fresh host,
-80 GiB free disk. Unsupported targets, including macOS, fail with the reasons and
+80 GiB of free disk, plus the `--disk-pool` size when given. Unsupported targets, including macOS, fail with the reasons and
 no changes. The command then runs the deployer, imports the image only if its
 checksum and architecture match, adds the location with the pinned fingerprint,
 and runs `doctor` plus a disposable create/exec/destroy smoke test. If the final
@@ -301,7 +330,7 @@ Set or clear the note of a location or a box.
 
 Location notes are operator guidance stored in `~/.config/raft/incus.json`. Use
 them to record which host is preferred or what a host should not run. Raft shows
-them in `locations`, `limits` and `new`.
+them in `locations`, `capacity` and `new`.
 
 Box notes tell other agents and people why a box exists. They follow one
 template, stored on the box as JSON in the Incus key `user.raft.note`:
@@ -313,28 +342,103 @@ template, stored on the box as JSON in the Incus key `user.raft.note`:
 | `next` | What happens to it next | `Destroy after the tests pass` |
 
 Each call replaces the whole note, on running or stopped boxes. `raft list`
-shows it as `note`. Forks and recovered backups keep the source box's note;
-update it if the copy has a different job.
+shows it as `note`. Forks and recovered backups keep the source box's note
+unless `fork` or `recover` gets note flags; update it if the copy has a
+different job.
+
+Empty values are rejected; use `--clear` to remove a note. A host
+[policy](#policy) can require fields, and then rejects notes and `--clear` that
+would leave them out. Otherwise Raft does not interpret notes.
+
+### `config`
+
+Show or change the controller defaults for `new`.
+
+`raft config`
+`raft config set KEY VALUE`
+`raft config unset KEY`
+
+- `KEY`: One of `location`, `ttl`, `cpu`, `memory`, `disk`, `disposable`.
+- `VALUE`: Accepted exactly when the same text is accepted by the matching `new` flag. A `location` must be configured. `disposable` takes `true` or `false`.
+
+`disposable true` makes `new` create disposable boxes, including `new --from`,
+because a snapshot carries no lifecycle; `--persistent` keeps one box. `fork`
+ignores it: a fork is persistent unless it gets `--disposable`.
+
+`cpu`, `memory` and `disk` size only boxes created from the image. `new --from`
+and `fork` keep the source's CPU, RAM and disk; only explicit flags change them.
+A `disk` default on a location without `raft-disks`, or larger than its
+unreserved space, fails `new` with the same error as `--disk`, plus a sentence
+naming `defaults.disk` as the source. `--disk shared` overrides it for one box.
+
+Defaults live in `~/.config/raft/config.json` as `{"defaults": {"KEY": VALUE}}`.
+`set` and `unset` print the old and new value, write atomically under a
+controller lock and keep mode `0600`. An unknown key, bad value or malformed
+file makes `new` fail with the file path and key; `set` or `unset` that key to
+repair it.
+
+`raft config` prints one JSON object: `file`, `defaults` (each key's `value` and
+`source`, `config` or `built-in`) and `policy`. For each location, `policy` has
+`require` (the required note fields), `deleteStoppedAfterHours` (`null` without
+retention), `deleteStoppedAfterSince` (when retention was set, Unix seconds) and
+the last change records `requireChanged` and `deleteStoppedAfterChanged`. It
+contacts every configured host to read policies.
+See [Defaults and host policies](../guides/config-policy.mdx).
+
+### `policy`
+
+Set or clear a location's host policies: the box note fields it requires and
+how long it keeps stopped boxes.
+
+`raft policy LOCATION [--require FIELDS|none] [--delete-stopped-after HOURS|never]`
 
-Notes are advisory; Raft never enforces them. Empty values are rejected; use
-`--clear` to remove a note.
+- `--require FIELDS`: Comma-separated fields from `purpose`, `owner`, `next`. Must include `purpose`. `--require none` stops requiring fields.
+- `--delete-stopped-after HOURS`: Delete boxes that stay stopped for HOURS, a positive whole number, with their snapshots. `--delete-stopped-after never` keeps stopped boxes.
+
+Give either option or both; each changes only its own policy. Both values are
+checked before the host changes.
+
+Policies are stored on the host in the Incus project `raft`, so they apply to
+every controller. The command prints each change and the host records the time,
+SSH account and controller in a `.changed` key beside the policy and in the host
+journal (`journalctl -t raft`).
+
+The note policy lives in `user.raft.require`. `new`, `fork`, `recover` and
+`note` check it on the controller for an actionable error, then again in the
+host transaction that writes the note.
+
+Retention lives in `user.raft.delete-stopped-after`, with the time it was set in
+`user.raft.delete-stopped-after.since`. The host expiry worker deletes a stopped
+box once HOURS have passed since the later of its stop and that time, so a new
+or shorter policy never deletes a box sooner than HOURS after the change. The
+worker runs every 15 seconds and on [`gc`](#gc), logs each deletion to the host
+journal and never touches running boxes. A stopped box with no recorded stop
+time, such as one powered off from inside, stopped with native `incus` or
+recovered from a backup, starts its clock when the worker first sees it.
+[`list`](#list) shows each box's `deleteAt`. Setting retention needs the current
+host worker; on an older one it fails with redeploy guidance.
+
+Policies are guardrails for agents, not a security boundary: SSH and sudo on the
+host can change or bypass them, and older controllers do not check note policies.
 
 ## Host inspection and maintenance commands
 
-### `limits`
+### `capacity`
 
-Inspect host resource capacity, active allocations, and recommended workspace limits.
+Estimate how many more boxes a host can run well. The report is advice: Raft
+enforces no box count or size budget, so create the boxes your task needs.
 
-`raft limits [--location LOCATION] [--json]`
+`raft capacity [--location LOCATION] [--json]`
 
 - `--location LOCATION`: Filter report to a specific host.
 - `--json`: Output report as JSON.
 
-Each report includes the location's `note`, if any.
+Each report leads with that advisory notice and includes the location's `note`,
+if any. See [Box sizing and capacity](./capacity.mdx) for the fields.
 
 ### `doctor`
 
-Inspect host connectivity, Incus version, expiry-worker compatibility, active systemd units (`incus`, `raft-expire.timer`, `raft-network.service`), root filesystem usage, storage pool status, and saved box count across configured hosts. An incompatible worker returns a nonzero exit status and names the failing location without running expiry or modifying boxes.
+Inspect host connectivity, Incus version, expiry-worker compatibility, active systemd units (`incus`, `raft-expire.timer`, `raft-network.service`), root filesystem usage, status of the shared `raft-data` pool and, when own box disks are enabled, the `raft-disks` pool, and saved box count across configured hosts. Without `raft-disks` it prints `own box disks: not enabled (redeploy with --disk-pool SIZE)` and does not fail. An incompatible worker returns a nonzero exit status and names the failing location without running expiry or modifying boxes.
 
 `raft doctor`
 
@@ -344,14 +448,17 @@ List existing workspace containers across configured hosts.
 
 `raft list [--location LOCATION]`
 
-Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt` and `note` fields.
+Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt`, `deleteAt`, `disk` and `note` fields.
+`deleteAt` is the Unix time when the location's [retention](#policy) deletes a
+stopped box, as a string like `stopAt`, or `""` when no deletion is due.
+`disk` is `"shared"` for the shared pool or the own disk's size, such as `"20GiB"`.
 `note` is the box note object, or `null` when the box has none.
 An empty inventory prints no records. See [Scripting and CI](../guides/scripting-ci.mdx)
 for output formats, exit codes, readiness, and failure handling.
 
 ### `gc`
 
-Enforce deadlines immediately. Persistent boxes stop; disposable boxes are deleted.
+Enforce deadlines and retention immediately. Persistent boxes stop; disposable boxes are deleted; stopped boxes past the location's [retention](#policy) are deleted.
 
 `raft gc [--location LOCATION]`
 
@@ -361,6 +468,42 @@ Preview deletion of persistent stopped boxes older than the selected number of d
 
 `raft prune --older-than DAYS [--location LOCATION] [--yes]`
 
-Days must be at least one. Without `--yes`, this only prints JSONL candidates. With `--yes`, it deletes matching boxes and their snapshots under the host lock. Running boxes and boxes without a recorded stop time are excluded. Stop timestamps come from Raft stop/expiry, not box creation. No automatic retention policy is enabled.
+Days must be at least one. Without `--yes`, this only prints JSONL candidates. With `--yes`, it deletes matching boxes and their snapshots under the host lock. Running boxes and boxes without a recorded stop time are excluded. Stop timestamps come from Raft stop/expiry, or from the host worker when it first sees a box stopped another way, never from box creation. For automatic deletion, set a [retention policy](#policy).
+
+Disposable creation/fork, prune and setting retention require the current expiry worker installed through the deployer. A mismatch fails with deployment guidance; the CLI does not install or adapt an older worker.
+
+## CLI maintenance commands
+
+### `self-update`
+
+Upgrade the installed CLI to the latest GitHub release, or to a chosen one.
+
+`raft self-update [--check | --version X.Y.Z]`
+
+- `--check`: Report whether a newer release exists without installing it. Exits `0` when the CLI is current and `100` when an update is available.
+- `--version X.Y.Z`: Install this release instead of the latest, for example to roll back. Without it, `self-update` never downgrades.
+
+The latest release on GitHub decides what is current. `self-update` installs
+through the channel that installed the running copy and never switches channel:
+
+| Installed with | Detected by | Upgrade | Integrity |
+| --- | --- | --- | --- |
+| `npm install -g @microck/raft` | `PREFIX/lib/node_modules/@microck/raft`, linked from `PREFIX/bin/raft` | `npm install --global --prefix PREFIX @microck/raft@X.Y.Z` | npm checks the registry integrity hash; Raft publishes with npm provenance |
+| `uv tool install` of a release wheel | A uv tool environment named `raft` | Downloads the wheel and `SHA256SUMS` from the release, then `uv tool install --force` | Refuses a wheel whose SHA-256 differs from the release `SHA256SUMS` |
+
+Source checkouts, editable installs, pip and other layouts are refused with
+instructions. For a uv tool, `uv tool dir` must still name the original tool
+directory; set `UV_TOOL_DIR` if it moved.
+
+`self-update` prints `raft OLD -> NEW` and the release notes link. A current CLI
+is a no-op. Hosts are not changed: run [`doctor`](#doctor) next. If a host's
+worker differs from the new CLI, redeploy that host from the same release; see
+[Upgrades and image changes](../guides/upgrades.mdx). After an update,
+[`host add`](#host-add) downloads the new release's image by default. Existing
+image pins stay unchanged.
 
-Disposable creation/fork and prune require the current expiry worker installed through the deployer. A mismatch fails with deployment guidance; the CLI does not install or adapt an older worker.
+Set `RAFT_NO_UPDATE_CHECK=1` to turn off the daily release notice, for example in
+pinned or scripted runs. The notice caches its last result in
+`$XDG_CACHE_HOME/raft/update.json` (default `~/.cache/raft/update.json`). It
+waits at most 2 seconds for GitHub and is skipped for `self-update` and
+`--version`.

package/docs/reference/configuration.mdx

@@ -40,7 +40,7 @@ The configuration file maps location names to host definition objects:
 ### Location keys
 
 - **Naming format**: Matches `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`. Starts with an alphanumeric character and contains ASCII letters, digits, underscores, or hyphens.
-- **Default location**: The first location listed is the default for `raft new`. `raft list`, `raft limits`, `raft gc`, and `raft prune` accept `--location` filters. Without a filter they check all configured hosts; `raft doctor` always checks all configured hosts.
+- **Default location**: The first location listed is the default for `raft new`. `raft list`, `raft capacity`, `raft gc`, and `raft prune` accept `--location` filters. Without a filter they check all configured hosts; `raft doctor` always checks all configured hosts.
 
 ### Host entry fields
 
@@ -60,7 +60,7 @@ raft note spare --clear
 ```
 
 `raft note` rewrites the file with two-space indentation, keeps location order and
-mode `0600`. `raft locations`, `raft limits` and `raft new` show the note.
+mode `0600`. `raft locations`, `raft capacity` and `raft new` show the note.
 
 <Callout type="warn" title="Replace placeholder image fingerprint">
 The `image` field requires the full 64-character hash for `raft new`; aliases such as `raft-dev` are rejected. Replace the example hash with the actual imported image fingerprint for that host.
@@ -68,6 +68,44 @@ The `image` field requires the full 64-character hash for `raft new`; aliases su
 ARM64 and AMD64 images produce different fingerprints; do not reuse an ARM64 hash on an AMD64 host.
 </Callout>
 
+## Defaults for new
+
+`~/.config/raft/config.json` is optional. It sets defaults for `raft new` on this
+controller and is separate from the location inventory:
+
+```json title="Example ~/.config/raft/config.json"
+{
+  "defaults": {
+    "location": "lab",
+    "ttl": 3600,
+    "cpu": 2,
+    "memory": "4GiB",
+    "disk": "20GiB",
+    "disposable": true
+  }
+}
+```
+
+| Key | Accepted values | Built-in default |
+| :--- | :--- | :--- |
+| `location` | A configured location name | First configured location |
+| `ttl` | `60` to `2592000` seconds | `600` |
+| `cpu` | A positive whole number | `1` |
+| `memory` | Whole GiB, e.g. `16GiB` | `2GiB` |
+| `disk` | Whole GiB for an own box disk, or `shared` | `shared` |
+| `disposable` | `true` or `false` | `false` (persistent) |
+
+Explicit flags win over these values; `--persistent` overrides `disposable`.
+`cpu`, `memory` and `disk` size only boxes created from the image: `new --from`
+and `fork` keep the source's size unless a flag overrides it. `disposable`
+applies to `new` and `new --from`, never to `fork`. A `disk` default needs the `raft-disks` pool on the target
+host, like `--disk`. Unknown keys and invalid values make
+`raft new` fail with the file path and key. Edit the file with
+`raft config set KEY VALUE` and `raft config unset KEY`, and inspect it with
+`raft config`. Required box note fields and stopped-box retention are host
+policies, not part of this file; see
+[Defaults and host policies](../guides/config-policy.mdx).
+
 ## SSH configuration and connection behavior
 
 Primary remote commands (`raft ssh`, `upload`, `download`, and control commands) run OpenSSH with `BatchMode=yes` and `-o ConnectTimeout=10` to fail fast on unreachable hosts. The timeout applies to initial connection establishment, not session or transfer duration.

package/docs/reference/meta.json

@@ -5,6 +5,6 @@
   "pages": [
     "cli",
     "configuration",
-    "capacity-limits"
+    "capacity"
   ]
 }

package/docs/releases/0.5.0.md

@@ -0,0 +1,19 @@
+---
+title: Raft 0.5.0
+---
+
+# Raft 0.5.0
+
+- **No box cap.** A location no longer stops at four saved boxes. Agents create the boxes their task needs; creation only fails for real reasons such as a full pool.
+- **Any size.** `--cpu N` and `--memory NGiB` accept any positive size up to the host's CPUs and RAM. A box from the image gets 1 CPU, 2 GiB and the shared disk; `new --from` and `fork` keep the source's CPU, RAM and disk, and each flag overrides only its own value.
+- **Own box disks.** `raft new --disk SIZE` gives a box its own ext4 disk with a hard cap that also holds for Docker inside the box. Own disks are opt-in per host: redeploy with `--disk-pool SIZE` to create the thin LVM pool `raft-disks`. New boxes, forks, template copies and snapshots are copy-on-write, and a reservation check refuses any request that would overcommit the pool. `raft list` shows each box's `disk`.
+- **`raft capacity` replaces `raft limits`.** It is advisory only: it reports host CPUs, RAM, allocations, both pools and how many more boxes of example sizes fit, and never limits creation. JSON fields changed (`boxes`, `estimates`, `sharedPool`, `boxDiskPool`, `headroom`, `notice`).
+- **`raft self-update`.** Updates the CLI through the channel that installed it: npm, or a uv tool from the release wheel verified against `SHA256SUMS`. `--check` reports without installing (exit 100 when an update exists) and `--version X.Y.Z` installs a specific release. A notice on stderr at most once a day says when a newer release exists; `RAFT_NO_UPDATE_CHECK=1` turns it off. It never installs on its own and never changes hosts.
+- **Controller defaults.** `raft config`, `raft config set KEY VALUE` and `raft config unset KEY` manage `~/.config/raft/config.json` with defaults for `location`, `ttl`, `cpu`, `memory` and `disk`. A flag beats the config, which beats the built-in default. `--disk shared` overrides a configured disk default for one box.
+- **Note policies.** `raft policy LOCATION --require purpose,owner` makes a host require those box note fields. `new`, `fork`, `recover` and `note` refuse a box without them, with an error naming the missing flag, and the host checks again under its lock. Policy changes are recorded on the host and in its journal. This is a guardrail for agents, not a security boundary.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.5.0`, or install the attached Python wheel; existing installs can run `raft self-update`.
+
+Redeploy each host with this release's `deploy/deploy.py`. It installs `lvm2` and `python3-yaml`, which `raft recover` now needs to read backups, and changes nothing else unless you add `--disk-pool SIZE` to enable own box disks. That needs SIZE plus 20 GiB free on the host; existing storage is never resized.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/releases/0.6.0.md

@@ -0,0 +1,16 @@
+---
+title: Raft 0.6.0
+---
+
+# Raft 0.6.0
+
+- **Disposable by default.** `raft config set disposable true` makes `raft new` create disposable boxes, which are deleted with their snapshots when they stop or expire. `raft new --persistent` keeps one box anyway, and `--disposable` still works the other way. The default also applies to `new --from`; a fork stays persistent unless you pass `--disposable`. `raft config` shows the setting.
+- **Delete boxes left stopped.** `raft policy LOCATION --delete-stopped-after 48` makes a host delete boxes, with their snapshots, once they have been stopped for 48 hours. The host applies it every 15 seconds and on `raft gc`, even with no controller online, logs each deletion to its journal (`journalctl -t raft`) and never touches running boxes. A new or shorter policy never deletes a box sooner than its hours after the change, and resuming a box resets its clock. `raft list` shows each stopped box's `deleteAt`. `--delete-stopped-after never` turns it off.
+- **Stop times for every stopped box.** The host now records a stop time for boxes stopped outside `raft stop`, such as a poweroff inside the box, a native `incus stop` or a recovered backup, when it first sees them. `raft prune` can therefore select them later; before, it skipped them forever.
+- **`raft policy` changes.** `--require` and `--delete-stopped-after` can be set together or alone, and each changes only its own policy. `--require none` replaces `--clear`, which is gone. In `raft config`, each location's `changed` field is now `requireChanged`, beside the new `deleteStoppedAfterHours`, `deleteStoppedAfterSince` and `deleteStoppedAfterChanged`.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.6.0`, or install the attached Python wheel; existing installs can run `raft self-update`.
+
+Redeploy each host with this release's `deploy/deploy.py`. The host expiry worker changed, and until a host is redeployed `raft doctor` reports it, while `new --disposable` (including a disposable default), `fork --disposable`, `raft prune` and `raft policy --delete-stopped-after HOURS` fail on it with redeploy guidance. Redeploying changes nothing else on the host and sets no retention policy.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/requirements.mdx

@@ -17,11 +17,11 @@ Each workspace host must be a dedicated physical machine or virtual instance:
 | **Operating system** | Ubuntu 22.04 LTS or 24.04 LTS | The deployer installs Incus 6.0 LTS and nftables bridge isolation rules. |
 | **CPU** | At least 2 CPU cores | Capacity calculations reserve 1 CPU core for the host OS and services (an advisory estimate, not an enforced host reservation). |
 | **RAM** | At least 8 GiB | Sizing calculations reserve the larger of 2 GiB or 10% of host RAM (an advisory estimate, not an enforced host reservation). |
-| **Free disk** | At least 80 GiB on host disk | The deployer provisions a 60 GiB dedicated Btrfs pool (`raft-data`). |
+| **Free disk** | At least 80 GiB on host disk | For the 60 GiB shared Btrfs pool (`raft-data`), images and the host. [Own box disks](./reference/capacity.mdx#own-box-disks) are optional: `--disk-pool SIZE` adds a `raft-disks` pool of SIZE, so a fresh host then needs 80 GiB plus SIZE, and an existing host SIZE plus 20 GiB. |
 
 `raft host add` checks these requirements read-only before it changes a host.
 
-Host CPU and RAM reserves are advisory estimates for `raft limits`, not enforced cgroup locks.
+Host CPU and RAM reserves are advisory estimates for `raft capacity`, not enforced cgroup locks. Raft limits neither how many boxes a host runs nor their size.
 
 <Callout type="warn" title="Dedicated host requirement">
 Do not deploy Raft on hosts with existing Incus storage pools or shared virtualization workloads. Deployment configures dedicated nftables rules, storage pools, and system services.

package/docs/verification.mdx

@@ -18,11 +18,12 @@ Storage accounting covers shared pools rather than per-box quotas. Large backup
 | --- | --- |
 | Create/list/info/delete | Qualified handle, native state, ownership and cleanup |
 | Root terminal/exec | Real PTY, workspace directory, literal arguments and exit code |
-| Resource sizing | Effective CPU affinity and cgroup memory limit |
-| Host capacity | Mixed-size budgets, stopped/frozen boxes, low RAM/disk and four saved slots; live create/stop/resume/destroy changes in CPU/memory allocations |
+| Resource sizing | Effective CPU affinity and cgroup memory limit for free-form sizes, and refusal of CPU or RAM beyond the host |
+| Host capacity | Advisory notice, arbitrary sizes, no box count limit, example shapes, stopped/frozen boxes, low RAM/disk, hosts without own box disks and thin pool metadata warnings; live create/stop/resume/destroy changes in CPU/memory allocations |
+| Own box disks | Guest and Docker writes stop at the disk size without changing pool reservations or taking shared-pool space; too-small disks and requests beyond the unreserved pool space fail before leaving anything behind; new boxes, forks and templates are thin snapshots of their source, and a template copy writes under 1 GiB; each reserves exactly its size; fork, template, resized template, snapshot and backup/recover keep the disk; on a fresh host, own box disks are off until a redeploy with `--disk-pool` enables them |
 | Background jobs | Journal output, nonzero exit status, cancellation of child processes, inspection after cancellation or log rotation, and rejection of unknown job IDs |
 | TTL/extend/resume | Host-enforced stop, manual `gc`, retained files, uninterrupted lifetime extension and 30-day resume |
-| Usage | Real cgroup counters and explicitly shared-pool disk scope |
+| Usage | Real cgroup counters and shared-pool or own-disk scope |
 | File transfer | Binary content, paths containing spaces, stopped-workspace transfers, preservation of the destination after a failed download, and real controller write-error rejection |
 | Docker | Real image build and container execution |
 | Snapshot/restore/fork | File rollback, independent copy, retained network identity and deterministic concurrent-resume rejection under the real host lock |
@@ -33,7 +34,7 @@ Storage accounting covers shared pools rather than per-box quotas. Large backup
 | Development image | Real developer-user tool checks, immutable selection and credential-path archive rejection |
 | Deployment/firewall | Repeat deployment removes stale rules without restarting Incus; failed filtering blocks normal and socket startup; boot timestamps prove filtering precedes Incus |
 | Storage contract | Disposable oversized pool is rejected without automatic resizing |
-| CLI options and errors | Help for all 31 commands and `host add`; default location, TTL and desktop port; all eight sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
+| CLI options and errors | Help for all 34 commands and `host add`; default location, TTL and desktop port; all eight sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
 
 ## Command and option audit (2026-10-06)
 
@@ -57,7 +58,7 @@ The [final runtime validation](https://github.com/Microck/raft/actions/runs/3754
 
 ## New workspace controls
 
-`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, and retention preview/apply. It uses only its own fixtures. Run the archive checks without `--location` to avoid allocating boxes.
+`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, prune preview/apply, host note policies for `new`, `fork`, `note` and `recover`, and stopped-box retention: it sets a 1-hour policy, backdates one stopped box and the policy start, and checks that the next timer run deletes only that box, records the stop time of a box stopped natively and logs to the journal. It sets policies on the host and clears them at the end, and uses only its own fixtures. Every live suite runs the CLI in a private `HOME` holding only `incus.json`, so controller defaults such as `disposable true` never change their boxes. Run the archive, controller-default, policy-message and host worker retention checks without `--location` to avoid allocating boxes; the worker check runs the real worker against a fake `incus` on `PATH`.
 
 The live suite also holds a controller stdin pipe open while running real remote
 readers through both captured and streamed lifecycle transactions. Both must
@@ -87,8 +88,9 @@ The source-race fix also passed a real concurrent writer test that swaps files a
 Test commands require configured hosts and immutable image fingerprints. Suites destroy only the fixtures they create.
 
 Allocation and archive inspection:
-- `python3 deploy/verify-limits.py`: Checks allocation policies without a host. Add `--location lab` to verify live create, stop, resume, and destroy reporting.
+- `python3 deploy/verify-limits.py`: Checks advisory capacity policies without a host. Add `--location lab` to verify live create, stop, resume, and destroy reporting, oversized-request refusal, and own box disks (needs a `raft-disks` pool with 42 GiB unreserved).
 - `python3 deploy/verify-image-tests.py`: Inspects archive structures, including symlinks, hardlinks, FIFOs, and credential detection.
+- `python3 deploy/verify-self-update.py`: Upgrades real npm and uv installs in temporary directories from a local release server and npm registry. Checks SHA256SUMS refusals, install-channel detection, version comparison and the passive notice. Needs npm and uv, but no network or host.
 
 Live host suites (expand the check you need):
 
@@ -137,6 +139,8 @@ python3 deploy/verify-controls.py --source lab --target second-host --directory
 
 </details>
 
+Recovery verification also sets a note policy on the target, proves that a backup without the required note is rejected and its imported box removed, recovers it with a note, then clears the policy.
+
 `verify-tools.py <qualified-box>` executes 31 tool checks as the unprivileged `developer` user inside a running workspace. It compiles and runs code across installed runtimes and package managers without external agent authentication.
 
 ## Extended lifecycle results (2026-10-05)
@@ -152,6 +156,8 @@ Desktop testing validated keyboard input, exact clipboard synchronization, point
 
 **Admission and backup runs**
 
+These runs predate the removal of the saved-box admission cap.
+
 The four-saved-box admission test passed, including rejection of a fifth create, fork, or recovery attempt. Full development-image recovery succeeded with a 5,254,224,965-byte archive, verifying inventories, tool checks, permissions, fresh MACs, and snapshot rollback.
 
 The execution wrapper reported exit 143 after the success message; independent native inventory and archive checks confirmed that all fixtures and temporary archives were removed.
@@ -210,7 +216,7 @@ The [release run](https://github.com/Microck/raft/actions/runs/37469540182) vali
 
 Following a VM reboot, changed kernel boot IDs and active services were verified alongside retained files, snapshots, container states, Docker, and bridge isolation. The host test uses a sparse 100 GiB virtual disk and accessible KVM.
 
-It preserves the production deployer's 80 GiB free-disk check but does not prove physical storage capacity. ARM64 host reboot, host loss, and cross-architecture recovery remain unverified. The VM, SSH keys, and controller configuration were disposable; existing operator hosts were not rebooted or reconfigured.
+It preserves the production deployer's 80 GiB free-disk check, and after enabling own box disks by redeploy checks that the pool is thin, does not pass discards to its file and has that file fully allocated, but does not prove physical storage capacity. ARM64 host reboot, host loss, and cross-architecture recovery remain unverified. The VM, SSH keys, and controller configuration were disposable; existing operator hosts were not rebooted or reconfigured.
 
 </details>
 
@@ -230,7 +236,7 @@ Packaging workflows passed on Python 3.11 and 3.14. Guidelines for visibility ch
 <details>
 <summary>Test evidence and run details</summary>
 
-On 2026-10-06, `raft limits` passed read-only text and JSON inspection and live lifecycle tests on two ARM64 Ubuntu hosts. Tests verified allocation adjustments during create, stop, resume, and destroy cycles.
+On 2026-10-06, `raft limits` (since renamed `raft capacity`, with the admission cap removed) passed read-only text and JSON inspection and live lifecycle tests on two ARM64 Ubuntu hosts. Tests verified allocation adjustments during create, stop, resume, and destroy cycles.
 
 Allocation fixtures validated mixed sizing budgets, frozen containers, low RAM and disk conditions, host reserves, and admission limits. The four-stopped-box admission test verified that creation, forking, and recovery reject a fifth container when slots are exhausted. These are conservative allocation checks, not workload saturation benchmarks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microck/raft",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Self-hosted Linux workspaces powered by Incus, an open-source alternative to boat.dev",
   "license": "MIT",
   "repository": {