@microck/raft 0.0.0-stage → 0.2.1

package/docs/benchmarks/arm64-candidate-a.json

@@ -0,0 +1,109 @@
+{
+  "hostArchitecture": "aarch64",
+  "hostCpus": 2,
+  "guestCpus": 1,
+  "guestMemory": "2GiB",
+  "sshRoundTripSeconds": 0.372,
+  "scope": "Cached local image; includes controller CLI and SSH; no host reboot or download",
+  "samples": [
+    {
+      "create": {
+        "cliReturnSeconds": 1.0,
+        "commandReadySeconds": 2.197,
+        "dockerReadySeconds": 3.939,
+        "desktopStartSeconds": 2.814
+      },
+      "resume": {
+        "cliReturnSeconds": 1.124,
+        "commandReadySeconds": 2.208,
+        "dockerReadySeconds": 3.792,
+        "desktopStartSeconds": 2.165
+      }
+    },
+    {
+      "create": {
+        "cliReturnSeconds": 1.447,
+        "commandReadySeconds": 2.803,
+        "dockerReadySeconds": 4.58,
+        "desktopStartSeconds": 2.375
+      },
+      "resume": {
+        "cliReturnSeconds": 1.275,
+        "commandReadySeconds": 2.381,
+        "dockerReadySeconds": 4.123,
+        "desktopStartSeconds": 2.449
+      }
+    },
+    {
+      "create": {
+        "cliReturnSeconds": 1.19,
+        "commandReadySeconds": 2.234,
+        "dockerReadySeconds": 4.302,
+        "desktopStartSeconds": 2.607
+      },
+      "resume": {
+        "cliReturnSeconds": 1.284,
+        "commandReadySeconds": 2.376,
+        "dockerReadySeconds": 3.973,
+        "desktopStartSeconds": 2.082
+      }
+    }
+  ],
+  "imageVolumeCachedAtStart": true,
+  "guestArchitecture": "arm64",
+  "imageSizeBytes": 1920185312,
+  "summary": {
+    "create": {
+      "cliReturnSeconds": {
+        "median": 1.19,
+        "min": 1.0,
+        "max": 1.447,
+        "p95": 1.447
+      },
+      "commandReadySeconds": {
+        "median": 2.234,
+        "min": 2.197,
+        "max": 2.803,
+        "p95": 2.803
+      },
+      "dockerReadySeconds": {
+        "median": 4.302,
+        "min": 3.939,
+        "max": 4.58,
+        "p95": 4.58
+      },
+      "desktopStartSeconds": {
+        "median": 2.607,
+        "min": 2.375,
+        "max": 2.814,
+        "p95": 2.814
+      }
+    },
+    "resume": {
+      "cliReturnSeconds": {
+        "median": 1.275,
+        "min": 1.124,
+        "max": 1.284,
+        "p95": 1.284
+      },
+      "commandReadySeconds": {
+        "median": 2.376,
+        "min": 2.208,
+        "max": 2.381,
+        "p95": 2.381
+      },
+      "dockerReadySeconds": {
+        "median": 3.973,
+        "min": 3.792,
+        "max": 4.123,
+        "p95": 4.123
+      },
+      "desktopStartSeconds": {
+        "median": 2.165,
+        "min": 2.082,
+        "max": 2.449,
+        "p95": 2.449
+      }
+    }
+  }
+}

package/docs/benchmarks/arm64-desktop-local.json

@@ -0,0 +1,22 @@
+{
+  "method": "Guest-local systemctl start to HTTP 200 and RFB greeting; excludes SSH overhead",
+  "guestCpus": 1,
+  "guestMemory": "2GiB",
+  "restartsPerImage": 3,
+  "baseline": {
+    "samplesSeconds": [
+      2.275,
+      1.423,
+      1.431
+    ],
+    "medianSeconds": 1.431
+  },
+  "candidate": {
+    "samplesSeconds": [
+      1.042,
+      0.525,
+      0.537
+    ],
+    "medianSeconds": 0.537
+  }
+}

