oikos/OIKOS.md

Oikos — the operating model

Oikos (Greek: household) is the agent operating system layered on this repo. It is not new infrastructure: inventory.yaml is the kernel data structure, the homelab CLI and MCP server are the syscall surface, and this page defines the rules everything above them follows.

Read this after AGENTS.md. Machine-readable companions: oikos/ontology.yaml (systems model), oikos/policy.yaml (risk & approval).

The kernel loop: OODA

Every Oikos activity — scheduled probe, agent task, operator request — is one pass through Observe → Orient → Decide → Act:

1. Observe — probes, drift detectors, and agent findings produce Signals (structured records, not loose messages): pending updates, high temperature, low disk, service down, cert expiry, stale backup, inventory drift.
2. Orient — walk the ontology graph: what entity is affected, what depends on it (blast radius), its lifecycle state, whether a runbook matches, what the ledger says about past attempts.
3. Decide — the classifier scores risk class × blast radius × confidence and routes:
   • auto-act: within autonomy policy, high confidence, contained radius
   • escalate: operator approval via Matrix (✅/❌ reaction; destructive actions additionally need a typed confirmation phrase)
   • queue: informational — console + reports The classifier can only lower autonomy relative to policy, never raise it. When in doubt, escalate.
4. Act — execute through homelab commands or runbooks (never ad-hoc SSH), then verify with the action's verification command, write a ledger entry, resolve the Signal, and update docs in the same session.

Primitives

Primitive	What it is	Lives in
Host / Service	topology entities	inventory.yaml (+ generated hosts/*.yaml)
Secret	SOPS+age encrypted value, per-client recipients	secrets/ + .sops.yaml
Runbook	executable workflow with risk class + verification	runbooks/ (Week 2)
Signal	something needing attention, with lifecycle	signals/ ledger (Week 3)
Change	one mutation: who, what, risk, approval, verification	ledger/ (Week 2)
Approval	short-TTL signed grant for a gated action	approval engine (Week 3)
Incident	investigation narrative	investigations/
Plan	design doc for non-trivial work	plans/
Agent	enrolled client identity = its age pubkey	inventory.yaml + .sops.yaml

Risk classes (enforced, not advisory)

From oikos/policy.yaml:

• read_only — status, logs, docs, inventory. Unattended.
• reversible_low — restart, cache clear, sync pull. Unattended + ledger.
• config_mutation — tracked-config edits (commit+push, never local), deploys, upgrades, DNS/ingress changes. Operator approval.
• destructive — destroy, format, wipe, rotate, revoke. Approval + typed confirmation phrase.

Lifecycle gates modify these: provisioning nodes are freely mutable (nothing depends on them); deprecated nodes accept no new dependents; anything touching a destroyed node is drift.

The systems model

Eight domains — physical, compute, network, storage, software, identity & access, operations, external — cover everything in the lab; entities are connected by typed edges (hosts, provides, mounts, stores-on, routes-to, can-decrypt, depends-on, backs-up-to, …) defined in oikos/ontology.yaml. Rule of completeness: if it can break, be changed, or hold data, it has an entity and edges. Blast-radius questions ("what breaks if strong goes down?") are graph walks, not doc archaeology.

Nodes move through an explicit lifecycle — planned → provisioning → active → migrating → deprecated → destroyed — stored as state: in inventory (absent = active). Destroyed nodes live in the archaeology: section. Each transition is a runbook checklist; deprecation completes only when inbound edges reach zero.

Generated views: infrastructure/topology.md (Mermaid, regenerated from inventory).

Conventions carried forward

• Inventory is the truth; live state wins over narrative docs.
• Prefer homelab CLI and MCP over ad-hoc SSH.
• Meaningful changes update docs in the same session.
• Secrets are decrypted locally via per-client keys; never into docs/comments.
• Tracked configs change by commit + push, not local edits.
• Netbird is the preferred mesh path for new traffic.
• Agents are terse (CAVEMAN.md), verify claims, and fix collateral drift when found.

Build status (30-day roadmap, started 2026-07-05)

• Week 1 (this): policy, ontology, service contract, archaeology, topology generator, this brief.
• Week 2: context cards, homelab service <name> …, change ledger, node relations, runbooks.
• Week 3: Prometheus + node_exporter, ops scheduler + state cache, drift detectors, signal engine, decision classifier, approval engine (Matrix ✅/❌), daily brief.
• Week 4: Oikos Console (oikos.hubris.network, behind Authentik with step-up re-auth on approvals), per-agent age-key-signed approval requests, docs pass, 60/90-day backlog.