Files

dtoro 2a7876c711 add caveman compression mode to agent bootstrap

AGENTS.md now instructs every agent to communicate
tersely. CAVEMAN.md holds the full rules. Agents
apply from first message in each session.

2026-06-21 23:36:06 +02:00

5.1 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. Communication mode

Read and apply /opt/homelab-context/CAVEMAN.md (if present). It defines the lab's terse-communication standard — drop filler, keep substance, use fragments.

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

8. When in doubt

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

5.1 KiB Raw Blame History