Repo docs

Per-repo documentation — each repo's docs/ and README, ingested and associated with the repo. Rendered through the <<<RepoDocs>>> tag.

← code__crank_pi docs · provision/README.md

provision/ — Pi-resident provisioning + control

The Pi-side counterpart to drivers/ (which are the Mac-side image/flash scripts). These run on the booted node (arm64 / Debian trixie), driven by the operator over SSH. python-only, stdlib-only.

- pi_hypervisor.py — turn a fresh trixie Pi into a hypervisor: QEMU + KVM + libvirt (VMs) and Docker + Incus (containers/sandboxes), add the user to the kvm/libvirt/docker/incus-admin groups, enable the daemons, bring up libvirt's default net + a minimal Incus, then verify. Idempotent. Note: on arm64 the literal qemu-kvm package is x86-centric — the correct equivalent is qemu-system-arm + kernel /dev/kvm (what this installs); sbx is macOS-only, so Incus is the Linux-native sandbox layer. Verified on a Pi 5 / 16 GB / trixie: KVM accel available, qemu 10.0.11, libvirt 11.3, docker 26.1.5, incus 6.0.4.

- bridge.py — network-gated checkpoints over the notesdb "bridge". A Pi script calls checkpoint(step, data) at each risky step; it posts the checkpoint to the Pi's notesdbd and blocks for an over-the-wire OK (operator) — or a policy decision (green -> ok, else abort, the unattended circuit-breaker) — safe-aborting on timeout. The checkpoints double as the remote telemetry the controller reads (ssh pi 'notesdb events --kind checkpoint'). See ../PLAN-anonymous-crank-pi.md.

- smoke_bridge.py — end-to-end smoke test of bridge.py against a local notesdbd (plays both the Pi-script and controller roles). Verified: remote-approval round-trip + policy mode.

Deploy note: run the durable notesdbd (and any long-lived service) as a systemd unit / systemd-run — backgrounding a daemon over SSH is unreliable (swallows output, exits 255). See ../PLAN-anonymous-crank-pi.md §error-recovery.