oikos/README.md

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 MCP search_knowledge instead.
• 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