mesh-host/README.md

mesh-host

Tier 0 of the Novox Mesh. The one thing ever installed by hand, and the only thing that changes a machine.

scp mesh-host root@machine:/usr/local/bin/
mesh-host profile

That is the whole installation. One statically linked binary, nothing else present, no runtime to install first (novox/hq ADR 0041).

What it is for

Apply declared state on this machine. Overlay membership, packet filtering, packages, services, containers and filesystems are not six concerns it carries; they are six instances of the one.

It does not decide. Anything needing knowledge of another node is the control plane's, and the host never queries the mesh database. It receives declarations and applies them.

What exists today

It reports, and it has begun to apply. It connects to nothing and listens on nothing.

mesh-host profile      what this machine can be asked to do
mesh-host inventory    what this machine is, and what it holds
mesh-host apply FILE   make this machine match the declaration in FILE
  --json               machine-readable
  --timeout            how long any single probe may take (default 10s)
  --store P            where the applied-state store lives (apply)

$ mesh-host profile
linux/amd64

  yes  container-runtime  29.7.2
  no   firewall           nft exited 1: Operation not permitted (you must be root)
  yes  graphical-session  x11: :1
  yes  overlay            wg0
  yes  package-manager    pacman 7.1.0
  no   privileged         effective uid 1000, not 0
  yes  service-manager    degraded

cannot be asked to: [firewall privileged]

Stage 2 has started: apply consumes a declaration (novox/hq ADR 0043) from a local file and converges this machine, with no mesh present. The first vocabulary is the one that needs no network — directories and files — applied in the stated order, read back, and recorded so what was applied and no longer declared is removed, while what the host did not create never is. The remaining resource types, sealed secrets, the link to the control plane, the pinned substrate bundle and enrolment are designed and not yet built.

A capability is detected, never assumed

The reason this is the first thing built rather than a detail of it.

An installed package is not a capability. A container client on disk with its daemon down looks exactly like a working runtime, and a node assigned work on that basis fails at the moment the work arrives. So every detector runs something that only succeeds if the thing is functioning — the daemon is asked for its version, the package database is queried, the firewall is asked to list a ruleset, which needs the privilege as well as the tool.

Every verdict says how it knows. A capability reported absent with no reason is a fault nobody can act on. The reason is what a person reads when a node will not take work they expected it to take.

Exit codes are not the whole answer. Found by running against a real machine rather than by reasoning: systemctl is-system-running exits non-zero for every state except running — including degraded, which means some units failed and the init is emphatically there. Reading the exit code reported no service manager on a machine whose init it was. That is the same fault in the mirror — installed-but-broken reported present, working-but-imperfect reported absent — and both place work wrongly.

Building

go test ./...                       structure and logic, and the same checks against this machine
CGO_ENABLED=0 go build -ldflags="-s -w" -o mesh-host ./cmd/mesh-host

Roughly 3 MB, static, no dynamic dependencies. Cross-compiles with GOOS/GOARCH; a host is built once per architecture and copied, never built on the machine it runs on.

Mocking the boundary is forbidden (novox/hq ADR 0034). Every detector is exercised against a fake runner for its logic and against this machine for its behaviour. The tests do not assert which capabilities a machine has — that varies, and is the point of detecting — they assert that detection tells the truth about whatever is there.

Where the reasoning lives

Design and decisions are in novox/hq, not here. This repository carries implementation and does not carry decisions.

• 03-DESIGN/01-to-be/05-the-node-host.md — what this is and the order it is built in
• 02-DECISIONS/0037-the-host-applies-it-does-not-decide.md — the one concern
• 02-DECISIONS/0038-a-node-joins-by-linking-first.md — one behaviour, two sources
• 02-DECISIONS/0039-the-link-is-the-security-boundary.md — a node owns no password
• 02-DECISIONS/0041-the-host-depends-on-nothing.md — why this is a static binary, and Go
• 04-ISSUES/007-an-installed-package-is-not-a-capability — why detection works this way