package/docs/benchmarks/arm64-native-ci.json

@@ -0,0 +1,137 @@
+{
+  "hostArchitecture": "aarch64",
+  "hostCpus": 4,
+  "guestCpus": 1,
+  "guestMemory": "2GiB",
+  "sshRoundTripSeconds": 0.187,
+  "scope": "Cached local image; includes controller CLI and SSH; no host reboot or download",
+  "samples": [
+    {
+      "create": {
+        "cliReturnSeconds": 0.425,
+        "commandReadySeconds": 0.866,
+        "dockerReadySeconds": 2.28,
+        "desktopStartSeconds": 1.136
+      },
+      "resume": {
+        "cliReturnSeconds": 0.549,
+        "commandReadySeconds": 0.98,
+        "dockerReadySeconds": 2.335,
+        "desktopStartSeconds": 1.116
+      }
+    },
+    {
+      "create": {
+        "cliReturnSeconds": 0.427,
+        "commandReadySeconds": 0.871,
+        "dockerReadySeconds": 2.324,
+        "desktopStartSeconds": 1.12
+      },
+      "resume": {
+        "cliReturnSeconds": 0.556,
+        "commandReadySeconds": 0.988,
+        "dockerReadySeconds": 2.626,
+        "desktopStartSeconds": 1.119
+      }
+    },
+    {
+      "create": {
+        "cliReturnSeconds": 0.427,
+        "commandReadySeconds": 0.869,
+        "dockerReadySeconds": 1.92,
+        "desktopStartSeconds": 1.115
+      },
+      "resume": {
+        "cliReturnSeconds": 0.524,
+        "commandReadySeconds": 0.95,
+        "dockerReadySeconds": 2.783,
+        "desktopStartSeconds": 1.087
+      }
+    },
+    {
+      "create": {
+        "cliReturnSeconds": 0.4,
+        "commandReadySeconds": 0.825,
+        "dockerReadySeconds": 2.795,
+        "desktopStartSeconds": 1.102
+      },
+      "resume": {
+        "cliReturnSeconds": 0.526,
+        "commandReadySeconds": 0.951,
+        "dockerReadySeconds": 2.817,
+        "desktopStartSeconds": 1.304
+      }
+    },
+    {
+      "create": {
+        "cliReturnSeconds": 0.407,
+        "commandReadySeconds": 0.832,
+        "dockerReadySeconds": 1.993,
+        "desktopStartSeconds": 1.097
+      },
+      "resume": {
+        "cliReturnSeconds": 0.516,
+        "commandReadySeconds": 0.943,
+        "dockerReadySeconds": 2.141,
+        "desktopStartSeconds": 1.101
+      }
+    }
+  ],
+  "imageVolumeCachedAtStart": true,
+  "guestArchitecture": "arm64",
+  "imageSizeBytes": 1921699952,
+  "summary": {
+    "create": {
+      "cliReturnSeconds": {
+        "median": 0.425,
+        "min": 0.4,
+        "max": 0.427,
+        "p95": 0.427
+      },
+      "commandReadySeconds": {
+        "median": 0.866,
+        "min": 0.825,
+        "max": 0.871,
+        "p95": 0.871
+      },
+      "dockerReadySeconds": {
+        "median": 2.28,
+        "min": 1.92,
+        "max": 2.795,
+        "p95": 2.795
+      },
+      "desktopStartSeconds": {
+        "median": 1.115,
+        "min": 1.097,
+        "max": 1.136,
+        "p95": 1.136
+      }
+    },
+    "resume": {
+      "cliReturnSeconds": {
+        "median": 0.526,
+        "min": 0.516,
+        "max": 0.556,
+        "p95": 0.556
+      },
+      "commandReadySeconds": {
+        "median": 0.951,
+        "min": 0.943,
+        "max": 0.988,
+        "p95": 0.988
+      },
+      "dockerReadySeconds": {
+        "median": 2.626,
+        "min": 2.141,
+        "max": 2.817,
+        "p95": 2.817
+      },
+      "desktopStartSeconds": {
+        "median": 1.116,
+        "min": 1.087,
+        "max": 1.304,
+        "p95": 1.304
+      }
+    }
+  }
+}

