dtoro
e30813a43d
Closes the gap that made the knowledge loop optional/implicit: every non-trivial task now has an EXPLICIT first plan step (research) and last plan step (write back), not just background behavior the model might skip. New MCP tools (the agent had no way to do these before — only REST endpoints existed, unexposed to it): - update_entity_attributes(slug, attributes): shallow-merge new/changed facts into an entity (an IP, a version, a discovered port) so a future task doesn't have to rediscover them from scratch. No approval required — this updates the knowledge graph, not live infra. - create_relationship(source, target, type): record a discovered edge (depends-on, hosts, provides, ...). Idempotent, FK-validated against the ontology's relationship_types, no approval required. SOUL.md: restructured the task loop so step 1 is explicitly "gather knowledge, not just status" (get_entity_knowledge, search_knowledge, get_relations, get_blast_radius, http_get) and the last step before complete_task is explicitly "write back" (update_entity_attributes, create_relationship, upsert_knowledge) — both called out as real plan entries the operator should see in propose_plan, not silent side-work. This is what prevents the graph drifting from reality and is the concrete mechanism behind "tasks compound." propose_plan's tool description reinforces the same first-step/last-step convention at the call site. Verified against the live stack: both tools registered and callable via MCP; update_entity_attributes merged an attribute correctly; create_relationship rejected an invalid type (FK violation, clear error) and succeeded with a valid type+direction, confirmed idempotent (2 calls, 1 row). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Oikos
Agentic homelab operating system written in Go. Single binary (cmd/oikos),
Docker-deployed on mac-mini, with a standalone Nomos MCP agent gateway
(cmd/nomos). Manages the hubris Proxmox homelab autonomously — observes
state, classifies actions against policy, executes approved procedures over SSH,
learns from outcomes, and escalates when uncertain.
For agents running on enrolled clients: start with AGENTS.md. For client machines: see CLIENTS.md. For developers: see CONTRIBUTING.md.
Quick start
# Dev stack (postgres + api + scheduler + notifier)
docker compose --profile dev up -d
# Full stack (adds Nomos agent gateway)
docker compose --profile full up -d
# Build standalone binary
go build -o bin/oikos -tags timetzdata ./cmd/oikos
# Run all roles in one process (dev mode)
OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disable" \
go run ./cmd/oikos all
Architecture
┌──────────────────────────────────┐
│ mac-mini (Docker) │
│ │
Workstation ─── │ nomos (8092) ──MCP── api (8090) │
(mesh) │ MCP gateway REST + MCP │
│ │
│ scheduler ── notifier ── postgres │
│ (observe) (Matrix) (Timescale)│
└──────────────────────────────────┘
| Component | Port | Role |
|---|---|---|
oikos api |
8090 | REST API + MCP server (15 tools) |
oikos scheduler |
— | Probe runner, signal lifecycle, metrics |
oikos notifier |
— | Approval tokens, Matrix alerts |
nomos serve |
8092 | MCP client gateway, query routing |
Phases
| Phase | Status | Description |
|---|---|---|
| 1 — Ontology + DB | ✅ | TimescaleDB, migrations, seeds, blast_radius |
| 2 — API | ✅ | OpenAPI-first REST + MCP, auth, SSE, audit |
| 3 — Control loop | ✅ | Scheduler, actuator, learning, classifier, notifier |
| 4 — Nomos agent | ✅ | Standalone MCP client gateway, agent activity |
| 5 — Secrets | ✅ | Infisical backend + SOPS fallback, rotation runbooks |
| 6 — Deploy | ✅ | CI pipeline, cutover checklist, watchdog, rollback |
Full plan: plans/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md.
Operations
API endpoints
curl http://localhost:8090/api/v1/entities?type=service # fleet
curl http://localhost:8090/api/v1/health # fleet health
curl http://localhost:8090/api/v1/agent-activity # agent log
Nomos queries
# Structured tool call
curl -X POST localhost:8092/query -H "Content-Type: application/json" \
-d '{"tool":"get_blast_radius","args":{"entity_id":"service:authentik"}}'
# Natural language
curl -X POST localhost:8092/query -H "Content-Type: application/json" \
-d '{"query":"what depends on authentik?"}'
CLI
oikos migrate # apply DB migrations
oikos seed # ingest ontology/inventory/policy seeds
oikos export # export DB state to YAML
oikos api # serve REST + MCP
oikos scheduler # run observe loop
oikos notifier # run notification loop
oikos all # all roles in one process
oikos secret list # enumerate SOPS secrets
oikos secret migrate # SOPS → Infisical
Repo layout
cmd/oikos/ Go entry point — single binary
cmd/nomos/ Nomos MCP client gateway
internal/ Go packages (httpapi, mcp, scheduler, actuator, learning,
notifier, policy, secrets, db, config, ontology, domain,
knowledge)
api/openapi.yaml API contract (OpenAPI 3.1)
migrations/ Forward-only SQL migrations (TimescaleDB)
seeds/ Bootstrap YAML (ontology, inventory, policy, knowledge)
compose/ Dockerfiles + Caddy config
scripts/ Deploy, watchdog, verification, rollback
nomos/ Nomos config, persona, skills
.agents/ Agent instruction files, shared conventions, skills
archive/ Historical reference (legacy wiki, plans, SOPS backups)
plans/ Design documents (active + done)
docs/adr/ Architecture decision records
For agents
See AGENTS.md for the full orientation. Quick reference:
- Source of truth: DB (runtime) then seeds (bootstrap). Old wiki is
archived at
archive/knowledge/— use MCPsearch_knowledgeinstead. - Mutations: classify against policy, request approval for
destructive/config_mutation - Secrets: Infisical (primary) or SOPS (fallback) — never hardcode
Related
- OIKOS.md — operating model, OODA loop, ontology
- CLIENTS.md — client onboarding guide
- CONTRIBUTING.md — developer guide
- plans/ — design documents and cutover checklist
- docs/adr/ — architecture decision records