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>
108 lines
5.2 KiB
Markdown
108 lines
5.2 KiB
Markdown
# 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](AGENTS.md). Machine-readable companions:
|
||
[oikos/ontology.yaml](oikos/ontology.yaml) (systems model),
|
||
[oikos/policy.yaml](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](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](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](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](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.
|