@microck/raft 0.2.1 → 0.3.0

package/docs/operations.mdx

@@ -9,6 +9,30 @@ Set up a dedicated Ubuntu host, install the Raft CLI, provision Incus, acquire a
 
 Review prerequisites in [System requirements](./requirements.mdx) before starting.
 
+## Guided onboarding
+
+Install the CLI from npm on your Linux controller, confirm key-based SSH to the
+host, then let `raft host add` do the remaining steps:
+
+```sh title="CONTROLLER: Onboard a host"
+npm install -g @microck/raft@0.3.0
+ssh ubuntu@192.0.2.10 true
+raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
+raft host add lab --ssh ubuntu@192.0.2.10
+```
+
+The dry run checks the host without changing it and prints the plan. The second
+command shows the same plan, asks for confirmation, provisions Incus, imports the
+checksum-verified release image, adds `lab` to `~/.config/raft/incus.json`, and
+finishes with `raft doctor` and a disposable smoke test. Unsupported hosts,
+including macOS, are rejected before any change; run an Ubuntu VM and onboard
+that instead. See [`host add`](./reference/cli.md#host-add) for image options.
+
+## Manual setup
+
+The steps below are what `raft host add` automates. Follow them to inspect or
+customize each stage.
+
 <Steps>
 
 <Step>
@@ -38,7 +62,7 @@ sudo -n true && echo "Passwordless sudo is functional"
 On your Linux controller with Python 3.11.8+, install the published CLI:
 
 ```sh title="CONTROLLER: Install published CLI"
-npm install -g @microck/raft@0.2.0
+npm install -g @microck/raft@0.3.0
 raft --version
 ```
 
@@ -46,7 +70,7 @@ Installation does not configure hosts or download images. Clone the matching
 release to obtain the deployment scripts and example configuration:
 
 ```sh title="CONTROLLER: Obtain deployment scripts"
-git clone --branch v0.2.0 https://github.com/Microck/raft.git raft
+git clone --branch v0.3.0 https://github.com/Microck/raft.git raft
 cd raft
 ```
 
@@ -135,16 +159,16 @@ Workspaces require an unprivileged Debian 13 development image matching the host
 
 <Tab value="Download release image">
 
-Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.2.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.3.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
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/manifest-arm64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
@@ -155,9 +179,9 @@ sha256sum --ignore-missing -c SHA256SUMS && \
 <Tab value="AMD64">
 
 ```sh title="HOST (AMD64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.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
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/manifest-amd64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev

package/docs/reference/capacity-limits.mdx

@@ -18,7 +18,7 @@ raft limits
 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:
+The output displays host CPU count, total RAM, configured limits, available RAM, disk headroom, and advisory recommendations across all eight sizing profiles:
 
 ### Illustrative host sizing
 
@@ -48,7 +48,7 @@ Operating systems report less usable RAM than advertised hardware size. Near siz
 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`).
+- `--memory`: `1GiB`, `2GiB`, `4GiB`, or `8GiB` cgroup limit (default: `2GiB`). An 8 GiB box needs at least 10 GiB of usable host RAM before `raft limits` recommends running one; like other recommendations, this is advisory and not enforced.
 
 Change supported CPU/RAM limits when resuming a stopped box or creating a fork:
 

package/docs/reference/cli.md

@@ -27,6 +27,7 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 | 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) |
+| Locations | [`host add`](#host-add), [`locations`](#locations), [`note`](#note) |
 | Host inspection and maintenance | [`limits`](#limits), [`doctor`](#doctor), [`list`](#list), [`gc`](#gc), [`prune`](#prune) |
 
 ## Workspace lifecycle commands
@@ -35,17 +36,18 @@ 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}] [--disposable] [--from LOCATION:BOX/SNAPSHOT]`
+`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--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`.
+- `--memory {1GiB,2GiB,4GiB,8GiB}`: 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.
+Returns the qualified workspace handle. If the location has a note, `new` prints
+it to stderr; stdout still contains only the handle.
 
 ### `stop`
 
@@ -59,7 +61,7 @@ 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}]`
+`raft resume <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}]`
 
 - `--ttl TTL`: Lifetime in seconds from resumption (`60` to `2592000`). Required.
 
