@microck/raft 0.2.1 → 0.3.0

package/README.md

@@ -40,6 +40,14 @@ up hosts or download workspace images.
 | host access | SSH and passwordless sudo |
 | controller | Linux, Python 3.11.8+, SSH and SCP; npm or uv for installation |
 
+then onboard a dedicated Ubuntu host over key-based SSH. `raft host add` checks
+the host, shows its plan, provisions Incus, imports a verified image and runs a
+smoke test:
+
+```sh
+raft host add lab --ssh ubuntu@192.0.2.10
+```
+
 once your host and image are configured, run the commands below. replace `lab`
 with a location from your configuration:
 
@@ -123,7 +131,7 @@ records differences, sources and test coverage.
 | Create/list/inspect/delete | ✅ | ✅ | Single operator |
 | Persistent stop/resume | ✅ | ✅ | Shared host kernel |
 | TTL and lifetime extension | ✅ | ✅ | Persistent boxes retain disk; disposable boxes delete |
-| CPU/memory sizing and usage | ✅ | ✅ | 1 or 2 CPUs, 1, 2 or 4 GiB RAM. Disk usage covers the shared pool |
+| CPU/memory sizing and usage | ✅ | ✅ | 1 or 2 CPUs, 1, 2, 4 or 8 GiB RAM. Disk usage covers the shared pool |
 | Host capacity recommendations | ❌ | ✅ | Raft recommends running capacity and enforces four saved boxes. Boat reports plan limits |
 | Root terminal and command execution | ✅ | ✅ | Host SSH transport |
 | Background jobs, logs and cancellation | ✅ | ✅ | No process checkpoints |

package/deploy/build-image.py

@@ -10,27 +10,17 @@ import time
 import uuid
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from deploy import HOSTS, ROOT, copy, host_architecture, remote  # noqa: E402
+from deploy import ROOT, copy, host_architecture, hosts, remote  # noqa: E402
 
 
-def main():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--location", choices=HOSTS, required=True)
-    parser.add_argument(
-        "--alias", default="raft-dev", help="New image alias; existing aliases are refused"
-    )
-    args = parser.parse_args()
-    if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]*", args.alias):
-        parser.error("alias must use letters, digits, underscores or hyphens")
-    host = HOSTS[args.location]
+def build(host, alias):
+    """Build and publish a native image under a new alias, returning its fingerprint."""
     architecture = host_architecture(host)
     started = time.monotonic()
     prefix = "sudo -n incus --project raft"
     aliases = json.loads(remote(host, prefix + " image list --format json"))
-    if any(a["name"] == args.alias for image in aliases for a in image["aliases"]):
-        raise RuntimeError(
-            args.alias + " exists; choose a fresh alias or review its removal explicitly"
-        )
+    if any(a["name"] == alias for image in aliases for a in image["aliases"]):
+        raise RuntimeError(alias + " exists; choose a fresh alias or review its removal explicitly")
     images = json.loads(
         remote(host, prefix + f" image list images:debian/13/{architecture} --format json")
     )
@@ -66,7 +56,7 @@ def main():
             host,
             prefix
             + " publish raft-builder --alias "
-            + shlex.quote(args.alias)
+            + shlex.quote(alias)
             + " --compression gzip description="
             + shlex.quote(f"Raft Debian 13 {architecture} development workspace"),
         )
@@ -74,11 +64,11 @@ def main():
     # Build failures intentionally retain their named builder for diagnostics.
     # A successful immutable publication no longer needs its writable builder.
     remote(host, prefix + " delete raft-builder")
-    published = json.loads(remote(host, prefix + " image list " + args.alias + " --format json"))
+    published = json.loads(remote(host, prefix + " image list " + alias + " --format json"))
     fingerprint = next(
         image["fingerprint"]
         for image in published
-        if any(alias["name"] == args.alias for alias in image["aliases"])
+        if any(item["name"] == alias for item in image["aliases"])
     )
     # Unpacking a full image can take a minute. Pay it during setup, before new
     # reports a usable box; init prepares the native cache without booting a guest.
@@ -89,6 +79,20 @@ def main():
     print(
         f"Native {architecture} image built in {time.monotonic() - started:.1f} seconds", flush=True
     )
