# Oikos — client guide

If you are a homelab machine, this is what Oikos is and what it gives you.
If you are an AI agent running on this machine, also read [AGENTS.md](AGENTS.md).

## What is Oikos?

Oikos is the agentic operating system for the **hubris** Proxmox homelab. It
observes state, classifies actions against policy, executes approved
procedures, learns from outcomes, and notifies the operator. It runs as a
Docker stack on mac-mini and exposes an MCP server + REST API.

## What Oikos provides

| Capability | How you access it |
|------------|-------------------|
| Entity query (topology, blast radius) | MCP `get_entity`, `get_blast_radius` |
| Full-text knowledge search | MCP `search_knowledge` |
| Service status + logs | MCP `get_service_status`, `tail_log` |
| LXC inventory + state | MCP `list_lxcs`, `get_lxc_state` |
| Context cards | MCP `explain` |
| Pre-flight risk classification | MCP `preflight` |
| Change history | MCP `get_change_history` |
| State snapshot (health, disk, drift) | MCP `get_state_snapshot` |
| Secrets (Infisical) | REST API + `oikos secret` CLI |
| Approval tokens | Matrix via notifier |

All MCP tools are read-only. Mutations use the `homelab` CLI with operator
approval.

## Enrollment

Enrolled clients have a checkout at `/opt/homelab-context/`. If this
directory does not exist, the client is not enrolled.

To enroll:
```bash
# Run from an existing enrolled client
homelab client add <hostname>
```

This runs `bootstrap.sh` on the target, which:
1. Clones the repo to `/opt/homelab-context/`
2. Configures the auto-sync timer
3. Provisions agent persona from `hermes/SOUL.md` (on Hermes agents)
4. Installs Caveman tooling for terse communication

## After enrollment

### What changes on your machine

- `/opt/homelab-context/` — the repo checkout, your source of truth
- `/opt/homelab-context/inventory.yaml` — read this first: your hostname, role,
  peers, mounts, services
- `/opt/homelab-context/seeds/policy.yaml` — rules for what actions you can
  take autonomously vs. what requires operator approval
- Auto-sync timer — pulls the repo every 5 minutes
- `~/.hermes/SOUL.md` — agent persona (on Hermes agents)
- `~/bin/caveman_wrapper.sh` — terse communication tooling

### Your identity

Your identity in the homelab is defined in `inventory.yaml`. Run `hostname`
(Linux) or `scutil --get LocalHostName` (macOS), then look up your entry.
It tells you your role, what services you host, what's mounted, and your
mesh address.

### Source of truth hierarchy

1. **Postgres database** (runtime) — authoritative for entities, knowledge,
   signals, ledger. Query via MCP or REST API.
2. **Repo at `/opt/homelab-context/`** — bootstrap seeds + documentation.
   On disk, available offline.
3. **Never guess.** If data is missing, query MCP. If MCP is down, grep the
   clone.

## The sync timer

Every 5 minutes, `systemd` (Linux) or `launchd` (macOS) runs:

1. `git pull` via `tools/post-pull.sh`
2. Any `tools/*.setup.sh` scripts that need to run

This keeps your checkout current and applies tooling updates automatically.
To trigger sync manually: `sudo homelab sync`.

## Making changes

- **Read state**: use MCP tools or the repo checkout
- **Mutate state** (restart, edit config, deploy): classify the action against
  `seeds/policy.yaml`:
  - `read_only` / `reversible_low` — execute directly
  - `config_mutation` / `destructive` — request operator approval via the
    `homelab` CLI
- **Secrets**: use Infisical (primary) or SOPS (fallback). Never hardcode.
- **Knowledge**: if you observe a discrepancy between docs and live state,
  update the DB via the API in the same session. Run `oikos export` to
  regenerate seeds.

## MCP endpoint

```
https://mcp.hubris.network/mcp
```

Available tools are listed in [AGENTS.md](AGENTS.md#3-the-mcp-server).

## Communication mode

Apply [.agents/shared/caveman.md](.agents/shared/caveman.md) — terse,
fragment-heavy communication. Drop filler, keep substance.

## Related

- [AGENTS.md](AGENTS.md) — full agent orientation (read this first)
- [OIKOS.md](.agents/OIKOS.md) — operating model, OODA loop, risk classes
- [CONTRIBUTING.md](CONTRIBUTING.md) — developer guide for the Oikos codebase