3c25f936d3
Add the foundation for distributing homelab context to every client (LXCs, VMs, workstations including republic-laptop, mac-mini, ludo-mini) with a single source of truth, structured query layer (MCP), and per-client age-key issuance for secrets: - inventory.yaml — canonical topology (hosts, services, mesh addresses) - hosts/*.yaml — per-host identity files generated from inventory by mcp/build_host_files.py; do not edit by hand - AGENTS.md — orientation doc symlinked to /root/AGENTS.md on every client - bootstrap.sh — one-shot enroll (Linux + macOS), clones repo, fetches age key from issuance, installs sync timer/launchd job, drops the homelab CLI - bin/homelab — single-binary Python CLI: whoami, list, ssh, pct, logs, restart, open, status, secret, sync, mcp, client add/remove, nuke - mcp/server.py — FastMCP server: context tools + read-only management tools (no mutations exposed); shell-outs use mcp-reader restricted ssh key - mcp/deploy/ — claudio-monitor-style gitea webhook deploy scaffold for the MCP service on LXC 105 (ports 9810 mcp, 9811 webhook) - secrets-issuance/ — per-client age key auto-provisioning over the mesh; source-IP gated against inventory, with denylist for revoked clients (ports 9820 issue, 9821 webhook) - secrets/, .sops.yaml — SOPS recipient scaffolding; the operator fills in age public keys after Phase 3a generates them - scripts/sync/ — systemd timer (Linux) + launchd plist (macOS) pulling /opt/homelab-context every 5 min Mesh: both Netbird (preferred, 100.122.0.0/16) and Tailscale accepted during the in-flight migration; no client is gated on completing the move. Plan reference: /root/.claude/plans/lets-make-a-plan-fluttering-trinket.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
secrets/
SOPS-encrypted YAML files. The plaintext lives only in transit and in the operator's head — committed files are always ciphertext.
Conventions
- One file per logical grouping (e.g.
gitea-tokens.yaml,webhook-hmacs.yaml,api-keys.yaml). - Recipients are declared in
../.sops.yamlby path-regex, not per-file. - The plaintext schema inside each file is free-form YAML; the consumer code
decides what it expects (e.g.
gitea-tokens.yamlcontains{"<host>": "ghp_xxx"}).
How to add a secret
# 1. Decide which clients should be able to decrypt it; edit ../.sops.yaml to
# list their age public keys for the new path_regex.
# 2. Create the plaintext, encrypt in place:
sops -e --in-place secrets/my-thing.yaml
# 3. Commit + push. The 5-min sync propagates to every recipient.
How to consume a secret
# On any client that's a recipient:
homelab secret my-thing # prints plaintext
# Or programmatically:
sops -d /opt/homelab-context/secrets/my-thing.yaml
The mcp tool list_my_secrets(caller_pubkey) returns the names of secrets
the caller can decrypt. The MCP server never reads plaintext — decryption
stays client-side.
Granting / revoking access
To grant a new recipient: edit ../.sops.yaml to add their age pubkey, then
re-key every affected file:
sops updatekeys -y secrets/my-thing.yaml
To revoke: remove the recipient from ../.sops.yaml and sops updatekeys —
but remember this only protects future ciphertext. Past plaintext the client
already decrypted is gone from your control. Rotate the underlying credential
if compromise is suspected.
homelab client remove <name> does the recipient removal + updatekeys for
you, and prints the rotation checklist as a follow-up.
hello.yaml — bootstrap decrypt test
secrets/hello.yaml is encrypted to every enrolled client. Used by Phase 3a
verification to confirm the end-to-end decrypt path works on a freshly-
bootstrapped machine. Content is intentionally trivial:
greeting: hello from the homelab