Mother hive

Mother hive

← index

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

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

The wrapper (colibri-mcp-ssh) further allowlists SSH_ORIGINAL_COMMAND to

rejected.

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

while the colibri copy used parameterized psql -v :'variable'. The iso copy

was removed in clawdie-iso PR #129.

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

trigger is table-agnostic and auto-computes has_gpu, gpu_vendor,

→ mother_schema.sql,

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).

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.

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).

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),

See also

• agent-harness — the zot/Colibri split; autospawn
• naming-decisions — usb_nodes → hive_nodes, autospawn flag rename
• quality-gates — the gate that should catch drift at PR time