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

crank_pi — the Pi node stack: image itself, then virtualize, route, and switch

A Raspberry Pi (or any arm64 node) that builds its own image, provisions itself, and then runs a real network fabric — Open vSwitch + Incus — so it can host VMs/containers and route/switch between them. Not an imaging tool; the node.

The lifecycle

IMAGE ──────────► BOOT + PROVISION ─────► FABRIC UP ─────► FLEET
recipe → flash    cloud-init + Ansible     routed_vm up     many nodes,
                  (installs OVS + Incus)   (OVS `fabric`     iSCSI / netboot
                                            bridge + Incus)   across the fabric

Pieces

- src/routed_vm/ — the fabric and the recipe (the package is named routed_vm = routed VMs). - recipe.py — build-to-spec cloud-init seed (born-instrumented; keys injected by the wallet, never hardcoded). Presets: workstation · imaging · pi · pi-boot · forge. - fabric.py · instance.py · persist.py · cli.py — the OVS fabric bridge (10.1.0.0/24) + Incus instances, systemd-backed, reboot-proven. python3 -m routed_vm up|down|status. - reseed_workstation.py — a thin wrapper over the recipe. - drivers/ — the human-facing Mac-side scripts: build_pi_forge.sh (seed → image), wifi_to_image.sh (wallet passphrase → WPA-PSK → image, verified end-to-end), push_img.sh and confirm.sh + disk_job.sh (the reviewed, guarded flash to the rotating NVMe). - ansible/ — forge-node.yml: provisions the forge peer (anvil ledger + wallet + the canonical truth), then fabric up (OVS + Incus). inventory.ini authenticates with the wallet-derived ~/.ssh/fleet key.

Fabric, not containers-pretending-to-be-a-fabric

OVS is a real programmable switch (L2/L3, flows, VLANs). It was chosen over Docker networking / vendor SDN because it came up faster and actually routes and switches — the node is a fabric member, not just a container host.

Drivers (Mac side)

~/code/{build_pi_forge,wifi_to_image,push_img,confirm,disk_job}.sh are symlinks into drivers/, so the muscle-memory paths still work. RECIPE_SRC=$HOME/code/crank_pi/src.

Provenance