Files

dtoro 638e313c66 docs: add client lifecycle plan, cleanup stale files, document repo for 3 audiences

Problem: Repo had no developer guide, no client onboarding doc, no agent
dev instructions. Stale files (675KB SQL dump, one-off convert script,
legacy MCP builder) cluttered the tree. Client enrollment was a documented
intention with no Go implementation.

Changes:
- New docs: CONTRIBUTING.md (dev setup), CLIENTS.md (client onboarding),
  .agents/dev/CONTRIBUTING.md (agent codebase map)
- New plan: plans/2026-07-07-client-lifecycle-in-go.md — full client
  lifecycle (planned→provisioning→active→deprecated→destroyed) in Go,
  replacing archived Python secrets-issuance, adding client API endpoints
  and 6 missing MCP tools
- Cleanup: deleted archive/convert-wiki.py (one-off), archive/mcp/
  build_host_files.py (legacy), backups/pre-deploy-7f7d039.sql (local)
- Fixes: plans/index.md duplicate row removed, README.md repo layout
  updated for current state, AGENTS.md header points to new guides

Risk: low. Docs only + stale file deletion. No code changes. New plan is
proposal, not implementation.
Verification: git diff reviewed, all changes are prose/docs/plans.

2026-07-07 23:45:32 +02:00

4.1 KiB

Raw Blame History

Oikos — client guide

If you are a homelab machine, this is what Oikos is and what it gives you. If you are an AI agent running on this machine, also read AGENTS.md.

What is Oikos?

Oikos is the agentic operating system for the hubris Proxmox homelab. It observes state, classifies actions against policy, executes approved procedures, learns from outcomes, and notifies the operator. It runs as a Docker stack on mac-mini and exposes an MCP server + REST API.

What Oikos provides

Capability	How you access it
Entity query (topology, blast radius)	MCP `get_entity`, `get_blast_radius`
Full-text knowledge search	MCP `search_knowledge`
Service status + logs	MCP `get_service_status`, `tail_log`
LXC inventory + state	MCP `list_lxcs`, `get_lxc_state`
Context cards	MCP `explain`
Pre-flight risk classification	MCP `preflight`
Change history	MCP `get_change_history`
State snapshot (health, disk, drift)	MCP `get_state_snapshot`
Secrets (Infisical)	REST API + `oikos secret` CLI
Approval tokens	Matrix via notifier

All MCP tools are read-only. Mutations use the homelab CLI with operator approval.

Enrollment

Enrolled clients have a checkout at /opt/homelab-context/. If this directory does not exist, the client is not enrolled.

To enroll:

# Run from an existing enrolled client
homelab client add <hostname>

This runs bootstrap.sh on the target, which:

Clones the repo to /opt/homelab-context/
Configures the auto-sync timer
Provisions agent persona from hermes/SOUL.md (on Hermes agents)
Installs Caveman tooling for terse communication

After enrollment

What changes on your machine

/opt/homelab-context/ — the repo checkout, your source of truth
/opt/homelab-context/inventory.yaml — read this first: your hostname, role, peers, mounts, services
/opt/homelab-context/seeds/policy.yaml — rules for what actions you can take autonomously vs. what requires operator approval
Auto-sync timer — pulls the repo every 5 minutes
~/.hermes/SOUL.md — agent persona (on Hermes agents)
~/bin/caveman_wrapper.sh — terse communication tooling

Your identity

Your identity in the homelab is defined in inventory.yaml. Run hostname (Linux) or scutil --get LocalHostName (macOS), then look up your entry. It tells you your role, what services you host, what's mounted, and your mesh address.

Source of truth hierarchy

Postgres database (runtime) — authoritative for entities, knowledge, signals, ledger. Query via MCP or REST API.
Repo at /opt/homelab-context/ — bootstrap seeds + documentation. On disk, available offline.
Never guess. If data is missing, query MCP. If MCP is down, grep the clone.

The sync timer

Every 5 minutes, systemd (Linux) or launchd (macOS) runs:

git pull via tools/post-pull.sh
Any tools/*.setup.sh scripts that need to run

This keeps your checkout current and applies tooling updates automatically. To trigger sync manually: sudo homelab sync.

Making changes

Read state: use MCP tools or the repo checkout
Mutate state (restart, edit config, deploy): classify the action against seeds/policy.yaml:
- read_only / reversible_low — execute directly
- config_mutation / destructive — request operator approval via the homelab CLI
Secrets: use Infisical (primary) or SOPS (fallback). Never hardcode.
Knowledge: if you observe a discrepancy between docs and live state, update the DB via the API in the same session. Run oikos export to regenerate seeds.

MCP endpoint

https://mcp.hubris.network/mcp

Available tools are listed in AGENTS.md.

Communication mode

Apply .agents/shared/caveman.md — terse, fragment-heavy communication. Drop filler, keep substance.

AGENTS.md — full agent orientation (read this first)
OIKOS.md — operating model, OODA loop, risk classes
CONTRIBUTING.md — developer guide for the Oikos codebase

4.1 KiB Raw Blame History