@microck/raft 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+<p align="center">
+  <img src=".github/assets/raft-logo.png" width="220" alt="raft logo">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">raft</h1>
+
+<p align="center">
+  <a href="https://github.com/Microck/raft/actions/workflows/check.yml"><img src="https://img.shields.io/github/actions/workflow/status/Microck/raft/check.yml?branch=main&style=flat-square&label=ci&color=000000" alt="ci badge"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-mit-000000?style=flat-square" alt="license badge"></a>
+</p>
+
+---
+
+`raft` is an independent, self-hosted open-source alternative to
+[boat.dev](https://boat.dev). it gives you persistent Linux boxes on machines you
+control, with command execution, Docker, file transfer, snapshots, forks and a
+private desktop. Raft is not affiliated with Boat.
+
+[setup](docs/operations.mdx) | [feature parity](docs/boat-capabilities.md) | [verification](docs/verification.mdx) | [agent skill](skills/raft-cli/SKILL.md) | [docs site](https://raft.micr.dev/)
+
+## quickstart
+
+follow the [setup guide](docs/operations.mdx) to install the CLI, configure SSH,
+set up Incus and download or build an image.
+
+install the CLI on Linux with Python 3.11.8+:
+
+```sh
+npm install -g @microck/raft
+raft --version
+```
+
+Python wheels and source archives are also available in
+[releases](https://github.com/Microck/raft/releases). npm installation does not set
+up hosts or download workspace images.
+
+| requirement | minimum |
+| --- | --- |
+| host | dedicated ARM64 or AMD64 Ubuntu host, 2 CPUs, 8 GiB RAM, 80 GiB free disk |
+| host access | SSH and passwordless sudo |
+| controller | Linux, Python 3.11.8+, SSH and SCP; npm or uv for installation |
+
+once your host and image are configured, run the commands below. replace `lab`
+with a location from your configuration:
+
+```sh
+box=$(raft new --location lab --ttl 600)
+raft exec "$box" -- node --version
+raft ssh "$box"
+raft stop "$box"
+```
+
+`raft stop` and expiration keep persistent boxes on disk. `new --disposable`
+deletes a temporary box when it stops or expires. `raft resume` starts
+the box with a new lifetime. `raft destroy` deletes the box and its snapshots.
+disposable creation and retention cleanup require the current host worker;
+redeploy from the current checkout before using them.
+
+each host allows four saved boxes, including stopped ones. `raft limits` reports
+current allocations, free disk space and recommended running counts for each
+size. see [host capacity](docs/reference/capacity-limits.mdx).
+
+## image and workspace control
+
+the image builder starts with Debian 13 and installs language runtimes,
+build tools, Docker, Chromium, FFmpeg and a noVNC desktop. build your own image
+or download an image for your host architecture from
+[versioned releases](https://github.com/Microck/raft/releases). pin its fingerprint
+in your configuration. see
+[image builds and boot measurements](docs/boot-performance.mdx) for checks and timings.
+
+see the task guides for [background jobs](docs/guides/background-jobs.mdx),
+[file transfer](docs/guides/files.mdx),
+[snapshots and forks](docs/guides/snapshots-forks.mdx),
+[private services and desktops](docs/guides/desktop-services.mdx),
+[backup and recovery](docs/guides/backup-recovery.mdx)
+and [Docker](docs/guides/docker.mdx).
+
+See [project setup and templates](docs/guides/project-setup.mdx),
+[persistent services](docs/guides/long-running-services.mdx),
+[scripting and CI](docs/guides/scripting-ci.mdx), and
+[upgrades](docs/guides/upgrades.mdx) for complete operator workflows.
+
+stop the source box before taking a snapshot, restoring one or making a fork.
+stopping a box ends its jobs without saving process memory.
+
+backups include the box's files and credentials. keep them private and import
+only trusted exports. a long backup can delay expiration checks on its host.
+
+## startup performance
+
+median startup times from five runs per architecture on native Ubuntu 24 CI
+hosts. each box had one CPU, 2 GiB RAM and a cached image:
+
+| measurement | ARM64 | AMD64 |
+| --- | ---: | ---: |
+| command ready after create | 0.87 s | 1.38 s |
+| Docker ready after create | 2.28 s | 3.04 s |
+| desktop, after its separate start request | 1.12 s | 1.59 s |
+| compressed development image | 1.79 GiB | 1.86 GiB |
+
+times depend on hardware, installed software and services, storage, image cache
+and SSH latency. the measurements include CLI and SSH overhead. they exclude
+image downloads and host reboots.
+
+the first image unpack can take longer. the runners used different hardware,
+so these results do not show that ARM64 is faster.
+
+both native images passed the lifecycle tests and all 31 development-tool checks. see
+[measurements and methodology](docs/boot-performance.mdx) for raw samples,
+resume timings and the measured image-size and desktop-startup improvements.
+
+## feature parity
+
+✅ supported · ❌ unavailable · ❓ not established in Boat's docs. matching checks
+do not imply identical behavior. the [full comparison](docs/boat-capabilities.md)
+records differences, sources and test coverage.
+
+| Capability | Boat | Raft | Raft limits / differences |
+| --- | :---: | :---: | --- |
+| Self-hosting on operator hardware | ❌ | ✅ | Incus on your hosts |
+| Native ARM64 workspaces | ❌ | ✅ | Boat documents x86_64 machines only |
+| 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 |
+| 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 |
+| File upload/download | ✅ | ✅ | Files and recursive trees; new directory destinations only |
+| Snapshots and same-host forks | ✅ | ✅ | Stopped source, checked under the lifecycle lock |
+| Deploy/delete named snapshots | ✅ | ✅ | Same-host templates and named snapshot deletion |
+| Portable backup/recovery | ❓ | ✅ | Raft native archives; Boat whole-instance archive import is not established |
+| Docker and development tools | ✅ | ✅ | Native ARM64 and AMD64 images. See [image tests](docs/boot-performance.mdx) |
+| Private port forwarding | ✅ | ✅ | Local SSH tunnel |
+| Desktop access | ✅ | ✅ | noVNC; see verification limits |
+| Reverse forwarding | ✅ | ❌ | Not implemented |
+| Public workspace hosting and browser-only streaming | ✅ | ❌ | Not implemented |
+| Resize on resume/fork | ✅ | ✅ | Optional CPU/RAM overrides within supported sizes |
+| CLI-wide JSON mode | ✅ | ❌ | Boat JSON/JSONL; Raft list/info/usage/limits plus prune JSONL |
+| Snapshot file browsing/download | ✅ | ❌ | Whole-box backup only |
+| Strict per-box disk quotas | ✅ | ❌ | Shared 60 GiB Btrfs pool |
+| Separate-kernel VM isolation | ✅ | ❌ | Container runtime |
+| Named environments and managed secrets | ✅ | ❌ | Manual configuration |
+| Organizations and webhooks | ✅ | ❌ | Raft is single-operator; no event API |
+| Dashboard, remote API and SDK | ✅ | ❌ | CLI only |
+| Managed agent conversations | ✅ | ❌ | Not implemented |
+| Automatic deletion and retention | ✅ | ✅ | Disposable deletion; opt-in age-based prune with preview |
+| CLI self-update | ✅ | ❌ | Standard npm or Python package installation |
+
+## verification and development
+
+run `uv sync --locked` to install dependencies and `uv run raft --help` to check
+the CLI. [verification](docs/verification.mdx) lists the real-host test suites.
+they create disposable boxes and remove only their own fixtures.
+
+the optional `--restart-incus` check restarts the host's Incus daemon. run it on
+dedicated test infrastructure.
+
+the tests cover Raft's behavior. they do not compare it against the live Boat
+service. Raft has not had a security audit.
+
+read [the contract](docs/contract.md), [architecture and references](docs/boat-parity-design.md)
+and the optional [agent skill](skills/raft-cli/SKILL.md).
+
+## license
+
+[MIT](LICENSE). third-party tools retain their own licenses.

package/deploy/benchmark-boot.py

@@ -0,0 +1,150 @@
+"""Measure real cached-image creation, resume, Docker and on-demand desktop latency."""
+
+import argparse
+import importlib.util
+import json
+import math
+from pathlib import Path
+import statistics
+import subprocess
+import sys
+import time
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+from raft import configuration, incus  # noqa: E402
+
+spec = importlib.util.spec_from_file_location("verify_live", ROOT / "deploy/verify-live.py")
+live = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(live)
+
+DOCKER_READY = """import subprocess,time
+end=time.monotonic()+60
+while time.monotonic()<end:
+ result=subprocess.run(['docker','info','--format','{{.ServerVersion}}'],capture_output=True,text=True)
+ if result.returncode==0:
+  print(result.stdout.strip());break
+ time.sleep(0.1)
+else: raise SystemExit('Docker did not become ready within 60 seconds')
+"""
+DESKTOP_READY = """import socket,time,urllib.request
+end=time.monotonic()+30
+while time.monotonic()<end:
+ try:
+  request=urllib.request.Request('http://127.0.0.1:6080/vnc.html',headers={'User-Agent':'OpenAI File Downloader, XaiImageApiFetch/1.0'})
+  with urllib.request.urlopen(request,timeout=1) as page: assert page.status==200
+  with socket.create_connection(('127.0.0.1',5900),1) as vnc: assert vnc.recv(12).startswith(b'RFB ')
+  print('desktop-ready');break
+ except (OSError,AssertionError): time.sleep(0.1)
+else: raise SystemExit('Desktop HTTP and VNC did not become ready within 30 seconds')
+"""
+
+
+def readiness(box, started, returned, desktop):
+    deadline = time.monotonic() + 60
+    while time.monotonic() < deadline:
+        probe = live.raft("exec", box, "--", "true", check=False)
+        if probe.returncode == 0:
+            break
+        time.sleep(0.1)
+    else:
+        raise RuntimeError("Guest command execution did not become ready")
+    measured = {
+        "cliReturnSeconds": returned - started,
+        "commandReadySeconds": time.monotonic() - started,
+    }
+    live.execute(box, "python3", "-c", DOCKER_READY)
+    measured["dockerReadySeconds"] = time.monotonic() - started
+    if desktop:
+        desktop_started = time.monotonic()
+        live.execute(box, "systemctl", "start", "raft-desktop")
+        live.execute(box, "python3", "-c", DESKTOP_READY)
+        measured["desktopStartSeconds"] = time.monotonic() - desktop_started
+    return {name: round(value, 3) for name, value in measured.items()}
+
+
+def benchmark(location, samples, desktop):
+    host = configuration()[location]["ssh"]
+    metadata = subprocess.run(
+        ["ssh", "-T", "-o", "BatchMode=yes", host, "uname -m; nproc"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.splitlines()
+    started = time.monotonic()
+    subprocess.run(["ssh", "-T", "-o", "BatchMode=yes", host, "true"], check=True)
+    report = {
+        "hostArchitecture": metadata[0],
+        "hostCpus": int(metadata[1]),
+        "guestCpus": 1,
+        "guestMemory": "2GiB",
+        "sshRoundTripSeconds": round(time.monotonic() - started, 3),
+        "scope": "Cached local image; includes controller CLI and SSH; no host reboot or download",
+        "samples": [],
+    }
+    image = configuration()[location]["image"]
+    volumes = json.loads(
+        incus(location, "storage", "volume", "list", "raft-data", "--format", "json")
+    )
+    report["imageVolumeCachedAtStart"] = any(
+        volume["type"] == "image" and volume["name"] == image for volume in volumes
+    )
+    for index in range(samples):
+        box = None
+        try:
+            started = time.monotonic()
+            box = live.raft("new", "--location", location, "--ttl", "1800").stdout.strip()
+            returned = time.monotonic()
+            created = readiness(box, started, returned, desktop)
+            if index == 0:
+                report["guestArchitecture"] = live.execute(box, "dpkg", "--print-architecture")
+                report["bootBlame"] = live.execute(box, "systemd-analyze", "blame")
+                report["bootCriticalChain"] = live.execute(box, "systemd-analyze", "critical-chain")
+                report["imageSizeBytes"] = json.loads(
+                    incus(
+                        location,
+                        "image",
+                        "list",
+                        configuration()[location]["image"],
+                        "--format",
+                        "json",
+                    )
+                )[0]["size"]
+            live.raft("stop", box)
+            started = time.monotonic()
+            live.raft("resume", box, "--ttl", "1800")
+            returned = time.monotonic()
+            resumed = readiness(box, started, returned, desktop)
+            sample = {"create": created, "resume": resumed}
+            report["samples"].append(sample)
+            print(json.dumps({"sample": index + 1, **sample}), file=sys.stderr, flush=True)
+        finally:
+            if box is not None:
+                live.raft("destroy", box)
+    report["summary"] = {}
+    for action in ("create", "resume"):
+        report["summary"][action] = {}
+        for metric in report["samples"][0][action]:
+            values = sorted(sample[action][metric] for sample in report["samples"])
+            report["summary"][action][metric] = {
+                "median": round(statistics.median(values), 3),
+                "min": values[0],
+                "max": values[-1],
+                "p95": values[math.ceil(0.95 * len(values)) - 1],
+            }
+    return report
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--location", required=True)
+    parser.add_argument("--samples", type=int, default=5)
+    parser.add_argument("--desktop", action="store_true")
+    args = parser.parse_args()
+    if not 1 <= args.samples <= 20:
+        parser.error("samples must be between 1 and 20")
+    print(json.dumps(benchmark(args.location, args.samples, args.desktop), indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/deploy/build-image.py

@@ -0,0 +1,95 @@
+"""Build a pinned Raft development template from a published Incus base image."""
+
+import argparse
+import json
+from pathlib import Path
+import re
+import shlex
+import sys
+import time
+import uuid
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from deploy import HOSTS, ROOT, copy, host_architecture, 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]
+    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"
+        )
+    images = json.loads(
+        remote(host, prefix + f" image list images:debian/13/{architecture} --format json")
+    )
+    bases = [
+        image
+        for image in images
+        if image["type"] == "container"
+        and image["properties"].get("variant") == "default"
+        and image["properties"].get("architecture") == architecture
+    ]
+    if len(bases) != 1:
+        raise RuntimeError("Expected exactly one native Debian 13 default container image")
+    fingerprint = bases[0]["fingerprint"]
+    # Incus --project selects the source project; the destination must be explicit.
+    remote(host, prefix + " image copy images:" + fingerprint + " local: --target-project raft")
+    print("Published base fingerprint: " + fingerprint, flush=True)
+    remote(
+        host,
+        prefix + " launch " + fingerprint + " raft-builder -c limits.cpu=2 -c limits.memory=4GiB",
+    )
+    for source, guest, mode in [
+        ("images/incus/build.sh", "/tmp/raft-build.sh", "755"),
+        ("images/incus/desktop.sh", "/usr/local/bin/raft-desktop", "755"),
+        ("images/incus/raft-desktop.service", "/etc/systemd/system/raft-desktop.service", "644"),
+    ]:
+        staged = "/tmp/" + Path(guest).name
+        copy(host, ROOT / source, staged)
+        remote(host, prefix + f" file push {staged} raft-builder{guest} --mode {mode}")
+    remote(host, prefix + " exec raft-builder -- bash /tmp/raft-build.sh")
+    remote(host, prefix + " stop raft-builder --timeout 30")
+    print(
+        remote(
+            host,
+            prefix
+            + " publish raft-builder --alias "
+            + shlex.quote(args.alias)
+            + " --compression gzip description="
+            + shlex.quote(f"Raft Debian 13 {architecture} development workspace"),
+        )
+    )
+    # 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"))
+    fingerprint = next(
+        image["fingerprint"]
+        for image in published
+        if any(alias["name"] == args.alias for alias 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.
+    cache_probe = "raft-image-cache-" + uuid.uuid4().hex[:8]
+    print("Preparing optimized image cache with " + cache_probe, flush=True)
+    remote(host, prefix + " init " + fingerprint + " " + cache_probe)
+    remote(host, prefix + " delete " + cache_probe)
+    print(
+        f"Native {architecture} image built in {time.monotonic() - started:.1f} seconds", flush=True
+    )
+
+
+if __name__ == "__main__":
+    main()

package/deploy/deploy.py

@@ -0,0 +1,176 @@
+"""Deploy isolated Incus system-container infrastructure on configured hosts.
+
+Run once after reviewing the host setup. Incus VMs need KVM; this deployment
+selects system containers explicitly and never silently substitutes a VM.
+"""
+
+import argparse
+import json
+import shlex
+from pathlib import Path
+import subprocess
+import sys
+
+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()}
+
+
+def remote(host, command):
+    response = subprocess.run(
+        ["ssh", "-T", "-o", "BatchMode=yes", host, command],
+        capture_output=True,
+        text=True,
+    )
+    if response.returncode:
+        raise RuntimeError(response.stderr.strip() or "Remote command failed: " + command)
+    return response.stdout
+
+
+def copy(host, source, destination):
+    subprocess.run(["scp", "-q", str(source), f"{host}:{destination}"], check=True)
+
+
+def host_architecture(host):
+    architecture = remote(host, "dpkg --print-architecture").strip()
+    if architecture not in {"arm64", "amd64"}:
+        raise RuntimeError("Raft hosts must use native ARM64 or AMD64 Debian/Ubuntu packages")
+    return architecture
+
+
+def deploy(name):
+    host = HOSTS[name]
+    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)
+    # Inspect rather than overwriting an unrelated existing project or pool.
+    projects = json.loads(remote(host, "sudo -n incus project list --format json"))
+    project = next((p for p in projects if p["name"] == "raft"), None)
+    pools = json.loads(remote(host, "sudo -n incus storage list --format json"))
+    networks = json.loads(remote(host, "sudo -n incus network list --format json"))
+    pool = next((item for item in pools if item["name"] == "raft-data"), None)
+    network = next((item for item in networks if item["name"] == "rfbr0"), None)
+    if project is not None:
+        if project.get("description") != "Raft managed workspaces":
+            raise RuntimeError("Existing raft project needs ownership verification")
+    else:
+        if pool is not None or network is not None:
+            raise RuntimeError(
+                "Raft resource names already exist without an owned project; review them explicitly"
+            )
+        available = int(
+            remote(
+                host,
+                shlex.join(
+                    [
+                        "python3",
+                        "-c",
+                        "import shutil; print(shutil.disk_usage('/var/lib/incus').free)",
+                    ]
+                ),
+            )
+        )
+        if available < 80 * 1024**3:
+            raise RuntimeError("Fresh deployment needs at least 80 GiB free disk")
+        remote(
+            host,
+            "sudo -n incus project create raft -c features.images=true -c features.profiles=true </dev/null",
+        )
+        remote(
+            host,
+            "sudo -n incus project set raft --property description='Raft managed workspaces'",
+        )
+        remote(host, "sudo -n incus storage create raft-data btrfs size=60GiB")
+        remote(
+            host,
+            "sudo -n incus network create rfbr0 ipv4.address=10.232.0.1/24 ipv4.nat=true ipv6.address=none",
+        )
+        remote(
+            host,
+            "sudo -n incus --project raft profile device add default root disk path=/ pool=raft-data",
+        )
+        remote(
+            host,
+            "sudo -n incus --project raft profile device add default eth0 nic network=rfbr0 name=eth0",
+        )
+        remote(
+            host,
+            "sudo -n incus --project raft profile set default limits.cpu=1 limits.memory=2GiB security.nesting=true security.syscalls.intercept.mknod=true security.syscalls.intercept.setxattr=true",
+        )
+    pools = json.loads(remote(host, "sudo -n incus storage list --format json"))
+    networks = json.loads(remote(host, "sudo -n incus network list --format json"))
+    profiles = json.loads(remote(host, "sudo -n incus --project raft profile list --format json"))
+    pool = next((item for item in pools if item["name"] == "raft-data"), None)
+    network = next((item for item in networks if item["name"] == "rfbr0"), None)
+    profile = next((item for item in profiles if item["name"] == "default"), None)
+    if pool is None or pool["driver"] != "btrfs" or network is None or profile is None:
+        raise RuntimeError(
+            "Incomplete Raft infrastructure; inspect the project, pool, bridge and profile before retrying"
+        )
+    if pool["config"].get("size") != "60GiB":
+        raise RuntimeError(
+            "Raft pool must have configured size=60GiB; inspect raft-data and back up boxes "
+            "before explicit storage recovery. Deployment does not resize existing storage."
+        )
+
+    devices = profile["devices"]
+    if (
+        devices.get("root", {}).get("pool") != "raft-data"
+        or devices.get("eth0", {}).get("network") != "rfbr0"
+        or network["config"].get("ipv4.address") != "10.232.0.1/24"
+        or network["config"].get("ipv4.nat") != "true"
+        or network["config"].get("ipv6.address") != "none"
+        or profile["config"].get("security.nesting") != "true"
+        or profile["config"].get("security.syscalls.intercept.mknod") != "true"
+        or profile["config"].get("security.syscalls.intercept.setxattr") != "true"
+        or profile["config"].get("security.privileged", "false") != "false"
+    ):
+        raise RuntimeError(
+            "Raft profile/network differs from the contract; inspect and recover explicitly"
+        )
+    remote(host, "sudo -n mkdir -p /usr/local/lib/raft")
+    for source, target in [
+        ("deploy/raft-network.sh", "network"),
+        ("deploy/raft-expire.py", "expire-worker"),
+    ]:
+        copy(host, ROOT / source, "/tmp/raft-" + target)
+        remote(host, f"sudo -n install -m 755 /tmp/raft-{target} /usr/local/lib/raft/{target}")
+    wrapper = (
+        '#!/bin/sh\nexec flock /run/lock/raft-incus.lock /usr/local/lib/raft/expire-worker "$@"\n'
+    )
+    local_wrapper = ROOT / ".raft-expire-wrapper"
+    local_wrapper.write_text(wrapper)
+    try:
+        copy(host, local_wrapper, "/tmp/raft-expire-wrapper")
+    finally:
+        local_wrapper.unlink()
+    remote(host, "sudo -n install -m 755 /tmp/raft-expire-wrapper /usr/local/lib/raft/expire")
+    for unit in ["raft-expire.service", "raft-expire.timer", "raft-network.service"]:
+        copy(host, ROOT / "deploy" / unit, "/tmp/" + unit)
+        remote(host, f"sudo -n install -m 644 /tmp/{unit} /etc/systemd/system/{unit}")
+    remote(host, "sudo -n mkdir -p /etc/systemd/system/incus.service.d")
+    copy(host, ROOT / "deploy/incus-network.conf", "/tmp/raft-incus-network.conf")
+    remote(
+        host,
+        "sudo -n install -m 644 /tmp/raft-incus-network.conf /etc/systemd/system/incus.service.d/raft-network.conf",
+    )
+    remote(host, "sudo -n systemctl daemon-reload")
+    remote(host, "sudo -n systemctl enable raft-network.service raft-expire.timer")
+    # Reload active filtering without stopping the Incus daemon that requires it.
+    remote(host, "sudo -n systemctl reload-or-restart raft-network.service")
+    remote(host, "sudo -n systemctl start raft-expire.timer")
+    print(f"{name}: Incus, private bridge and host expiry timer ready", flush=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--location", choices=HOSTS)
+    args = parser.parse_args()
+    for name in [args.location] if args.location else HOSTS:
+        deploy(name)
+
+
+if __name__ == "__main__":
+    main()

package/deploy/incus-network.conf

@@ -0,0 +1,4 @@
+[Unit]
+# Socket activation and normal startup both pass this fail-closed dependency.
+Requires=raft-network.service
+After=raft-network.service

package/deploy/install-incus.sh

@@ -0,0 +1,22 @@
+set -eu
+architecture=$(dpkg --print-architecture)
+case "$architecture" in
+  arm64|amd64) ;;
+  *) echo 'Raft supports native ARM64 and AMD64 hosts' >&2; exit 1 ;;
+esac
+if ! command -v incus >/dev/null; then
+  sudo mkdir -p /etc/apt/keyrings
+  curl -fsSL -A 'OpenAI File Downloader, XaiImageApiFetch/1.0' https://pkgs.zabbly.com/key.asc -o /tmp/raft-zabbly.asc
+  fingerprint=$(gpg --show-keys --with-colons /tmp/raft-zabbly.asc 2>/dev/null | awk -F: '$1=="fpr" {print $10; exit}')
+  test "$fingerprint" = 4EFC590696CB15B87C73A3AD82CC8797C838DCFD
+  sudo install -m 644 /tmp/raft-zabbly.asc /etc/apt/keyrings/raft-zabbly.asc
+  . /etc/os-release
+  printf 'Types: deb\nURIs: https://pkgs.zabbly.com/incus/lts-6.0\nSuites: %s\nComponents: main\nArchitectures: %s\nSigned-By: /etc/apt/keyrings/raft-zabbly.asc\n' "$VERSION_CODENAME" "$architecture" | sudo tee /etc/apt/sources.list.d/raft-incus.sources >/dev/null
+  sudo apt-get update -qq
+  sudo env DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=l apt-get install -y --no-install-recommends incus btrfs-progs
+fi
+if ! command -v nft >/dev/null; then
+  sudo apt-get update -qq
+  sudo env DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=l apt-get install -y --no-install-recommends nftables
+fi
+sudo incus version