@@ -194,7 +196,7 @@ 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}] [--disposable]`
+`raft fork <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable]`
 
 - `--ttl TTL`: Lifetime in seconds for the clone. Required.
 
@@ -244,6 +246,60 @@ Import a portable backup archive onto a host as a fresh stopped workspace.
 
 Returns the qualified handle of the imported stopped workspace.
 
+## Location commands
+
+### `host add`
+
+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]`
+
+- `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.
+- `--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
+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
+checks fail, it removes the location again; host changes remain and a rerun
+reuses them.
+
+```sh title="CONTROLLER: Onboard a host"
+raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
+raft host add lab --ssh ubuntu@192.0.2.10
+```
+
+The deployment files ship in the npm package and source checkouts. The Python
+wheel contains only the CLI; use npm or a checkout to onboard hosts.
+
+### `locations`
+
+List configured locations without contacting hosts.
+
+`raft locations`
+
+Prints one JSON object per location (JSONL) in configuration order, with
+`location`, `default` and `note` fields. `default` is true for the location that
+`new` uses without `--location`. `note` is empty when none is set.
+
+### `note`
+
+Set or clear operator guidance for a location in `~/.config/raft/incus.json`.
+
+`raft note LOCATION TEXT`
+`raft note LOCATION --clear`
+
+Notes are advisory. Use them to record which host is preferred or what a host
+should not run. Raft shows notes in `locations`, `limits` and `new` but does not
+enforce them. Empty notes are rejected; use `--clear` to remove one.
+
 ## Host inspection and maintenance commands
 
 ### `limits`
@@ -255,6 +311,8 @@ Inspect host resource capacity, active allocations, and recommended workspace li
 - `--location LOCATION`: Filter report to a specific host.
 - `--json`: Output report as JSON.
 
+Each report includes the location's `note`, if any.
+
 ### `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.

package/docs/reference/configuration.mdx

@@ -27,7 +27,8 @@ The configuration file maps location names to host definition objects:
 {
   "lab": {
     "ssh": "ubuntu@192.0.2.10",
-    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "note": "Preferred for builds"
   },
   "remote-builder": {
     "ssh": "builder.example.com",
@@ -47,6 +48,19 @@ The configuration file maps location names to host definition objects:
 | :--- | :--- | :--- | :--- |
 | `ssh` | `string` | Yes | Non-empty SSH connection string (IP, `user@host`, or SSH host alias from `~/.ssh/config`). |
 | `image` | `string` | For `raft new` only | Full 64-character hexadecimal SHA-256 fingerprint (`^[a-f0-9]{64}$`). An empty string `""` is allowed during initial host provisioning. |
+| `note` | `string` | No | Operator guidance for choosing this location, such as `Preferred for builds` or `Do not use for Docker`. Raft shows notes but never enforces them. |
+
+Set or clear notes with `raft note` instead of editing the file by hand:
+
+```sh title="CONTROLLER: Record location guidance"
+raft note lab "Preferred for builds"
+raft note spare "Do not use for Docker builds"
+raft locations
+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.
 
 <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.

package/docs/releases/0.3.0.md

@@ -0,0 +1,15 @@
+---
+title: Raft 0.3.0
+---
+
+# Raft 0.3.0
+
+- `raft host add LOCATION --ssh TARGET` onboards a host from the CLI. It checks the host read-only first and rejects unsupported targets such as macOS, shows the exact plan, and asks before changing anything (`--dry-run` previews, `--yes` skips the prompt). It provisions Incus, imports a checksum-verified release image (or `--image-archive` / `--build`), pins the fingerprint, and finishes with `doctor` and a disposable smoke test. A failed final check removes the new location again.
+- Boxes can use 8 GiB RAM: `new`, `resume` and `fork` accept `--memory 8GiB`, and `raft limits` reports recommendations for it. An 8 GiB box needs at least 10 GiB of usable host RAM before `limits` recommends running one.
+- Locations accept an optional `note` for operator guidance, such as which host is preferred or what a host should not run. `raft note LOCATION TEXT` sets it and `raft note LOCATION --clear` removes it.
+- `raft locations` lists configured locations as JSONL with their default status and note, without contacting hosts.
+- `raft limits` includes each location's note, and `raft new` prints the target location's note to stderr. Notes are advisory and never block allocation.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.3.0`, or install the attached Python wheel. Notes live in the controller configuration; host workers are unchanged and need no redeployment. Host onboarding needs the npm package or a source checkout because the Python wheel does not ship the deployment files.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/requirements.mdx

@@ -19,6 +19,8 @@ Each workspace host must be a dedicated physical machine or virtual instance:
 | **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`). |
 
+`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.
 
 <Callout type="warn" title="Dedicated host requirement">

package/docs/verification.mdx

@@ -33,7 +33,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 28 commands; default location, TTL and desktop port; all six 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 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 |
 
 ## Command and option audit (2026-10-06)
 

package/package.json

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