dtoro
2a7876c711
AGENTS.md now instructs every agent to communicate tersely. CAVEMAN.md holds the full rules. Agents apply from first message in each session.
116 lines
5.1 KiB
Markdown
116 lines
5.1 KiB
Markdown
# 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.
|