+    return fingerprint
+
+
+def main():
+    configured = hosts()
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--location", choices=configured, required=True)
+    parser.add_argument(
+        "--alias", default="raft-dev", help="New image alias; existing aliases are refused"
+    )
+    args = parser.parse_args()
+    if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]*", args.alias):
+        parser.error("alias must use letters, digits, underscores or hyphens")
+    build(configured[args.location], args.alias)
 
 
 if __name__ == "__main__":

package/deploy/deploy.py

@@ -5,7 +5,9 @@ selects system containers explicitly and never silently substitutes a VM.
 """
 
 import argparse
+import hashlib
 import json
+import re
 import shlex
 from pathlib import Path
 import subprocess
@@ -15,7 +17,49 @@ ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT))
 from raft import configuration  # noqa: E402
 
-HOSTS = {name: entry["ssh"] for name, entry in configuration().items()}
+RELEASES = "https://github.com/Microck/raft/releases/download/"
+# Matches the user agent install-incus.sh sends for its own downloads.
+USER_AGENT = "OpenAI File Downloader, XaiImageApiFetch/1.0"
+INCUS_ARCHITECTURES = {"arm64": "aarch64", "amd64": "x86_64"}
+
+# Shared tail of both image scripts. A unified image's Incus fingerprint is the
+# SHA-256 of its archive, so checking the digest also predicts the fingerprint and
+# lets a rerun reuse an earlier import instead of failing on a duplicate.
+IMPORT_IMAGE = """fingerprint=$(sha256sum "$archive" | cut -d ' ' -f 1)
+test "$fingerprint" = "$expected" || { echo 'Image SHA-256 does not match the expected checksum' >&2; exit 1; }
+if ! sudo -n incus --project raft image info "$fingerprint" >/dev/null 2>&1; then
+  sudo -n incus --project raft image import "$archive" >&2
+fi
+echo "$fingerprint"
+"""
+
+RELEASE_IMAGE = (
+    """set -eu
+work=$(mktemp -d /tmp/raft-image.XXXXXXXX)
+trap 'rm -rf "$work"' EXIT
+archive="$work/raft-dev-$2.tar.gz"
+curl -fsSL -A "$3" -o "$work/SHA256SUMS" "$1/SHA256SUMS"
+curl -fsSL -A "$3" -o "$archive" "$1/raft-dev-$2.tar.gz"
+expected=$(awk -v name="raft-dev-$2.tar.gz" '$2 == name {print $1}' "$work/SHA256SUMS")
+test -n "$expected" || { echo "Release SHA256SUMS lists no raft-dev-$2.tar.gz" >&2; exit 1; }
+"""
+    + IMPORT_IMAGE
+)
+
+ARCHIVE_IMAGE = (
+    """set -eu
+archive=$(mktemp /tmp/raft-image.XXXXXXXX)
+trap 'rm -f "$archive"' EXIT
+cat > "$archive"
+expected="$1"
+"""
+    + IMPORT_IMAGE
+)
+
+
+def hosts():
+    # Read at call time: onboarding imports this module before its location exists.
+    return {name: entry["ssh"] for name, entry in configuration().items()}
 
 
 def remote(host, command):
@@ -40,8 +84,57 @@ def host_architecture(host):
     return architecture
 
 
-def deploy(name):
-    host = HOSTS[name]
+def script(host, body, *arguments, stdin=None):
+    """Run a shell script on the host with positional arguments, returning its stdout."""
+    response = subprocess.run(
+        [
+            "ssh",
+            "-T",
+            "-o",
+            "BatchMode=yes",
+            host,
+            shlex.join(["sh", "-c", body, "raft", *arguments]),
+        ],
+        stdin=stdin,
+        capture_output=True,
+        text=True,
+    )
+    if response.returncode:
+        raise RuntimeError(response.stderr.strip() or "Remote script failed")
+    return response.stdout.strip()
+
+
+def checked_image(host, fingerprint, architecture):
+    """Confirm the imported image exists and matches the host architecture."""
+    if not re.fullmatch(r"[a-f0-9]{64}", fingerprint):
+        raise RuntimeError("Image import returned an invalid fingerprint")
+    images = json.loads(
+        remote(host, f"sudo -n incus --project raft image list {fingerprint} --format json")
+    )
+    image = next((item for item in images if item["fingerprint"] == fingerprint), None)
+    if image is None or image["architecture"] != INCUS_ARCHITECTURES[architecture]:
+        raise RuntimeError(f"Imported image is missing or not a native {architecture} image")
+    return fingerprint
+
+
+def import_release(host, tag, architecture):
+    """Download a release image on the host, verify it against SHA256SUMS and import it."""
+    if not re.fullmatch(r"v\d+\.\d+\.\d+", tag):
+        raise ValueError("Release tags look like v0.3.0")
+    fingerprint = script(host, RELEASE_IMAGE, RELEASES + tag, architecture, USER_AGENT)
+    return checked_image(host, fingerprint, architecture)
+
+
+def import_archive(host, archive, architecture):
+    """Upload a local image archive over SSH stdin, verify its digest and import it."""
+    with Path(archive).open("rb") as source:
+        expected = hashlib.file_digest(source, "sha256").hexdigest()
+        source.seek(0)
+        fingerprint = script(host, ARCHIVE_IMAGE, expected, stdin=source)
+    return checked_image(host, fingerprint, architecture)
+
+
+def deploy(name, host):
     host_architecture(host)
     copy(host, ROOT / "deploy/install-incus.sh", "/tmp/raft-install-incus.sh")
     print(remote(host, "bash /tmp/raft-install-incus.sh </dev/null"), flush=True)
@@ -166,10 +259,11 @@ def deploy(name):
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--location", choices=HOSTS)
+    configured = hosts()
+    parser.add_argument("--location", choices=configured)
     args = parser.parse_args()
-    for name in [args.location] if args.location else HOSTS:
-        deploy(name)
+    for name in [args.location] if args.location else configured:
+        deploy(name, configured[name])
 
 
 if __name__ == "__main__":

package/deploy/verify-features.py

@@ -22,7 +22,15 @@ import time
 
 ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT))
-from raft import incus, inventory, parse_handle, remote, settings, transaction  # noqa: E402
+from raft import (  # noqa: E402
+    host_problems,
+    incus,
+    inventory,
+    parse_handle,
+    remote,
+    settings,
+    transaction,
+)
 import raft_files  # noqa: E402
 from raft_files import pack_directory, publish, unpack_directory  # noqa: E402
 
@@ -157,6 +165,114 @@ def verify_archives():
     )
 
 
+def verify_location_notes():
+    """Edit notes in a private controller home; no host is contacted."""
+    with tempfile.TemporaryDirectory() as home:
+        config = Path(home) / ".config/raft/incus.json"
+        config.parent.mkdir(parents=True)
+        config.write_text(
+            json.dumps({"lab": {"ssh": "lab-host", "image": ""}, "spare": {"ssh": "spare-host"}})
+        )
+
+        def cli(*arguments):
+            return subprocess.run(
+                [sys.executable, str(ROOT / "raft.py"), *arguments],
+                env={**os.environ, "HOME": home},
+                capture_output=True,
+                text=True,
+            )
+
+        assert cli("note", "spare", "  Avoid for Docker builds ").returncode == 0
+        records = [json.loads(line) for line in cli("locations").stdout.splitlines()]
+        assert records == [
+            {"location": "lab", "default": True, "note": ""},
+            {"location": "spare", "default": False, "note": "Avoid for Docker builds"},
+        ], records
+        assert list(json.loads(config.read_text())) == ["lab", "spare"], "Default location moved"
+        assert config.stat().st_mode & 0o777 == 0o600, "Note editing widened permissions"
+        for arguments, error in [
+            (["note", "missing", "x"], "Unknown location"),
+            (["note", "lab", " "], "--clear"),
+        ]:
+            rejected = cli(*arguments)
+            assert rejected.returncode == 1 and error in rejected.stderr, rejected
+        assert cli("note", "lab", "x", "--clear").returncode == 2
+        # Concurrent edits to different locations must all survive.
+        many = {f"host{index}": {"ssh": f"host{index}"} for index in range(8)}
+        saved = config.read_text()
+        config.write_text(json.dumps(many))
+        writers = [
+            subprocess.Popen(
+                [sys.executable, str(ROOT / "raft.py"), "note", location, "busy " + location],
+                env={**os.environ, "HOME": home},
+            )
+            for location in many
+        ]
+        assert all(writer.wait() == 0 for writer in writers)
+        notes = {key: entry.get("note") for key, entry in json.loads(config.read_text()).items()}
+        assert notes == {location: "busy " + location for location in many}, notes
+        config.write_text(saved)
+        assert cli("note", "spare", "--clear").returncode == 0
+        assert "note" not in json.loads(config.read_text())["spare"]
+        assert not list(config.parent.glob(".raft-*")), "Staged configuration left behind"
+        config.write_text(json.dumps({"lab": {"ssh": "lab-host", "note": 1}}))
+        rejected = cli("locations")
+        assert rejected.returncode == 1 and "notes must be strings" in rejected.stderr, rejected
+    print("Location note editing, listing, ordering and permissions passed", flush=True)
+
+
+def verify_host_preflight():
+    """Check onboarding decisions and refusals that need no host."""
+    ready = {
+        "kernel": "Linux",
+        "os": "ubuntu",
+        "version": "24.04",
+        "arch": "arm64",
+        "cpus": "2",
+        # MemTotal of an 8 GiB VM, in KiB.
+        "memory": str(8_131_000),
+        "disk": str(90 * 1024**2),
+        "sudo": "yes",
+        "python3": "yes",
+        "deployed": "no",
+    }
+    assert host_problems(ready) == []
+    # An existing deployment already owns its pool, so free disk no longer gates it.
+    assert host_problems({**ready, "disk": "0", "deployed": "yes"}) == []
+    darwin = host_problems({"kernel": "Darwin", "sudo": "no"})
+    assert len(darwin) == 1 and "macOS" in darwin[0], darwin
+    for change, reason in [
+        ({"os": "debian", "version": "13"}, "Ubuntu 22.04 or 24.04"),
+        ({"version": "20.04"}, "Ubuntu 22.04 or 24.04"),
+        ({"arch": "armhf"}, "ARM64 or AMD64"),
+        ({"sudo": "no"}, "passwordless sudo"),
+        ({"python3": "no"}, "python3"),
+        ({"cpus": "1"}, "2 CPUs"),
+        ({"memory": str(6 * 1024**2)}, "8 GiB RAM"),
+        ({"disk": str(40 * 1024**2)}, "80 GiB"),
+    ]:
+        problems = host_problems({**ready, **change})
+        assert len(problems) == 1 and reason in problems[0], (change, problems)
+    with tempfile.TemporaryDirectory() as home:
+        config = Path(home) / ".config/raft/incus.json"
+        config.parent.mkdir(parents=True)
+        config.write_text(json.dumps({"lab": {"ssh": "lab-host", "image": ""}}))
+        # Each refusal happens before SSH; the unroutable target proves no host is contacted.
+        for arguments, error in [
+            (["lab"], "already configured"),
+            (["bad name"], "Location names"),
+            (["spare", "--image-archive", str(Path(home) / "missing.tar.gz")], "not found"),
+        ]:
+            rejected = subprocess.run(
+                [sys.executable, str(ROOT / "raft.py"), "host", "add", *arguments, "--ssh", "x"],
+                env={**os.environ, "HOME": home},
+                capture_output=True,
+                text=True,
+            )
+            assert rejected.returncode == 1 and error in rejected.stderr, rejected
+    print("Host preflight decisions and pre-SSH onboarding refusals passed", flush=True)
+
+
 def verify_readiness(location, expect_stale=False):
     # Isolate the selected host without losing the controller's verified SSH config.
     with tempfile.TemporaryDirectory(prefix="raft-doctor-test-") as work:
@@ -294,6 +410,25 @@ def verify(location, isolated_worker=False):
     try:
         verify_readiness(location, expect_stale=isolated_worker)
         verify_transaction_stdin(location)
+        # A location note goes to stderr; stdout stays the bare handle for scripts.
+        # A private HOME copy carries the note, leaving the operator config untouched;
+        # OpenSSH reads keys and aliases from the passwd home, not HOME.
+        with tempfile.TemporaryDirectory() as home:
+            noted = Path(home) / ".config/raft/incus.json"
+            noted.parent.mkdir(parents=True)
+            noted.write_text(
+                json.dumps({location: {**settings(location), "note": "feature verifier note"}})
+            )
+            response = live.raft(
+                "new", "--location", location, "--ttl", "600", env={**os.environ, "HOME": home}
+            )
+        handle = response.stdout.strip()
+        fixtures.append(handle)
+        assert response.stdout == handle + "\n", response.stdout
+        assert response.stderr == f"{location} note: feature verifier note\n", response.stderr
+        live.raft("destroy", handle)
+        fixtures.remove(handle)
+        print(f"{location}: noted new kept stdout to the handle and the note on stderr", flush=True)
         box = create("--memory", "1GiB")
         live.wait_running(box)
         _, name = parse_handle(box)
@@ -514,6 +649,8 @@ if __name__ == "__main__":
     parser.add_argument("--location")
     parser.add_argument("--isolated-worker", action="store_true")
     args = parser.parse_args()
+    verify_location_notes()
+    verify_host_preflight()
     verify_archives()
     if args.location:
         verify(args.location, args.isolated_worker)

package/deploy/verify-fresh-host.py

@@ -1,4 +1,4 @@
-"""Provision and reboot a disposable KVM Ubuntu host using the canonical deployer.
+"""Onboard and reboot a disposable KVM Ubuntu host through `raft host add`.
 
 CI-only harness. Writes temporary verified SSH/configuration in its own HOME.
 Uses a sparse 100 GiB virtual disk, not an 80 GiB physical capacity guarantee.
@@ -115,7 +115,6 @@ def verify(archive):
         ssh = home / ".ssh"
         config = home / ".config/raft"
         ssh.mkdir(parents=True, mode=0o700)
-        config.mkdir(parents=True, mode=0o700)
         for key in ["client", "host"]:
             run("ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-f", str(work / key))
         (ssh / "config").write_text(
@@ -124,9 +123,8 @@ def verify(archive):
             f"  UserKnownHostsFile {ssh / 'known_hosts'}\n  StrictHostKeyChecking yes\n"
         )
         (ssh / "known_hosts").write_text("[localhost]:2222 " + (work / "host.pub").read_text())
+        # Onboarding starts from a controller with no Raft configuration at all.
         configuration = config / "incus.json"
-        configuration.write_text(json.dumps({"lab": {"ssh": "raft-fresh", "image": ""}}))
-        configuration.chmod(0o600)
         # A per-harness HOME keeps the operator's controller config untouched.
         env = {**os.environ, "HOME": str(home)}
         cloud = {
@@ -230,33 +228,40 @@ def verify(archive):
                 else:
                     raise RuntimeError("Fresh VM SSH did not become ready")
                 run("ssh", "raft-fresh", "sudo cloud-init status --wait --long", env=env)
-                run(sys.executable, str(ROOT / "deploy/deploy.py"), "--location", "lab", env=env)
-                verify_firewall(env)
-                run("scp", str(archive), "raft-fresh:/tmp/raft-image.tar.gz", env=env)
-                run(
-                    "ssh",
-                    "raft-fresh",
-                    "sudo incus --project raft image import /tmp/raft-image.tar.gz --alias raft-dev",
-                    env=env,
+                onboard = [sys.executable, str(ROOT / "raft.py"), "host", "add", "lab"]
+                onboard += ["--ssh", "raft-fresh"]
+                preview = subprocess.run(
+                    [*onboard, "--dry-run"], env=env, capture_output=True, text=True, check=True
+                )
+                assert "Dry run: nothing was changed" in preview.stdout, preview.stdout
+                assert not config.exists(), "Dry run wrote controller configuration"
+                deployed = subprocess.run(
+                    ["ssh", "raft-fresh", "command -v incus"], env=env, capture_output=True
                 )
-                images = subprocess.check_output(
-                    [
-                        "ssh",
-                        "raft-fresh",
-                        "sudo incus --project raft image list raft-dev --format json",
-                    ],
+                assert deployed.returncode != 0, "Dry run installed Incus"
+                # Without a terminal or --yes, onboarding must refuse before changing anything.
+                refused = subprocess.run(
+                    onboard, env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True
+                )
+                assert refused.returncode == 1 and "--yes" in refused.stderr, refused
+                run(*onboard, "--image-archive", str(archive), "--yes", env=env)
+                with archive.open("rb") as image_archive:
+                    digest = hashlib.file_digest(image_archive, "sha256").hexdigest()
+                saved = json.loads(configuration.read_text())
+                assert saved == {"lab": {"ssh": "raft-fresh", "image": digest}}, saved
+                assert configuration.stat().st_mode & 0o777 == 0o600
+                leftovers = subprocess.check_output(
+                    ["ssh", "raft-fresh", "ls /tmp | grep -c '^raft-image' || true"],
                     env=env,
                     text=True,
                 )
-                fingerprint = next(
-                    item["fingerprint"]
-                    for item in json.loads(images)
-                    if any(a["name"] == "raft-dev" for a in item["aliases"])
-                )
-                configuration.write_text(
-                    json.dumps({"lab": {"ssh": "raft-fresh", "image": fingerprint}})
+                assert leftovers.strip() == "0", "Image staging file left on the host"
+                repeated = subprocess.run(
+                    [*onboard, "--yes"], env=env, capture_output=True, text=True
                 )
-                run("ssh", "raft-fresh", "rm /tmp/raft-image.tar.gz", env=env)
+                assert repeated.returncode == 1 and "already configured" in repeated.stderr
+                print("Guided onboarding: dry run, confirmation, import and smoke test passed")
+                verify_firewall(env)
                 run(
                     sys.executable,
                     str(ROOT / "deploy/verify-live.py"),

package/deploy/verify-limits.py

@@ -32,6 +32,32 @@ def policy_checks():
     assert report["allocated"] == {"cpus": 2, "memoryBytes": 4 * GIB}
     size = next(r for r in report["recommendations"] if r["cpu"] == 2 and r["memoryGiB"] == 4)
     assert (size["totalRunning"], size["additionalRunning"], size["newBoxes"]) == (3, 2, 2)
+    assert len(report["recommendations"]) == 8, "Every CPU/RAM combination needs advice"
+    # An 8 GiB box uses most of a 16 GiB host's 14 GiB budget: one fits on an empty
+    # host, none more while it runs, but a 4 GiB box still does.
+    large_box = {
+        "status": "Running",
+        "expanded_config": {"limits.cpu": "2", "limits.memory": "8GiB"},
+    }
+    eight = capacity(host, [large_box])
+    assert eight["allocated"] == {"cpus": 2, "memoryBytes": 8 * GIB}
+    by_size = {(r["cpu"], r["memoryGiB"]): r for r in eight["recommendations"]}
+    assert (by_size[2, 8]["totalRunning"], by_size[2, 8]["additionalRunning"]) == (1, 0)
+    assert by_size[1, 4]["additionalRunning"] == 1
+    try:
+        capacity(
+            host,
+            [
+                {
+                    "status": "Running",
+                    "expanded_config": {"limits.cpu": "1", "limits.memory": "16GiB"},
+                }
+            ],
+        )
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("Unsupported box size was counted")
     full = capacity(host, [stopped] * 4)
     assert full["savedSlots"] == 0
     assert all(r["newBoxes"] == 0 for r in full["recommendations"])
@@ -58,7 +84,7 @@ def policy_checks():
         )
         assert default["totalRunning"] == expected
     print(
-        "Capacity policy: mixed sizes, stopped/frozen boxes, low RAM/disk, reserves and saved cap passed",
+        "Capacity policy: mixed and 8 GiB sizes, unsupported sizes, stopped/frozen boxes, low RAM/disk, reserves and saved cap passed",
         flush=True,
     )
 

package/deploy/verify-live.py

@@ -19,7 +19,7 @@ ROOT = Path(__file__).resolve().parent.parent
 CLI = [sys.executable, str(ROOT / "raft.py")]
 USER_AGENT = "OpenAI File Downloader, XaiImageApiFetch/1.0"
 sys.path.insert(0, str(ROOT))
-from raft import configuration, incus, remote, settings, transaction  # noqa: E402
+from raft import MEMORY_SIZES, configuration, incus, remote, settings, transaction  # noqa: E402
 
 
 def raft(*arguments, check=True, env=None):
@@ -424,17 +424,18 @@ def verify_configuration():
 
 def verify_arguments():
     # Invoke actual CLI processes: help and argument errors must not access a host.
-    commands = "new list limits doctor gc prune recover info stop resume extend destroy ssh exec upload download snapshot snapshots snapshot-delete restore fork forward desktop logs status cancel backup usage".split()
+    commands = "new locations note host list limits doctor gc prune recover info stop resume extend destroy ssh exec upload download snapshot snapshots snapshot-delete restore fork forward desktop logs status cancel backup usage".split()
     assert raft("--help").returncode == 0
     for command in commands:
         assert raft(command, "--help").returncode == 0
+    assert raft("host", "add", "--help").returncode == 0
     missing = "lab:rf-0000000000000000"
     for command in ["new", "resume", "extend", "fork"]:
         prefix = [command] if command == "new" else [command, missing]
         for lifetime in ["59", "2592001", "invalid"]:
             rejected = raft(*prefix, "--ttl", lifetime, check=False)
             assert rejected.returncode == 2 and "Traceback" not in rejected.stderr
-    for options in [["--cpu", "0"], ["--cpu", "3"], ["--memory", "8GiB"]]:
+    for options in [["--cpu", "0"], ["--cpu", "3"], ["--memory", "16GiB"]]:
         assert raft("new", *options, check=False).returncode == 2
     for arguments in [["exec", missing], ["recover", "missing"], ["forward", missing]]:
         assert raft(*arguments, check=False).returncode == 2
@@ -691,7 +692,7 @@ def verify(location, extended=False, restart_incus=False, reboot_host=False):
         if extended:
             subprocess.run([sys.executable, str(ROOT / "deploy/verify-tools.py"), box], check=True)
             for cpu in [1, 2]:
-                for memory in ["1GiB", "2GiB", "4GiB"]:
+                for memory in MEMORY_SIZES:
                     sized = raft(
                         "new",
                         "--location",
@@ -708,7 +709,7 @@ def verify(location, extended=False, restart_incus=False, reboot_host=False):
                     )
                     assert execute(sized, "nproc") == str(cpu)
                     assert execute(sized, "cat", "/sys/fs/cgroup/memory.max") == str(
-                        int(memory[0]) * 1024**3
+                        int(memory.removesuffix("GiB")) * 1024**3
                     )
                     raft("destroy", sized)
                     fixtures.remove(sized)

package/docs/boat-capabilities.md

@@ -18,7 +18,7 @@ Tests verify Raft behavior, not hosted Boat infrastructure. See [verification](.
 | 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 |
+| Sizing | ✅ | ✅ | 1/2 CPUs and 1/2/4/8 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 |

package/docs/contract.md

@@ -23,6 +23,7 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 - **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.
+- **Guided onboarding**: `raft host add LOCATION --ssh TARGET` probes the target read-only and refuses unsupported hosts, including macOS, before any change. It prints the exact plan and applies it only after an interactive yes or `--yes`; `--dry-run` stops after the plan. It runs the same deployer as `deploy/deploy.py`, imports an image only after its SHA-256 matches (release `SHA256SUMS` or the local archive digest) and its architecture matches the host, then registers the location with the image fingerprint. It finishes with `doctor` and a disposable create/exec/destroy smoke test; if either fails, it removes the new location from the configuration and leaves host changes for a rerun. It uses existing key-based SSH and never collects passwords or changes SSH, other firewall rules or IP configuration. It requires the deployment files from the npm package or a source checkout.
 - **CLI coverage**: The single-operator workflow spans lifecycle, execution, files, snapshots, jobs, tunnels, backup, and capacity inspection; see the [command reference](./reference/cli.md).
 
 ## Configuration and lifecycle defaults
@@ -32,13 +33,15 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 | Host identification | Configuration requires named SSH targets using letters, digits, underscores, or hyphens. |
 | Qualified handles | Every handle includes location and instance name (`<location>:<name>`). |
 | Image pinning | Workspace creation requires the immutable 64-hex image fingerprint, not an updating alias. |
-| Lifecycle defaults | Defaults to first configured location, 1 CPU, 2 GiB RAM, and 600-second lifetime. Supported choices are 1 or 2 CPUs, 1/2/4 GiB RAM, and 60 to 2,592,000 seconds (30 days) TTL. |
+| Lifecycle defaults | Defaults to first configured location, 1 CPU, 2 GiB RAM, and 600-second lifetime. Supported choices are 1 or 2 CPUs, 1/2/4/8 GiB RAM, and 60 to 2,592,000 seconds (30 days) TTL. |
 | Admission limit | Hard ceiling of four saved boxes per host, including stopped boxes. |
 | 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 locations` lists configured locations as JSONL with `location`, `default` and `note` fields without contacting hosts. `raft note LOCATION TEXT` and `raft note LOCATION --clear` edit the optional `note` field in the controller configuration atomically, preserving location order and mode `0600`. Notes are advisory guidance; Raft shows them in `locations`, `limits` and on stderr from `new`, and never enforces them.
+
 `raft 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.

package/docs/guides/scripting-ci.mdx

@@ -23,6 +23,7 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | `info` | One pretty-printed native Incus metadata JSON object |
 | `usage` | One JSON object containing running resource counters |
 | `limits --json` | One JSON object per location (JSONL across multiple hosts) |
+| `locations` | One JSON object per configured location (JSONL) |
 | `prune` | JSONL candidates or deleted records with `box`, `action` |
 | `status` | systemd `ActiveState`, `SubState`, `ExecMainStatus` property lines |
 | `logs` | Guest journal text |