@microck/raft 0.0.0-stage → 0.2.1

package/docs/operations.mdx

@@ -0,0 +1,239 @@
+---
+title: Installation and host setup
+description: Install the Raft controller CLI, provision a dedicated host, and acquire the native workspace image.
+---
+
+# Installation and host setup
+
+Set up a dedicated Ubuntu host, install the Raft CLI, provision Incus, acquire a workspace image, and verify readiness.
+
+Review prerequisites in [System requirements](./requirements.mdx) before starting.
+
+<Steps>
+
+<Step>
+
+### Install prerequisites on the workspace host
+
+Connect to your host over SSH, verify its host key fingerprint, and install baseline packages:
+
+```sh title="HOST: Install baseline system packages"
+sudo apt-get update
+sudo apt-get install -y --no-install-recommends \
+  ca-certificates curl gnupg python3 openssh-server iptables btrfs-progs
+```
+
+Verify passwordless `sudo` on the host:
+
+```sh title="HOST: Verify passwordless sudo"
+sudo -n true && echo "Passwordless sudo is functional"
+```
+
+</Step>
+
+<Step>
+
+### Install the CLI and obtain deployment scripts
+
+On your Linux controller with Python 3.11.8+, install the published CLI:
+
+```sh title="CONTROLLER: Install published CLI"
+npm install -g @microck/raft@0.2.0
+raft --version
+```
+
+Installation does not configure hosts or download images. Clone the matching
+release to obtain the deployment scripts and example configuration:
+
+```sh title="CONTROLLER: Obtain deployment scripts"
+git clone --branch v0.2.0 https://github.com/Microck/raft.git raft
+cd raft
+```
+
+Alternatively, install from that checkout using `uv` instead of npm:
+
+```sh title="CONTROLLER: Clone repository and install CLI"
+uv sync --locked
+uv tool install --editable .
+```
+
+For the `uv` installation, add `~/.local/bin` to `PATH` and verify the CLI:
+
+```sh title="CONTROLLER: Verify CLI installation"
+export PATH="$HOME/.local/bin:$PATH"
+raft --help
+```
+
+</Step>
+
+<Step>
+
+### Configure host inventory on the controller
+
+The controller reads host definitions from `~/.config/raft/incus.json`. Initialize the configuration directory and template:
+
+```sh title="CONTROLLER: Initialize configuration file"
+mkdir -p ~/.config/raft
+cp docs/incus.example.json ~/.config/raft/incus.json
+chmod 600 ~/.config/raft/incus.json
+```
+
+Verify interactive SSH to establish known host keys:
+
+```sh title="CONTROLLER: Verify host SSH access"
+ssh user@host-address "echo Host SSH connected successfully"
+ssh -o BatchMode=yes user@host-address "echo Batch SSH functional"
+```
+
+Edit `~/.config/raft/incus.json`. Set the `ssh` target. Leave `image` empty during initial setup:
+
+```json title="CONTROLLER: ~/.config/raft/incus.json"
+{
+  "lab": {
+    "ssh": "user@host-address",
+    "image": ""
+  }
+}
+```
+
+Location names use letters, digits, underscores, or hyphens. The first configured location is the default for `raft new`.
+
+</Step>
+
+<Step>
+
+### Provision the dedicated host
+
+Run the automated host deployer from your controller:
+
+```sh title="CONTROLLER: Provision host infrastructure"
+python3 deploy/deploy.py --location lab
+```
+
+<details>
+<summary>Infrastructure created by the deployer</summary>
+
+The deployer runs over SSH and configures the host:
+1. Installs Incus 6.0 LTS and nftables packages.
+2. Creates the isolated `raft` Incus project.
+3. Creates a 60 GiB Btrfs storage pool (`raft-data`).
+4. Creates private bridge interface `rfbr0` (`10.232.0.1/24`) with NAT.
+5. Configures nftables bridge filters to block inter-workspace traffic and restrict host access.
+6. Installs and enables `raft-network.service` and `raft-expire.timer` units.
+
+</details>
+
+</Step>
+
+<Step>
+
+### Acquire a native workspace image
+
+Workspaces require an unprivileged Debian 13 development image matching the host architecture:
+
+<Tabs items={["Download release image", "Build from source"]}>
+
+<Tab value="Download release image">
+
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.2.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
+
+<Tabs items={["ARM64", "AMD64"]}>
+
+<Tab value="ARM64">
+
+```sh title="HOST (ARM64): Download, verify, and import release image"
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.2.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.2.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.2.0/manifest-arm64.json
+
+sha256sum --ignore-missing -c SHA256SUMS && \
+  sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
+```
+
+</Tab>
+
+<Tab value="AMD64">
+
+```sh title="HOST (AMD64): Download, verify, and import release image"
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.2.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.2.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.2.0/manifest-amd64.json
+
+sha256sum --ignore-missing -c SHA256SUMS && \
+  sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev
+```
+
+</Tab>
+
+</Tabs>
+
+</Tab>
+
+<Tab value="Build from source">
+
+Run the build script from your controller. It pulls Debian 13 to the host, installs development runtimes and Docker, and publishes alias `raft-dev`:
+
+```sh title="CONTROLLER: Build native development image"
+python3 deploy/build-image.py --location lab
+```
+
+<Callout type="warn" title="Do not pin the base image fingerprint">
+During the build, the script downloads an upstream Debian base image and logs its intermediate fingerprint. Do not copy that initial fingerprint; retrieve and pin the final `raft-dev` image fingerprint in the next step.
+</Callout>
+
+</Tab>
+
+</Tabs>
+
+</Step>
+
+<Step>
+
+### Retrieve and pin the image fingerprint
+
+Query the published `raft-dev` image on the host:
+
+```sh title="HOST: Retrieve published image fingerprint"
+sudo incus --project raft image list raft-dev --format json | python3 -c '
+import json, sys
+data = json.load(sys.stdin)
+print(next(img["fingerprint"] for img in data if any(a.get("name") == "raft-dev" for a in img.get("aliases", []))))
+'
+```
+
+Copy the 64-character hex output into `image` in `~/.config/raft/incus.json` on the controller:
+
+```json title="CONTROLLER: ~/.config/raft/incus.json"
+{
+  "lab": {
+    "ssh": "user@host-address",
+    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}
+```
+
+Replace the example string with your actual fingerprint. Raft requires this immutable fingerprint to prevent unexpected image mutations when creating workspaces.
+
+</Step>
+
+<Step>
+
+### Check host status with doctor
+
+Run `raft doctor` on your controller to inspect host readiness:
+
+```sh title="CONTROLLER: Run doctor diagnostics"
+raft doctor
+```
+
+Check that Incus, the network service, and the expiration timer are active. For the full report contents, see [Controller diagnostics](./guides/troubleshooting.mdx#controller-diagnostics).
+
+</Step>
+
+</Steps>
+
+## Next step
+
+Proceed to [First working box](./first-box.mdx) to launch, verify, and manage your first workspace.
+
+For later releases, follow [Upgrades and image changes](./guides/upgrades.mdx).

package/docs/publishing.md

@@ -0,0 +1,48 @@
+---
+title: Publishing
+---
+
+# Publishing a clean source release
+
+Public releases must contain only reusable code, examples, and documentation. Keep controller configuration, SSH keys, instance archives, journals, and private reports outside the repository.
+
+## Release assets and image publishing
+
+Release `main` through the `native images` workflow with a semantic `release_tag`, such as `v0.2.0`. The tag must match both Python and npm versions. Clean upstream Debian bases provide the images.
+
+The workflow builds and inspects Python and npm packages, tests their installed executables outside the checkout, and publishes `@microck/raft` using the repository's `NPM_TOKEN` secret with npm provenance. Only then does it create the GitHub release with the wheel, source archive, npm tarball and verified image assets. Published versions are immutable; after partial publication, fix the failure and use a new patch version.
+
+```sh
+gh workflow run images.yml --ref main -f release_tag=v0.2.0
+```
+
+- **Validation gating**: Publication requires native lifecycle and full-image recovery jobs alongside fresh AMD64 KVM provisioning and reboot verification.
+- **Asset immutability**: The workflow refuses existing tags and never overwrites release assets.
+- **Provenance records**: Release assets include `SHA256SUMS`, architecture manifests, package inventories, and boot reports. Manifests identify the source commit, CI run, and Incus image fingerprint.
+
+## Repository history hygiene
+
+Scan **all Git history**, branches, and tags before changing repository visibility. A clean working tree does not remove sensitive data from commit history.
+
+- **Manual audit**: Secret scanners do not catch every identifier. Inspect old commits for host addresses, usernames, local paths, and private reports.
+- **Fresh repository snapshot**: If commit history contains sensitive data, publish a clean snapshot in a fresh public repository. History rewrites can leave orphaned commits accessible in GitHub cache (see GitHub guidance on [removing sensitive data](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)).
+- **Keep source private**: Do not make an existing private repository public merely because its current working tree is clean.
+
+## Release verification commands
+
+Run security scanning, linting, formatting checks, and package builds before tagging:
+
+```sh
+gitleaks dir --redact --no-banner .
+gitleaks git --redact --no-banner .
+uv sync --locked
+uvx ruff check raft.py deploy/*.py
+uvx ruff format --check raft.py deploy/*.py
+uv build
+```
+
+## Image distribution rules
+
+Do not upload local workspace backups or development exports as release assets. Distributable images must be built from clean upstream bases, inspected for credentials, and accompanied by fingerprints, manifests, and licenses.
+
+Review the package contents and capability table before release. State container isolation accurately without claiming VM isolation or exact Boat compatibility. Raft is an independent alternative to boat.dev and is not affiliated with that service.

package/docs/reference/capacity-limits.mdx

@@ -0,0 +1,92 @@
+---
+title: Capacity limits and planning
+description: Host resource reserves, sizing profiles, advisory calculations, and admission limits.
+---
+
+# Capacity limits and planning
+
+Raft provides capacity inspection and allocation policies designed to keep dedicated hosts stable while running concurrent workspaces.
+
+## Inspecting capacity with `raft limits`
+
+Run `raft limits` to view host resources and workspace allocation calculations:
+
+```sh title="CONTROLLER: View host capacity report"
+raft limits
+
+# Output JSON for programmatic inspection
+raft limits --location lab --json
+```
+
+The output displays host CPU count, total RAM, configured limits, available RAM, disk headroom, and advisory recommendations across all six sizing profiles:
+
+### Illustrative host sizing
+
+Illustrative totals for 1 CPU / 2 GiB boxes on an empty host, using exact usable RAM values:
+
+| Host CPUs | Host RAM | Recommended running | Enforced saved maximum |
+| ---: | ---: | ---: | ---: |
+| 2 | 8 GiB | 1 | 4 |
+| 4 | 8 GiB | 3 | 4 |
+| 4 | 16 GiB | 3 | 4 |
+| 8 | 32 GiB | 4 | 4 |
+
+Operating systems report less usable RAM than advertised hardware size. Near sizing boundaries, `raft limits` may calculate fewer recommended boxes. Available RAM and host processes can further reduce running capacity. These values are point-in-time advisory estimates, not hardware reservations.
+
+### Column definitions and algorithms
+
+| Column | Calculation |
+| --- | --- |
+| Total running | `min(4, floor(CPU budget / box CPU), floor(Memory budget / box memory))` |
+| More running | Bounded by remaining CPU, memory, available RAM, and active slots |
+| New boxes | `min(more running, max(0, 4 - saved boxes))` |
+
+**Total running** assumes an empty host. **More running** accounts for current allocations, `MemAvailable - Memory reserve`, and `4 - active boxes`. Active limits are not subtracted twice.
+
+## Sizing profiles
+
+Select CPU and memory limits when launching with `raft new`:
+
+- `--cpu`: `1` or `2` shared vCPUs managed by Incus (default: `1`).
+- `--memory`: `1GiB`, `2GiB`, or `4GiB` cgroup limit (default: `2GiB`).
+
+Change supported CPU/RAM limits when resuming a stopped box or creating a fork:
+
+```sh
+raft resume "$box" --ttl 1800 --cpu 2 --memory 4GiB
+copy=$(raft fork "$box" --ttl 1800 --memory 2GiB)
+```
+
+Resume requires a stopped box; fork requires a stopped source. Omitted limits
+stay unchanged on resume and inherit the source limits on fork. Live resizing is
+not exposed by the CLI. See [Snapshots and forks](../guides/snapshots-forks.mdx).
+
+## Host resource reserves and active states
+
+Raft calculates advisory host safety margins:
+- **CPU reserve**: 1 CPU core reserved for the host OS.
+- **Memory reserve**: The larger of `2 GiB` or `10%` of host RAM.
+
+These reserves are advisory estimates for planning, not hard cgroup locks.
+
+All non-`Stopped` states (such as `Running` or `Frozen`) count as active allocations. Stopped containers release CPU and RAM allocations while retaining their saved slot and disk storage.
+
+## Enforced admission limits
+
+<Callout type="warn" title="Hard limit: four saved boxes per location">
+Raft enforces a hard limit of four saved boxes per location. Both running and stopped containers occupy storage and count against this limit.
+</Callout>
+
+Exceeding four saved boxes fails with an admission error:
+```text
+Location already holds four boxes
+```
+
+Destroy unused containers with `raft destroy <box>` to free slots. Advisory CPU and memory calculations do not block container creation or resumption.
+
+## Storage capacity
+
+Every Raft host provisions a dedicated 60 GiB Btrfs pool (`raft-data`):
+- **Shared pool**: All containers, snapshots, and Docker layers share this 60 GiB pool.
+- **No strict per-box quotas**: Nested subvolumes prevent strict per-box quota enforcement.
+- **Disk warnings**: `raft limits` warns when free space on host disk or `raft-data` falls below 5 GiB. Warnings are diagnostic and do not block operations. `raft doctor` reports storage usage without emitting 5 GiB warnings.

package/docs/reference/cli.md

@@ -0,0 +1,288 @@
+---
+title: CLI command reference
+description: Complete command-line reference for the Raft controller CLI.
+---
+
+# CLI command reference
+
+Command-line reference for the `raft` controller tool.
+
+Syntax:
+`raft <subcommand> [options] [arguments]`
+
+`raft --help` lists commands, `raft <subcommand> --help` lists its arguments,
+and `raft --version` prints the installed version without loading configuration.
+Output is command-specific; see [Scripting and CI](../guides/scripting-ci.mdx).
+
+Workspaces are referenced by location-qualified handles formatted as `<location>:<instance-name>` (for example `lab:rf-a1b2c3d4e5f60718`).
+
+## Command index
+
+| Task | Commands |
+| --- | --- |
+| Workspace lifecycle | [`new`](#new), [`stop`](#stop), [`resume`](#resume), [`extend`](#extend), [`destroy`](#destroy) |
+| Execution and inspection | [`exec`](#exec), [`ssh`](#ssh), [`info`](#info), [`usage`](#usage) |
+| Background job | [`status`](#status), [`logs`](#logs), [`cancel`](#cancel) |
+| File transfer | [`upload`](#upload), [`download`](#download) |
+| Snapshots and cloning | [`snapshot`](#snapshot), [`snapshots`](#snapshots), [`restore`](#restore), [`snapshot-delete`](#snapshot-delete), [`fork`](#fork) |
+| Port forwarding and desktop | [`forward`](#forward), [`desktop`](#desktop) |
+| Backup and recovery | [`backup`](#backup), [`recover`](#recover) |
+| Host inspection and maintenance | [`limits`](#limits), [`doctor`](#doctor), [`list`](#list), [`gc`](#gc), [`prune`](#prune) |
+
+## Workspace lifecycle commands
+
+### `new`
+
+Create and launch a new workspace container.
+
+`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB}] [--disposable] [--from LOCATION:BOX/SNAPSHOT]`
+
+- `--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}`: Memory limit. Default: `2GiB`.
+
+- `--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.
+
+Returns the qualified workspace handle.
+
+### `stop`
+
+Stop a running workspace.
+
+`raft stop <box>`
+
+Terminates guest processes and stops the container. Persistent boxes retain filesystem contents, packages and snapshots. Disposable boxes are deleted, including their snapshots.
+
+### `resume`
+
+Start a stopped workspace with a renewed lifetime deadline.
+
+`raft resume <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB}]`
+
+- `--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.
+
+### `extend`
+
+Reset the expiration deadline for a running workspace without restarting it.
+
+`raft extend <box> --ttl TTL`
+
+- `--ttl TTL`: Lifetime in seconds from the current host timestamp. Required.
+
+### `destroy`
+
+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.
+
+## Execution and inspection commands
+
+### `exec`
+
+Execute a command inside a workspace.
+
+`raft exec <box> [--detach] [--] <command ...>`
+
+- `--detach`: Run in background as a guest systemd unit. Returns a job ID immediately.
+- `<command ...>`: Command and arguments passed to `execve`. For shell features (pipes, redirects, variables), wrap with `bash -lc '...'`.
+
+Example:
+```sh
+job=$(raft exec "$box" --detach -- make test)
+```
+
+### `ssh`
+
+Open an interactive root terminal session inside the workspace over host SSH and Incus exec.
+
+`raft ssh <box>`
+
+### `info`
+
+Display container metadata from Incus in JSON format, including status, IP addresses, resource limits, and timestamps.
+
+`raft info <box>`
+
+### `usage`
+
+Display active resource consumption for a running workspace: cgroup memory, CPU microseconds, CPU affinity, and shared-pool disk space.
+
+`raft usage <box>`
+
+## Background job commands
+
+`status`, `logs` and `cancel` require a job ID returned by `exec --detach` in the selected running workspace. Unknown jobs return an error.
+
+Cancelled jobs remain inspectable while their guest journal records exist. Rotating old logs does not prevent inspection of a live job.
+
+### `status`
+
+Check the execution state of a detached background job.
+
+`raft status <box> <job>`
+
+Queries `systemctl show` inside the container and outputs `ActiveState`, `SubState`, and `ExecMainStatus`.
+
+### `logs`
+
+Retrieve journal output from a detached background job using `journalctl --no-pager -o cat -u <job>`.
+
+`raft logs <box> <job>`
+
+### `cancel`
+
+Terminate a running detached background job using `systemctl stop <job>`.
+
+`raft cancel <box> <job>`
+
+## File transfer commands
+
+### `upload`
+
+Transfer a local file from the controller to an absolute path inside the workspace.
+
+`raft upload <box> <source> <destination> [--recursive]`
+
+- `<source>`: Path to local file on controller.
+- `<destination>`: Target absolute path inside container.
+
+### `download`
+
+Transfer a file from an absolute path inside the workspace to the local controller.
+
+`raft download <box> <source> <destination> [--recursive]`
+
+- `<source>`: Absolute path to file inside container.
+- `<destination>`: Local file destination path on controller.
+
+`--recursive` transfers a directory tree into a new destination directory. It requires a running workspace and Python 3.11.8+ in the guest. Parent directories must exist. Existing destinations are rejected, including empty directories and symlinks. Internal relative links, hardlinks, executable files and empty directories are supported; escaping links and special files are rejected. Archives use temporary controller disk space. Single-file transfers still work on stopped boxes.
+
+## Snapshots and cloning commands
+
+### `snapshot`
+
+Create a named point-in-time snapshot of a stopped workspace. Names use alphanumeric characters, underscores, or hyphens up to 64 characters.
+
+`raft snapshot <box> <name>`
+
+### `snapshots`
+
+List existing snapshots and creation timestamps for a workspace.
+
+`raft snapshots <box>`
+
+### `snapshot-delete`
+
+Delete one named snapshot without deleting the workspace. The box can be running.
+
+`raft snapshot-delete <box> <name>`
+
+### `restore`
+
+Roll back a stopped workspace filesystem to a named snapshot using `--diskonly`, preserving container configuration and MAC address.
+
+`raft restore <box> <name>`
+
+### `fork`
+
+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}] [--disposable]`
+
+- `--ttl TTL`: Lifetime in seconds for the clone. Required.
+
+Omitted CPU/RAM values inherit the source limits. The clone is persistent unless `--disposable` is supplied, regardless of the source policy.
+
+Returns the qualified handle of the clone.
+
+## Port forwarding and desktop commands
+
+### `forward`
+
+Open a private SSH tunnel between a guest port and controller loopback (`127.0.0.1`).
+
+`raft forward <box> --remote REMOTE --local LOCAL`
+
+- `--remote REMOTE`: Port number inside the workspace (bound to `0.0.0.0` or container IP).
+- `--local LOCAL`: Port number on controller loopback (`127.0.0.1`).
+
+Runs in foreground; press `Ctrl+C` to close.
+
+### `desktop`
+
+Start `raft-desktop.service` inside the container and open a private tunnel for noVNC.
+
+`raft desktop <box> [--local LOCAL]`
+
+- `--local LOCAL`: Controller port to bind (default: `6080`). Access at `http://127.0.0.1:<LOCAL>/vnc.html`. Press `Ctrl+C` to close.
+
+## Backup and recovery commands
+
+### `backup`
+
+Export a stopped workspace and its snapshots to a compressed archive on the controller.
+
+`raft backup <box> <destination>`
+
+- `<destination>`: Output archive path (e.g. `./workspace.tar.gz`). Must not exist. Created with mode `0600`.
+
+### `recover`
+
+Import a portable backup archive onto a host as a fresh stopped workspace.
+
+`raft recover <source> --location LOCATION`
+
+- `<source>`: Path to archive file on controller.
+- `--location LOCATION`: Target host location. Required.
+
+Returns the qualified handle of the imported stopped workspace.
+
+## Host inspection and maintenance commands
+
+### `limits`
+
+Inspect host resource capacity, active allocations, and recommended workspace limits.
+
+`raft limits [--location LOCATION] [--json]`
+
+- `--location LOCATION`: Filter report to a specific host.
+- `--json`: Output report as JSON.
+
+### `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.
+
+`raft doctor`
+
+### `list`
+
+List existing workspace containers across configured hosts.
+
+`raft list [--location LOCATION]`
+
+Prints one JSON object per box (JSONL), with `box`, `state`, and `stopAt` fields.
+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.
+
+`raft gc [--location LOCATION]`
+
+### `prune`
+
+Preview deletion of persistent stopped boxes older than the selected number of days.
+
+`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.
+
+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.