dtoro
205d8a1a43
Oikos Console v0 (oikos/console/) — read-mostly, server-rendered FastAPI + Jinja2 web UI, no SPA build chain. Signals landing page, service grid + detail, node/blast-radius view, live Mermaid relationship graph, drift findings, approvals queue (approve/deny, destructive confirmation-phrase enforced), daily/weekly reports. Tested end-to-end via the preview tools against live production data, including a real click-through of the approve/deny flow. Found and fixed two bugs during that testing: - Severity-dot CSS classes didn't match the actual severity strings (dot-warn/dot-crit vs "warning"/"critical") — warning-severity signals rendered with no visible indicator at all. - The console's sys.path setup pointed at its own webhook checkout (/opt/oikos-console) rather than /opt/homelab-context, which would have made its oikos.* imports resolve to a SEPARATE copy of oikos/signal.py etc. than the scheduler and CLI use — silently forking signal/approval data into two locations in production. Fixed to match mcp/server.py's CONTEXT_DIR pattern. Also added _commit_push() so the console's writes (approval replies, signal ack/resolve) don't sit uncommitted against the 5-min-synced clone. Split oikos/gen_topology_lib.py out of oikos/gen-topology.py (hyphenated filenames aren't importable) so the console's /graph route can render live without shelling out. oikos/console/deploy/ — third webhook on dtoro/Homelab-Docs (port 9831), matching the homelab-mcp/secrets-issuance precedent. README documents the Caddy route and Gitea webhook registration this repo can't do for itself, and that Authentik step-up on /approvals needs a live instance to configure. Approval hardening: grants are now single-use (oikos/approve.py check_grant marks the request "executed" atomically, so a second call for the same id fails even within the TTL) — verified with a test. Per- agent age-key-signed requests, as originally planned, turned out not to be buildable as stated: age is encryption-only, no signing primitive. Documented the real alternative (SSH-key signing) and moved it to the 60/90-day backlog pending an inventory schema gap (no SSH pubkeys recorded today). Docs pass: added the Oikos command surface to operations/commands.md, new MCP tools to AGENTS.md. Found two more stale references while at it — commands.md and AGENTS.md both still pointed DNS at the destroyed LXC 124/dnsmasq instead of Technitium on dns (107), and a claudio-monitor reference deprecated since 2026-06-04 — fixed both. 60/90-day backlog written into OIKOS.md, derived from gaps actually observed this month, not guesswork. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
133 lines
6.1 KiB
Markdown
133 lines
6.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.
|
|
|
|
The operating model — OODA loop, risk classes, approval rules, the ontology,
|
|
and node lifecycle — is defined in [OIKOS.md](OIKOS.md). Before any mutation,
|
|
classify the action against `oikos/policy.yaml`; when the class requires
|
|
approval, stop and ask the operator.
|
|
|
|
## 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
|
|
Technitium on [dns (107)](../containers/107-dns.md). `*.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, DNS, and the Oikos command surface. 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)
|
|
|
|
Oikos (read-only; see OIKOS.md):
|
|
explain(service) — compact context card, cheaper than search_docs+get_page
|
|
preflight(service) — risk class, approval requirement, verification command
|
|
get_relations(entity) — ontology blast-radius query (host: or service: id)
|
|
get_change_history(entity, limit=20) — change-ledger entries
|
|
get_state_snapshot() — last scheduler Observe-pass (health, disk, drift count)
|
|
|
|
Mutations are **not** exposed via MCP. Use the `homelab` CLI for those, with
|
|
operator confirmation — see OIKOS.md's risk classes and approval flow.
|
|
|
|
**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.): classify against
|
|
`oikos/policy.yaml` first (`homelab decide <action> <entity>`).
|
|
`reversible_low` actions just need the interactive confirmation prompt;
|
|
`config_mutation`/`destructive` actions are mechanically refused without
|
|
a valid `--approval-id` from `homelab approval request` — see OIKOS.md.
|
|
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.
|