5. Nodes

State

Draft. The node contract v0 is a 16-section draft. It has not had an independent review, and most of it is not built. The claim flow is Built (works end to end on a VM; the TPM side is unverified). The node agent exists only in a first, thin form (see Venue).

What a node is

A node is a machine, or a container, that runs a BenixOS node agent and has been claimed by an owner. The owner is the person whose key was pinned on the node at claim.

A machine is a node when all four hold (contract §1):

  1. It runs the node agent as a supervised service.
  2. It holds a device key and has completed a claim that pinned an owner key.
  3. It is bound to exactly one authority registry, or declares itself standalone.
  4. It meets the host profile for its OS (Hosts and DeviceNix).
Condition Today
Claim Built: benix-claim-agent, end to end on a VM
Node agent Partial: the executor venue-node (chapter 6), without signed placements or grants
Registry binding Draft: Venue today is one daemon with a file registry and bearer tokens
Host profile Draft

Claiming

benix-claim-agent is a public repo that implements device claim: a TPair state machine, a LAN endpoint, and TPM binding. It straddles two layers. The state machine is BenixOS identity. The TPM, first-boot and dinit pieces are DeviceNix. The plan asks for a root-of-trust provider seam so a host without a TPM can still claim; it does not exist yet.

Discovery before claim. An unclaimed box advertises _benixos._tcp over mDNS so a client can find it. benix-mdns-advertiser does this and works. After claim, discovery is Venue's, which also browses _venue._tcp. Machines found by mDNS arrive in Venue pending, and are never nodes until an authoritative manager adopts them. _hearth._tcp is a discovery signal and never a trust signal.

Identity (contract §2)

State: the device key and claim are partly built; the owner's account log is Draft (the log format is proposed, and account_id still equals the Keycloak id).

Registry binding (§4)

At claim the owner binds the node, by signature, to exactly one authority registry and pins that registry's key.

Roles and classes

The owner-signed record assigns roles; a placement's group label is checked against them. Venue uses a role as a placement constraint (where); the agent checks it (whether).

Two node classes:

Class Holds leases Examples
Full yes, hosts services DeviceNix box, Ubuntu server, macOS (reduced)
Client no Phones, tablets, Windows until its transport exists. Hold keys, present grants, show the shell.

What the agent must not hold (§3.3)

The node agent MUST NOT hold: device-root material or the TPM lockoutAuth; unlock keys or session memory of any person; household or operator signing keys; Keycloak admin credentials; upstream service credentials; ssh keys to other nodes; an exec or shell path; policy loaded from the network; or any call to a Lockamy service.

Update and supervision

A conflict the draft has not resolved

The contract says the agent runs as a dedicated non-root user under rootless Podman, and is not in the docker group. The compose bundle that exists today puts the executor in a container with the Docker socket mounted, which is root-equivalent on the host. This is an open decision. See The security model.

Conformance

The first node conformance tests are the M1 and M2 milestone exit tests (Status and roadmap): a path-spelling table, placement signature and fencing checks, and a partition-policy exercise. A node-conformance suite is meant to live in spec-kit, beside the Hearth suite. Neither exists.

Next

6. Venue