---
name: client-enrollment
risk_class: config_mutation
inputs: [hostname, kind, role]
verification: "homelab doctor (on the new client)"
docs_update_checklist: [hosts_narrative_page_if_lxc_or_vm]
---

# Client enrollment

Goal: bring a new host (workstation, LXC, VM) into the mesh, inventory,
and secrets model. This wraps the existing `homelab client add` flow —
see [operations/agent-enrollment.md](../operations/agent-enrollment.md)
for the full walkthrough; this runbook is the risk/lifecycle framing.

1. On any enrolled client: `homelab client add <hostname>` — appends a
   `hosts.<name>:` block to `inventory.yaml` (lifecycle `state: planned`
   → `provisioning`, per [oikos/ontology.yaml](../oikos/ontology.yaml)),
   commits + pushes.
2. Join the new host to Netbird (out-of-band, console or setup key).
3. On the new host: run `bootstrap.sh` (add `--with-hermes` to also
   enroll the Hermes agent). This provisions `/etc/age/key.txt`, the
   sync timer, and prints an age pubkey.
4. Back on an enrolled client: `homelab client add <hostname>
   --finalize-pubkey <age1...>` — sets `age_pubkey`, grants shared
   secrets, re-keys SOPS, commits + pushes. This is the
   `provisioning → active` transition.
5. Verify: `homelab doctor` on the new client should show all checks
   green (clone, sync timer, age key, CLI symlink, MCP reachable).

Docs-update checklist: if the new host is an LXC/VM, add its narrative
page under `containers/` or `vms/` and set `doc_page` in its inventory
entry (host-level cards don't have a `doc_page` field yet — services do;
narrative pages are still found via the generated `see_also` in
`hosts/<name>.yaml`).