package/docs/boat-capabilities.md

@@ -0,0 +1,64 @@
+---
+title: Boat feature parity
+---
+
+# Boat capability coverage
+
+Raft is an independent open-source alternative to [boat.dev](https://boat.dev).
+✅ supported · ❌ unavailable through the compared product · ❓ not established by Boat's documentation.
+
+A shared checkmark means both offer the workflow, not identical behavior or isolation.
+
+Tests verify Raft behavior, not hosted Boat infrastructure. See [verification](./verification.mdx) for evidence.
+
+| Capability | Boat | Raft | Raft limits and differences |
+| --- | :---: | :---: | --- |
+| Self-hosted runtime on operator hardware | ❌ | ✅ | Boat is a hosted service. Raft runs Incus on hosts controlled by the operator |
+| Native ARM64 workspaces | ❌ | ✅ | Boat documents all machine sizes as x86_64; Raft also supports native ARM64 |
+| Create/list/inspect/delete | ✅ | ✅ | Qualified handles, explicit locations, native Incus metadata. Single operator; no organization/account API |
+| Stop/resume | ✅ | ✅ | Stops processes, retains disk; resume requires TTL. Shared-kernel containers, not Boat VMs |
+| Running lifetime | ✅ | ✅ | Host-enforced TTL; extend resets deadline without restart. Long locked transactions delay expiry checks |
+| Sizing | ✅ | ✅ | 1/2 CPUs and 1/2/4 GiB choices. Resume/fork support sizing overrides; Boat offers larger sizes |
+| Host capacity recommendations | ❌ | ✅ | Raft reports host CPU/RAM budgets, active allocations, saved slots and disk headroom. Boat limits describe hosted plan credits and concurrency, not operator-host sizing. Raft enforces four saved boxes per host |
+| Hosted credit and start-rate limits | ✅ | ❌ | Boat reports plan credits, concurrency and start rates. Raft has no billing service |
+| Resize on resume/fork | ✅ | ✅ | Optional CPU/RAM overrides, retaining omitted limits |
+| Usage | ✅ | ✅ | Cgroup memory, CPU counters, shared pool space. No billing meter or per-box disk accounting |
+| Root terminal | ✅ | ✅ | PTY over host SSH and native Incus exec. No directly exposed guest SSH endpoint |
+| Synchronous exec | ✅ | ✅ | Literal argv and preserved exit code. Shell syntax requires an explicit shell |
+| Detached exec | ✅ | ✅ | Guest systemd unit, status, logs, cancellation. No process checkpoint or restart after stop |
+| File transfer | ✅ | ✅ | Binary file upload/download. Recursive tree transfer for running boxes; no directory merges |
+| Named snapshots | ✅ | ✅ | Create/list/restore with stopped source, checked inside the lifecycle lock. No running snapshot consistency guarantee |
+| Deploy/delete named snapshots | ✅ | ✅ | `new --from LOCATION:BOX/SNAPSHOT` and `snapshot-delete`; templates stay on their source host |
+| Fork | ✅ | ✅ | Same-host stopped filesystem copy. Copies filesystem secrets; no cross-host fork command |
+| Portable recovery | ❓ | ✅ | Raft exports/imports whole native instances including snapshots. Boat documents snapshot file downloads; importing a portable whole-instance archive is not established. Raft backup storage is manual; no scheduled off-host uploads |
+| Docker | ✅ | ✅ | Guest daemon with real image builds. Container nesting uses host kernel |
+| Native development images | ✅ | ✅ | Boat: Ubuntu x86_64 machines. Raft: published native Debian ARM64/AMD64 images with pinned fingerprints and clean-archive inspection |
+| Development tools | ✅ | ✅ | 31 real developer-user checks. Debian/Chromium, not identical Ubuntu/Chrome versions; VS Code, Ghostty and GitHub CLI are not bundled; version-manager coverage differs |
+| Private forward | ✅ | ✅ | Foreground authenticated SSH tunnel to controller loopback. Guest service must listen on its managed NIC; no reverse forwarding |
+| Public workspace hosting | ✅ | ❌ | Missing. Deferred; requires a defined ingress and access policy |
+| Desktop | ✅ | ✅ | On-demand noVNC, framebuffer, pointer and browser transport checks. See verification for desktop interaction coverage |
+| Browser-only streaming | ✅ | ❌ | Missing. Full desktop only; browser confinement deferred |
+| Network separation | ❓ | ✅ | Raft tests host/private/metadata and IPv4/IPv6 peer restrictions with startup-gated filtering. Boat's equivalent filtering policy is not established; its VM boundary is listed separately |
+| Bounded host storage pool | ❓ | ✅ | Raft configures a shared 60 GiB Btrfs host pool and rejects size drift. Boat does not document an operator-managed host storage pool |
+| Strict per-box disk allocation | ✅ | ❌ | Nested subvolumes prevent claiming strict quotas; no independent Boat-sized disks |
+| VM kernel isolation | ✅ | ❌ | VM deployment not implemented |
+| Nested KVM / Android emulator acceleration | ✅ | ❌ | Boat documents KVM on standard hosts; overflow cloud VMs lack it. Raft has no guest KVM device or VM mode |
+| External guest SSH | ✅ | ❌ | Boat supports a public IP or an SSH endpoint; public IPv4 is not guaranteed. Raft uses host-mediated private access |
+| Named environments and secrets | ✅ | ❌ | Files/configuration can be prepared explicitly. No environment registry or secret-injection service |
+| Organizations | ✅ | ❌ | Boat shares billing and plan limits; resources stay with their creator. Raft is single-operator |
+| Lifecycle webhooks | ✅ | ❌ | Missing. Deferred until an external consumer needs them |
+| Automatic deletion/retention | ✅ | ✅ | Disposable delete-on-stop/expiry; opt-in stopped-box retention cleanup with preview |
+| Dashboard | ✅ | ❌ | Missing. CLI and private desktop cover current workflow |
+| SDK/API keys | ✅ | ❌ | Host SSH authentication. No remote Raft service API |
+| CLI-wide JSON mode | ✅ | ❌ | Boat supports JSON/JSONL for most commands; argument errors may use stderr. Raft provides JSON for list/info/usage/limits and JSONL for prune |
+| Snapshot file browsing/download | ✅ | ❌ | Full native archives only; no Raft snapshot tree or selected-file interface |
+| CLI self-update/completions | ✅ | ❌ | Standard npm or Python package installation/help. No CLI update command or dynamic shell completions |
+| Managed agents | ✅ | ❌ | Not implemented. No prompt/events/steer/interrupt/conversation API |
+
+## Reference check
+
+Checked on 2026-10-07 against Boat's [CLI reference](https://docs.boat.dev/cli-reference), [machine capabilities](https://docs.boat.dev/machines), [SSH/file access](https://docs.boat.dev/ssh-access), [snapshots](https://docs.boat.dev/snapshots), [data retention](https://docs.boat.dev/data-retention), and [billing and limits](https://docs.boat.dev/billing).
+
+The new workspace-control suite passed on ARM64 and AMD64 at runtime commit `a7fef1f5` in [run 37603576786](https://github.com/Microck/raft/actions/runs/37603576786). The baseline native architecture and disposable AMD64 host tests passed in [run 37496577945](https://github.com/Microck/raft/actions/runs/37496577945). This audit compares documented features, not a live differential test against Boat. Managed agent workflows remain out of scope.
+
+Recursive transfers, resume/fork sizing, snapshot templates/deletion and disposable lifecycle are implemented. Directory transfers require a running box; templates stay on the source host. Public hosting, VM isolation, organization sharing, and remote APIs require additional infrastructure. noVNC tests do not establish parity for Boat frame rate, browser confinement or application set.

package/docs/boat-parity-design.md

@@ -0,0 +1,26 @@
+---
+title: Design decisions
+---
+
+# Architecture and references
+
+Raft is an independent open-source alternative to [boat.dev](https://boat.dev). It pairs an operator CLI with open-source infrastructure without redistributing Boat software or credentials.
+
+## Runtime
+
+[Incus](https://github.com/lxc/incus) manages unprivileged system containers, images, snapshots, clones, and file transfers on native ARM64 and AMD64 Ubuntu hosts with Debian 13 guest images. Containers share the host kernel. KVM is not required, and VM deployment is not implemented.
+
+Host SSH authenticates the operator. Incus listens strictly on its local Unix socket without a public management API. Guest systemd manages detached jobs and the on-demand Xvfb, Openbox, and noVNC desktop. A host timer enforces running TTL.
+
+## Image distribution
+
+Build clean images from upstream Debian bases using the provided builder, then pin the resulting 64-hex fingerprint in controller configuration. The native image workflow attaches temporary templates after build and E2E checks pass (see [Boot performance](./boot-performance.mdx)).
+
+Reference projects and comparison surfaces:
+
+- [OpenSandbox](https://github.com/opensandbox-group/OpenSandbox): Self-hosted sandbox patterns and runtime images.
+- [Incus first steps](https://linuxcontainers.org/incus/docs/main/tutorial/first_steps/): Container lifecycle, image servers, and snapshots.
+- [Incus backups](https://linuxcontainers.org/incus/docs/main/howto/instances_backup/): Portable container export format.
+- [Boat CLI reference](https://docs.boat.dev/cli-reference): Parity comparison surface. Raft tests verify Raft behavior, not Boat service conformance.
+
+See [Runtime contract](./contract.md), [Boat feature parity](./boat-capabilities.md), and [Verification](./verification.mdx) for behavior and limits.

package/docs/boot-performance.mdx

@@ -0,0 +1,102 @@
+---
+title: Boot performance
+---
+
+# Native images and boot performance
+
+Raft builds Debian 13 system container images for native ARM64 and AMD64 hosts. The installer, base image, and Node archive match the host CPU architecture. These are separate native images, not emulation layers.
+
+Timings depend on software, image state, hardware, host load, and network transport. These measurements do not compare Raft with hosted Boat.
+
+## Native CI comparison
+
+[Verified native run](https://github.com/Microck/raft/actions/runs/37447415532), 2026-10-06. Five samples per architecture on 4-CPU runners with 1 guest CPU and 2 GiB guest RAM:
+
+| Controller-visible median | ARM64 runner | AMD64 runner |
+| --- | ---: | ---: |
+| Create returns handle | 0.425 s | 0.659 s |
+| Create accepts a command | 0.866 s | 1.375 s |
+| Create has Docker ready | 2.280 s | 3.035 s |
+| Resume accepts a command | 0.951 s | 1.489 s |
+| Resume has Docker ready | 2.626 s | 3.049 s |
+| Desktop starts after create | 1.115 s | 1.592 s |
+| Compressed image | 1.79 GiB | 1.86 GiB |
+
+Raw samples and p95 distributions are recorded in [ARM64 report](benchmarks/arm64-native-ci.json) and [AMD64 report](benchmarks/amd64-native-ci.json). Measurements reflect runner hardware and transport differences, not inherent architecture performance.
+
+Native CI validates builds, workspaces, and clean exports. Imports must match host CPU architecture; cross-architecture recovery is not supported.
+
+## Baseline measured on 2026-10-06
+
+Three-sample medians from two 2-CPU ARM64 hosts with pre-warmed image volumes. Raw samples are preserved in [host A](benchmarks/arm64-baseline-a.json) and [host B](benchmarks/arm64-baseline-b.json).
+
+| Controller-visible operation | ARM64 host A | ARM64 host B |
+| --- | ---: | ---: |
+| Create returns handle | 0.864 s | 2.906 s |
+| Create accepts a command | 1.918 s | 6.936 s |
+| Create has Docker ready | 3.941 s | 10.753 s |
+| Resume returns | 1.056 s | 3.889 s |
+| Resume accepts a command | 1.851 s | 8.213 s |
+| Resume has Docker ready | 3.917 s | 11.653 s |
+| Desktop starts after create | 2.602 s | 7.631 s |
+| Desktop starts after resume | 2.430 s | 7.669 s |
+| Separate host SSH request | 0.397 s | 3.556 s |
+
+Network transport latency dominates the delta between hosts. This is not an ARM64 versus AMD64 benchmark, nor a comparison against hosted Boat.
+
+## Measured changes on the same ARM64 host
+
+- **SSH key generation**: Generates only the advertised Ed25519 host key on first boot, reducing SSH unit startup on host A from 1.898 s to 0.202 s.
+- **Desktop polling**: Waits for an active X server response rather than sleeping for a fixed second.
+- **Image footprint**: Omits coding-agent packages. The candidate ARM64 image is 1,920,185,312 bytes versus 2,626,705,196 bytes for baseline (about 27% smaller).
+- **Volume pre-warming**: Pre-warming the storage volume avoids an initial 82.1 s unpack delay on first use.
+
+Three samples per image on host A give the following comparison. The [candidate report](benchmarks/arm64-candidate-a.json) preserves all samples.
+
+| Measurement | Baseline | Candidate |
+| --- | ---: | ---: |
+| Compressed image | 2.45 GiB | 1.79 GiB |
+| SSH unit, first sample | 1.898 s | 0.202 s |
+| Create has Docker ready, median | 3.941 s | 4.302 s |
+| Resume has Docker ready, median | 3.917 s | 3.973 s |
+| Desktop startup inside guest, median | 1.431 s | 0.537 s |
+
+Warm Docker readiness remains about 4 seconds. These results do not show an overall warm boot speedup; SSH key generation and desktop startup improved.
+
+Desktop benchmarks measure three internal stop/start cycles inside the guest from `systemctl start` to HTTP 200 and RFB greeting, showing about 62% less startup time in [local measurements](benchmarks/arm64-desktop-local.json). Local desktop timing excludes SSH delay; controller-visible timing includes network transport overhead and shows a smaller change.
+
+The candidate passed lifecycle and headed-browser E2E suites on Ubuntu 22 ARM64, and extended suites with all 31 tool checks on Ubuntu 24 ARM64 and AMD64. Fresh-host testing resolved Chromium user-namespace policies and bridge peer filtering.
+
+## Benchmark method
+
+```sh
+python3 deploy/benchmark-boot.py --location lab --samples 5 --desktop > boot.json
+```
+
+The benchmark creates and destroys dedicated test boxes with 1 CPU and 2 GiB RAM. Each sample measures creation, then stops and resumes the same box. It records CLI return, command execution, and Docker API readiness from request initiation.
+
+Desktop timing measures on-demand requests requiring both noVNC HTTP 200 and an RFB protocol greeting. Reports include median, minimum, maximum, nearest-rank p95, SSH round-trip time, image size, and systemd boot critical chain.
+
+Measurements assume the image is pre-downloaded. A first use after import or cache eviction can still unpack Incus's optimized storage volume. Timings are software-dependent, varying with installed packages and services, image state, host hardware, load, and transport overhead.
+
+Small sample sets are exploratory; with three or five samples, nearest-rank p95 is effectively their maximum. They do not measure image downloads, host reboots, process-memory restoration, or remote browser rendering.
+
+## Build and verify
+
+<details>
+<summary>Image build, publication, and artifact details</summary>
+
+Run the image builder on each native host. To preserve an existing image, specify a new alias such as `--alias raft-dev-next`. Building a candidate does not modify the pinned fingerprint in controller configuration.
+
+After publication, the builder creates and deletes a cache-preparation instance to populate Incus's storage volume before reporting readiness. Imported archives or use after cache eviction can still require a slow first unpack.
+
+The [native images workflow](https://github.com/Microck/raft/blob/main/.github/workflows/images.yml) runs on GitHub `ubuntu-24.04` and `ubuntu-24.04-arm` runners. It builds each image, runs extended lifecycle tests and all 31 developer tool checks, measures startup, and exports clean templates with SHA-256 checksums.
+
+Successful CI runs attach seven-day artifacts (`raft-dev-amd64` and `raft-dev-arm64`), which require a GitHub login to download. Small `boot-results-amd64` and `boot-results-arm64` artifacts contain only reports.
+
+Versioned public images are published under [releases](https://github.com/Microck/raft/releases) after recovery and fresh-host validation; public release assets do not expire on the seven-day CI schedule. Each archive must be imported into a host of the matching CPU architecture.
+
+The CI runner uses a sparse Btrfs pool on an ephemeral VM and does not certify the 80 GiB production free-disk preflight. Pinned images retain their contents until you configure a new fingerprint.
+
+</details>
+

package/docs/contract.md

@@ -0,0 +1,93 @@
+---
+title: Runtime contract
+---
+
+# Raft contract
+
+Raft manages persistent unprivileged native-architecture Incus system containers on configured ARM64 or AMD64 Linux hosts. Containers share the host kernel. Images must match host CPU architecture; foreign-architecture emulation and VM workflows are not implemented.
+
+## Image releases
+
+- Versioned releases provide clean ARM64 and AMD64 templates with SHA-256 checksums, package inventories, and build provenance.
+- Publication requires native lifecycle checks, recovery verification, and fresh AMD64 Ubuntu VM provisioning and reboot checks.
+- Disposable AMD64 KVM verification uses a sparse 100 GiB disk and does not certify physical storage capacity or ARM64 host reboot behavior.
+
+## CLI distribution
+
+- 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.
+
+## 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.
+- **Firewall precedence**: Redeployment reapplies firewall rules. Incus startup requires successful firewall application before the daemon starts, including socket activation.
+- **CLI coverage**: The single-operator workflow spans lifecycle, execution, files, snapshots, jobs, tunnels, backup, and capacity inspection; see the [command reference](./reference/cli.md).
+
+## Configuration and lifecycle defaults
+
+| Setting | Behavior |
+| --- | --- |
+| 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 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. |
+| 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
+
+`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.
+
+- **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.
+
+## 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.
+- **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.
+- **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.
+
+## Security and network isolation
+
+- **User namespaces**: Guest root maps to an unprivileged host UID. Container nesting and intercepted syscalls support Docker without mounting the host Docker socket.
+- **Network filtering**: Dedicated bridge `rfbr0` allows DNS, DHCP, and outbound internet. Interface-scoped firewall rules block guest access to host services, cloud metadata, and private address ranges.
+- **Bridge peer isolation**: A native nftables bridge rule blocks all inter-workspace frames on `rfbr0`. IPv6 and link-local peer traffic are blocked.
+- **Private tunnels**: Forwarding listeners bind strictly to controller loopback (`127.0.0.1`). Guest services must listen on `0.0.0.0` or their managed IP, not guest loopback.
+- **Image hygiene**: Development images omit coding agents, personal keys, and host credentials. SSH host keys are generated fresh on first boot. Release inspection rejects root and non-root SSH content, guest host keys, and credential-path links or nonregular entries.
+
+## 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.
+- **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.
+- **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
+
+- **Detached jobs**: Commands run as guest systemd units with journal logging and exit status. Job inspection and cancellation reject unknown IDs in the selected workspace. `raft cancel` stops the unit's control group. Stopping the container terminates jobs.
+- **Desktop service**: On-demand Xvfb, Openbox, and noVNC stack on display `:99` without a login manager. Clipboard exchange is available without login-manager delay. Desktop provides full workspace access, not browser confinement. Closing the tunnel leaves the service running.
+
+## Backup and recovery
+
+- **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.
+- **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

@@ -0,0 +1,86 @@
+---
+title: First working box
+description: Launch, execute commands, connect interactively, and stop your first workspace.
+---
+
+# First working box
+
+Launch and manage a workspace after provisioning your host and pinning the image fingerprint (see [Installation and setup](./operations.mdx)).
+
+## Step 1: Launch a workspace
+
+Create a workspace with `raft new`:
+
+```sh title="CONTROLLER: Create a new workspace"
+box=$(raft new --location lab --ttl 600)
+echo "Created workspace: $box"
+```
+
+The command returns a location-qualified handle formatted as `<location>:<instance-name>` (for example `lab:rf-a1b2c3d4e5f60718`).
+
+Omitting `--location` targets the first location in `~/.config/raft/incus.json`. The `--ttl` flag sets the lifetime in seconds (default: 600).
+
+## Step 2: Verify command execution and Docker daemon
+
+Execute commands inside the container with `raft exec`:
+
+```sh title="CONTROLLER: Verify runtime tools and Docker daemon"
+raft exec "$box" -- node --version
+raft exec "$box" -- docker version
+raft exec "$box" -- docker info
+```
+
+<Callout type="info" title="Daemon readiness check">
+`docker version` and `docker info` verify guest `dockerd` readiness. Running `docker --version` inspects only the client binary without checking the daemon.
+</Callout>
+
+Arguments after `--` pass directly to `execve`. For pipes, redirects, or environment variables, wrap the command in `bash -lc '...'`.
+
+## Step 3: Open an interactive terminal
+
+Open a root terminal session inside the container:
+
+```sh title="CONTROLLER: Open interactive root shell"
+raft ssh "$box"
+```
+
+Type `exit` or press `Ctrl+D` to disconnect.
+
+<Callout type="info" title="User namespace security">
+Commands run as root in `/workspace` inside an unprivileged Linux user namespace. Container root maps to an unprivileged high UID on the host, sharing the host kernel.
+</Callout>
+
+## Step 4: Stop, resume, and destroy
+
+Manage the workspace lifecycle:
+
+```sh title="CONTROLLER: Stop, resume, and destroy workspace"
+# Stop running processes while preserving files and snapshots
+raft stop "$box"
+
+# Resume the stopped workspace with a renewed lifetime
+raft resume "$box" --ttl 600
+
+# Permanently destroy the workspace and release host capacity
+raft destroy "$box"
+```
+
+- **`raft stop`**: Stops running processes and frees active allocations while retaining files and snapshots.
+- **`raft resume`**: Starts a stopped container with a new expiration deadline (`now + TTL`). Does not restore process memory.
+- **`raft destroy`**: Permanently deletes the container, filesystem, and snapshots from the host storage pool.
+
+## Next steps
+
+- [Project setup and templates](./guides/project-setup.mdx): Prepare a project and reuse its dependencies.
+- [Lifetime and persistent services](./guides/long-running-services.mdx): Manage deadlines and restart applications after resume.
+- [Scripting and CI](./guides/scripting-ci.mdx): Parse CLI output and handle failures.
+- [Docker in workspaces](./guides/docker.mdx): Run nested containers and build images.
+- [File transfer](./guides/files.mdx): Upload and download files over SSH.
+- [Background jobs](./guides/background-jobs.mdx): Run detached commands under systemd.
+- [Desktop and private services](./guides/desktop-services.mdx): Forward guest ports and open noVNC desktop.
+- [Snapshots and forks](./guides/snapshots-forks.mdx): Capture disk states and create same-host clones.
+- [Backup and recovery](./guides/backup-recovery.mdx): Export portable archives and restore across hosts.
+- [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.