Files

root 3c25f936d3 Phase 1: cross-client homelab context + MCP scaffolding

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>

2026-05-20 15:47:48 +02:00

3.9 KiB

Raw Blame History

AGENTS.md — orientation for any agent on a homelab client

You are running on a machine that is part of the hubris homelab. The full context is in this checkout at /opt/homelab-context/. This file is the entry point. Read it once at start, then keep working.

1. Who you are

Run hostname (Linux) or scutil --get LocalHostName (macOS), then read:

/opt/homelab-context/hosts/<your-hostname>.yaml

That file tells you your role, your peers, what's mounted, and what services you host. If it does not exist, this client was not enrolled — stop and tell the operator to run homelab client add <hostname> from an existing client.

2. The topology

/opt/homelab-context/inventory.yaml — every host, LXC, VM, and workstation with their mesh addresses, roles, and service mappings. Treat this file as authoritative; anything you read in narrative pages should agree with it.
/opt/homelab-context/infrastructure/mesh.md — Tailscale → Netbird state. Both meshes are accepted today; Netbird is preferred for new traffic.
/opt/homelab-context/infrastructure/dns.md — split-horizon DNS via dnsmasq on LXC 124. *.hubris.network resolves to 192.168.x.x on the LAN and to mesh addresses off-LAN.
/opt/homelab-context/operations/commands.md — the operator's cheatsheet for pct, caddy, dnsmasq. Use these verbs when you take actions.

3. The MCP server

The homelab exposes a Model Context Protocol server with structured tools. Endpoint is in inventory.yaml under services.homelab_mcp.endpoint.

Available tools:

Context (pure read): get_host(name), list_services(), find_service(name_or_role), get_topology(), search_docs(query), get_page(path), get_changelog(page, since?), whoami(hostname), list_my_secrets(caller_pubkey?)

Management (read-only): get_service_status(service), tail_log(service, lines=200), list_lxcs(), get_lxc_state(lxc), ping_service(service)

Mutations are not exposed via MCP. Use the homelab CLI for those, with operator confirmation.

When to prefer MCP over grepping the clone: any time you need to resolve a name to an address, look up service status, or search the wiki by content. Grep is fine for browsing or when MCP is unreachable.

4. Wiki conventions

Pages live under containers/, hosts/, vms/, infrastructure/, investigations/, operations/. Cross-link liberally; orphans are bugs.

Every page ends with a ## Changelog section, entries in reverse-chrono order:

### YYYY-MM-DD — short title
one or two lines describing what changed and why.

Investigation files are dated and slugged: YYYY-MM-DD-slug.md.
Live state takes precedence over docs. If you observe a discrepancy, update the docs in the same session (per the same-session update rule).

5. Acting on the homelab

Read state: prefer MCP tools, then files, then shell. Examples: homelab whoami, homelab list, homelab status, homelab logs caddy.
Cross-host actions (caddy reload, pct exec, etc.): use the homelab CLI — it resolves hostname → mesh address → ssh / pct path for you. Direct SSH still works; the CLI just removes the lookup burden.
Secrets: never hardcode. Call homelab secret <name> to decrypt on demand using the per-client age key at /etc/age/key.txt. Secrets ARE available in this system — list_my_secrets() (MCP) shows what you can decrypt.
Mutations (restart, edit configs, etc.): the homelab CLI's mutating subcommands ask for confirmation. For ad-hoc work, SSH and edit directly — but commit changes that touch tracked configs (caddy, gitea custom, artifacto, mule-image, etc.; see infrastructure/auto-deploy.md).
Wiki updates: same-session rule applies to any meaningful state change this client makes.

6. When in doubt

Run homelab mcp search_docs <query> or homelab mcp get_host <name>. The clone is the fallback; MCP is the index.

3.9 KiB Raw Blame History