Separate the identity that owns a machine from the seat that performs an action. Then scale compute around hives, with the current lease rules kept visible.
01 / TWO IDENTITY LAYERS
A host role governs lease tenure and machine participation. A seat scopes the authority for one action.
The lease is per hive and fenced through HQ. A viewer stays useful for reading and filing without becoming the write primary.
A session may hold different seats over time, but each bh action is stamped as one seat. The RBAC matrix marks Control, Planning, and Integration operational; its least-privilege reconciliation and some naming changes remain work in progress.
02 / THE DISPATCHER LOOPS
Two loops run at different scopes. Neither is a cross-hive scheduler.
bh host dispatch run --hive H checks the host lease, reaps finished children, then starts kicked-off epics from bd ready order when capacity is available.
bh work loop <epic> checks gates, reclaims stale work, renews the host lease while active, heartbeats claims, harvests seats, claims the next bead safely, and spawns the role binary.
RUNTIME SEAM
work.runtimebh work loopLifecycle state stays in Beads: gates, claims, heartbeats, and merge slots. The per-hive picker deliberately does no cross-hive arbitration or budget reasoning. systemd is the only installed dispatch supervisor today; launchd and container backends are named but unimplemented.
03 / COMPUTE SHAPES
The desktop/cloud/cluster view below follows the new Frame draft. It replaces the old onboarding topology picture.
One local Beadhive host and one or more hive repos. Keep HQ local until backup or a second host matters. The local runtime can plan, dispatch, review, and merge on that machine.
A shared always-on host could be the single executor and lease holder, with separate human/seat identities for the two people. The product docs do not yet define OS-user isolation, shared checkout ownership, or credential boundaries for this setup.
The current Linux host-provision path configures executor/transient/viewer roles; `bh host lease adopt` establishes the primary lease for a selected hive. A provider-specific VPS Bead Frame adapter is planned: pinned NixOS image or slower nixos-anywhere path, enrollment, secret bootstrap, admission, then dispatch.
Attach Frames to one or more hives. The draft allows one active Frame per hive; other Frames are drained or parked for failover. A Frame can serve multiple hives, but there is no shipped cross-hive capacity scheduler or same-hive parallel execution.
Different hives may run on different active Frames. A second Frame attached to the same hive is standby/failover under the proposal, not parallel same-hive capacity.
hq.mode. Each hive keeps its issue history on its own remote; each host keeps a disposable hub it rebuilds with bh sync; HQ alone is authoritative for fleet membership, leases and HQ-origin beads. In git mode the fleet configuration travels as signed commits in an HQ repository every frame clones. In dolt-server mode the same configuration is a committed snapshot in a central SQL store, the live lease and heartbeat tables are deliberately never committed, and a frame needs no HQ checkout at all — but SQL credentials are never trusted on their own: the frame's SSH signature on every envelope is what makes a lease or heartbeat count, exactly as in git mode. A drained frame attached to a leased hive is standby for failover, not a second worker on the same hive.Frame shapes are proposed adapters, not a shipping support matrix. The draft chooses NixOS for VM/cloud VM shapes, OCI images from the same flake for container/pod/sandbox shapes, and Debian + Nix via System Manager with Ansible fallback for host convergence.
04 / FRAME PROVISIONING
Dispatch stays off until the frame is trusted, healthy, and the product eligibility gates exist.
bh host provision then HQ push; report health and signed heartbeat.IDENTITY ATTESTATION
The draft defaults to manual operator admission. It defines operator, cloud instance identity, Kubernetes service-account, and sandbox API attestors. A frame's SSH key is reused for HQ/hive Git access and commit/heartbeat signing; it is a separate concept from test attest keys.
SAFE SHUTDOWN
Stop taking claims, let seats finish to a deadline, push branches and bead state, release leases, and record a clean checkpoint. Live session suspend/resume remains blocked on a gateway contract; a provider memory snapshot does not count as a work checkpoint.
05 / TOOLCHAIN + DELIVERY
Beads and Dolt are part of the runtime chain; a standalone central Dolt service is optional.
$ bh setup check
bd · dolt · gh · git-workspace
flake.nix → pinned versions ↗Current Beadhive install: the managed Nix route pins the driver toolchain, then uv tool install --force 'beadhive[otel]' installs the Python bh CLI; bh setup check verifies the tools it drives. The PyPI/uv route installs bh only and leaves bd, Dolt, GitHub CLI, and git-workspace to the operator.
Beads provides the per-hive bead store and the optional bd serve API. A hive's data lives on one shared local Dolt SQL server per host that bd starts for you; the managed toolchain and the Frame draft pin the same Dolt release, and the pin is deliberately not the newest Dolt. The older per-hive embedded mode is legacy and has its own documented minimum Dolt version for the bd dolt pull hang — "any Dolt 2.x" is too broad. The exact pins live in the repo's flake and INSTALL.md, never here.
bh dolt up starts a separate, optional central Dolt service; it is not required for ordinary local operation. The Frame proposal's future dolt-server HQ mode is another distinct fleet control-plane option.
Implementation gap: Beadhive's current flake is toolchain-only. It has no NixOS module, OCI outputs, or Nix-built bh; the Nix-built bh package is the first hard blocker for a proper NixOS frame.
SOURCE NOTES
The September 29 homelab document is WIP revision 5. Its D1–D16 decisions await review; the frame and homelab rollout work has not been filed or applied. Use it as the updated topology source, not the older onboarding diagrams.