dtoro
e3a0326c78
Full review (plans/2026-07-17-codebase-review-and-cleanup.md) covering Go, web SPA, and docs. Applied low-risk doc/tooling fixes; code refactors and dead-code deletions are listed as actionable recommendations pending approval. Doc fixes: - AGENTS.md: remove ghost of retired request_execution (contradicted the retire notice above it); fix knowledge/wiki/ -> archive/knowledge/; replace brittle counts (33 tools, 36 docs, 20 checks) with pointers to source; drop point-in-time dates. - OIKOS.md: fix broken plan link (now in done/); 001-011 -> 001-020; 15 MCP tools -> pointer; replace hardcoded knowledge counts. - README.md: 15 tools -> pointer; fix wails plan link (now in done/); complete internal/ package list (add checkdefaults, observability, safego); add cmd/desktop/ to repo layout. - commands.md, page-templates.md: fix broken links; HERMES.md -> NOMOS.md. Plans housekeeping: - Move 4 done 2026-07-14 plans from plans/ to plans/done/. - Reconcile plans/index.md: add the 2 missing 2026-07-14 entries and the 2 missing 2026-07-15 done entries; add this review. - Fix stale plan path in migrations/020 comment. New docs: - docs/index.md and docs/operations/README.md (folder READMEs per writing-style.md). Tooling: - web/package.json: add check/typecheck/lint scripts + svelte-check devDep. - Makefile: desktop-package version now reads from VERSION file instead of hardcoded 0.1.0. VERSION 0.7.6 -> 0.7.7 (patch: docs + tooling only).
163 lines
6.8 KiB
Markdown
163 lines
6.8 KiB
Markdown
# 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](AGENTS.md).
|
|
**For client machines:** see [CLIENTS.md](CLIENTS.md).
|
|
**For developers:** see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Dev stack (postgres + api + scheduler + notifier). The api/nomos
|
|
# services need a shared token — every route requires a real bearer
|
|
# credential, there's no dev-open bypass.
|
|
OIKOS_MCP_BEARER_TOKEN=dev-token docker compose --profile dev up -d
|
|
|
|
# Full stack (adds Nomos agent gateway)
|
|
OIKOS_MCP_BEARER_TOKEN=dev-token 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" \
|
|
OIKOS_API_TOKEN=dev-token \
|
|
go run ./cmd/oikos all
|
|
|
|
# Control-room SPA (separate from the Go binary — see web/)
|
|
cd web && OIKOS_API_TOKEN=dev-token npm run dev # http://localhost:5173
|
|
```
|
|
|
|
## 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 (tool list in [AGENTS.md §3](AGENTS.md#3-the-mcp-server)) |
|
|
| `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/done/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md](plans/done/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md).
|
|
|
|
## Operations
|
|
|
|
### API endpoints
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $OIKOS_API_TOKEN" \
|
|
http://localhost:8090/api/v1/entities?type=service # fleet
|
|
curl -H "Authorization: Bearer $OIKOS_API_TOKEN" \
|
|
http://localhost:8090/api/v1/health # fleet health
|
|
curl -H "Authorization: Bearer $OIKOS_API_TOKEN" \
|
|
http://localhost:8090/api/v1/agent-activity # agent log
|
|
```
|
|
|
|
### Nomos queries
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Web UI
|
|
|
|
`web/` is a standalone Svelte 5 SPA — not embedded in the `oikos` binary, not
|
|
part of `docker-compose.yml`. It talks to `api`/`nomos` over HTTP with a
|
|
bearer token entered on first launch (see `web/src/pages/Config.svelte`).
|
|
Build with `make ui`, deploy with `make deploy-ui` (Caddy serves the static
|
|
output). A native desktop wrapper exists at `cmd/desktop/` — see
|
|
[plans/done/2026-07-12-wails-desktop-app.md](plans/done/2026-07-12-wails-desktop-app.md).
|
|
|
|
## Repo layout
|
|
|
|
```
|
|
cmd/oikos/ Go entry point — single binary
|
|
cmd/nomos/ Nomos MCP client gateway
|
|
cmd/webhook/ Gitea deploy-webhook receiver (push-to-deploy on mac-mini)
|
|
cmd/desktop/ Wails desktop wrapper around the SPA
|
|
internal/ Go packages (actuator, checkdefaults, config, db, domain,
|
|
httpapi, knowledge, learning, mcp, notifier, observability,
|
|
ontology, policy, safego, scheduler, secrets)
|
|
web/ Control-room SPA (Svelte 5) — standalone, not embedded
|
|
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
|
|
checks/ Host health-check scripts run over SSH by the scheduler
|
|
tools/ Client auto-setup scripts (checks)
|
|
ssh/ Deploy keys + authorized_keys management
|
|
vps/ Caddy/TURN config templates for the netbird VPS
|
|
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
|
|
docs/operations/ Runbooks (rollback, etc.)
|
|
```
|
|
|
|
## For agents
|
|
|
|
See [AGENTS.md](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](.agents/OIKOS.md) — operating model, OODA loop, ontology
|
|
- [CLIENTS.md](CLIENTS.md) — client onboarding guide
|
|
- [CONTRIBUTING.md](CONTRIBUTING.md) — developer guide
|
|
- [plans/](plans/) — design documents and cutover checklist
|
|
- [docs/adr/](docs/adr/) — architecture decision records
|