Mother hive

What this is

The mother node (OSA) coordinates USB operator nodes via MCP over SSH → PostgreSQL. USB nodes send hardware profiles; mother derives capabilities and maintains the hive registry. This page records the decisions behind the implementation — the rationale the code can’t express. For setup instructions, architecture diagrams, and the first-run checklist, see packaging/mother/MOTHER-SETUP.md.

Decisions

Forced-command SSH boundary (not a listening daemon)

USB nodes reach mother by spawning ssh colibri@mother (no remote command). On the mother side, authorized_keys enforces command="/usr/local/bin/colibri-mcp-ssh",restrict,... — the connection cannot run an interactive shell or any command except the wrapper.

The wrapper (colibri-mcp-ssh) further allowlists SSH_ORIGINAL_COMMAND to "" (stdio MCP mode) or "tools" (one-shot discovery). Every other value is rejected.

Why not a listening daemon (HTTP, gRPC, raw TCP): Tailscale encrypts the wire, so the SSH layer adds authentication + confinement without extra infrastructure (no TLS certs, no auth tokens, no open ports). The forced-command boundary is a second lock on top of the SSH key — even a compromised USB that holds the key can only invoke the wrapper, and the wrapper only delegates to colibri-mcp. Defense in depth, deployed as one OpenSSH feature.

→ colibri-mcp-ssh, MOTHER-SETUP.md §Security

Single home for mother infra (colibri, not clawdie-iso)

The mother MCP scripts (node-register-mcp, geodesic-dome-mcp, etc.) were originally copied into both repos. The clawdie-iso copy drifted — its node-register-mcp used E'${...}' string interpolation (SQL-injectable) while the colibri copy used parameterized psql -v :'variable'. The iso copy was removed in clawdie-iso PR #129.

Lesson: a script in two repos will drift. The wiki lint is single-repo and can’t see cross-repo duplicates. The mitigation is discipline: mother infra lives in one place.

→ naming-decisions §Structural (“Single home” row)

`hive_nodes` — not `usb_nodes`

The original table name assumed only USB-booted nodes would register. But a node is any host that joins the hive — USB, NVMe, a jail. Renamed to hive_nodes with a node_type column (colibri #161). The derive_capabilities() trigger is table-agnostic and auto-computes has_gpu, gpu_vendor, can_run_local_llm, has_wifi, max_model on INSERT.

→ mother_schema.sql, naming-decisions (usb_nodes → hive_nodes row)

PostgreSQL peer auth (no passwords)

The colibri OS user connects to mother_hive via peer authentication — the kernel attests the Unix user, no password needed. node-register-mcp runs as this user and inherits the trust. No pgpass files, no env vars, no credential rotation. One moving part: the pg_hba.conf peer rule must precede any catch-all local all all line (first-match).

Why not a password or certificate: passwords rotate and leak; certificates need a CA. Peer auth is built into PostgreSQL on every Unix and works for a localhost connection with zero configuration beyond one pg_hba.conf line.

→ MOTHER-SETUP.md §Setup step 6

Key on seed partition, not in the image

The mother-mcp private key is placed on the CLAWDIESEED partition, not baked into the ISO. The build script has a release guard that refuses to bake it into a release image. The seed importer (clawdie-live-seed) installs it at boot time.

Why: a release ISO is a downloadable artifact. Baking a private key into it would give every downloader access to the mother MCP. The seed partition is a separate physical medium that the operator controls. Even without a seed, the ISO boots and runs — the daemon’s external MCP connection to mother fails gracefully (SSH: “config file not found”), and the node operates standalone.

→ naming-decisions (“Known residue”), clawdie-iso #133

Daemon user, not operator

The colibri daemon runs as the colibri user (/var/db/colibri), not as the operator (clawdie, /home/clawdie). The external MCP SSH connection to mother is spawned by the daemon — so the SSH key, config, and known_hosts must be in the daemon’s home. The seed importer installs SSH material to both homes (operator + daemon).

Why not just put it in clawdie’s home and sudo: the daemon is not the operator. Running as a separate user means the blast radius of a daemon compromise is limited to what the colibri user can do — MCP calls to mother, not operator files or sudo.

→ clawdie-live-seed (clawdie-iso), MOTHER-SETUP.md §Key management