oikos/AGENTS.md

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