dtoro
b230ab5937
Adds the Oikos agent-OS kernel: oikos/policy.yaml (risk classes + approval rules for every homelab/MCP command), oikos/ontology.yaml (8-domain systems model, typed relationships, node lifecycle), and OIKOS.md (OODA loop operating brief, linked from AGENTS.md). Extends inventory.yaml with a stable service contract (doc_page, config_repo, risk_notes) on all 17 services, and a structured archaeology: section for the 13 destroyed LXCs (was scattered comments + a narrative table). Fixes stale drift found in the process: authentik's backend pointed at a retired LXC (124); core has run on the VPS since 2026-05-31. Adds oikos/gen-topology.py, generating infrastructure/topology.md (Mermaid compute/ingress + storage views) from inventory.yaml. build_host_files.py now carries state/storage/depends_on into generated hosts/*.yaml. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.3 KiB
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. 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 dnsmasq on LXC 124.*.hubris.networkresolves 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
## Changelogsection, 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
homelabCLI — 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
homelabCLI'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.; seeinfrastructure/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.mdfromHERMES.mdon 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.