Files

dtoro 85457095e4 DNS single-source Phase 1 + decommission Tailscale fleet-wide

Phase 1 of the DNS-redundancy cleanup (keep NetBird, collapse toward one
zone) — the safe, mesh-independent half:

- Every homelab LXC now resolves via Technitium (192.168.8.2). Fixed 8
  boxes on a dead resolver (.180), the router (.1), or Tailscale MagicDNS
  (100.100.100.100): 101,102,104,105,106,114,119,126.
- Removed the redundant /etc/hosts auth/mcp/secrets overrides (Technitium
  returns identical-or-better answers); disabled hubris-hosts-override.
- Net effect: on-prem DNS (LXCs + household via Fritz!Box->Technitium) is
  now NetBird-independent, so dropping the managed zone later can't break
  on-LAN resolution. Phases 2-4 still pending.

Tailscale decommissioned (was legacy/being-phased-out):
- Removed from the 6 LXCs still running it (101,103,104,105,114,119):
  logout, disable tailscaled, apt purge, state cleared.
- inventory.yaml: dropped tailscale from accepted + all mesh blocks;
  regenerated hosts/*.yaml (also pruned orphan authentik/claudio-bot).
- Tightened secrets-issuance MESH_SUBNETS: removed the now-vestigial
  Tailscale CGNAT range 100.64.0.0/10.
- Updated narrative docs (mesh, dns, network, README, AGENTS,
  agent-enrollment, homelab-context, 105-apps, 107-dns).

Live infra changed on the fleet + Mac; this commit records the docs/inventory.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-21 15:14:07 +02:00

4.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 — Netbird mesh state. Tailscale was decommissioned 2026-06-21; the fleet is Netbird-only.
/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. Auto-setup mechanism

The homelab-context repo ships tooling that gets automatically installed on every client after git pull. This is handled by tools/post-pull.sh (replaces the raw git pull in the sync timer) which runs any script matching tools/*.setup.sh after pull.

Currently auto-setup:

Caveman + templates (tools/setup-caveman.sh): Installs Caveman npm package, wrapper scripts, and compact output templates for token-efficient CLI output. Wrapper at ~/bin/caveman_wrapper.sh.
Hermes agent persona (tools/setup-hermes-soul.sh): Provisions ~/.hermes/SOUL.md from HERMES.md on Hermes agents. This ensures every Hermes agent follows the canonical homelab persona (token efficiency, source of truth hierarchy). No-op on non-Hermes agents.

To add a new auto-setup, create tools/<name>.setup.sh in the repo, commit and push. All enrolled clients pick it up within 5 minutes.

To trigger sync manually: sudo homelab sync or wait for the 5-min timer.

7. When in doubt

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

4.9 KiB Raw Blame History