homelab-codex-ws/README.md

# Homelab Codex

GitOps-lite orchestration for a distributed homelab environment.

## Architecture

The homelab consists of several nodes connected via a Tailscale internal mesh.

| Host | Role | Description |
|------|------|-------------|
| **SATURN** | Primary Node | Development, orchestration, and git source of truth (commit node). |
| **SOLARIA** | Compute Node | GPU, inference, and heavy compute workloads. |
| **PIHA** | Infra Node | Core infrastructure services, automation, and monitoring. |
| **VPS** | Edge Node | Public ingress, reverse proxy, and edge services. |

## Agent System

The homelab uses a multi-agent orchestration model with human-in-the-loop for destructive actions:

| Agent | Node | Role |
|-------|------|------|
| **stability-agent** | all nodes | Per-node watchdog — monitors Docker, disk, Tailscale, MQTT; emits events |
| **node-agent** | all nodes | Publishes container health events to Redis pub/sub |
| **observer** | VPS | Synthesizes world state from events into `/opt/homelab/world/*.json` |
| **supervisor** | VPS | Detects drift between desired and actual state; writes `pending` actions |
| **planner-agent** | SOLARIA | LLM-powered diagnosis — listens to Redis, proposes remediation actions |
| **executor** | VPS | Executes actions only after operator approval |
| **operator-ui** + **telegram-bot** | VPS / PIHA | Operator reviews and approves/rejects pending actions |

Action approval flow: `pending/` → operator approves → `approved/` → executor runs.

## Repository Structure

- `docs/`: [Infrastructure Standards](kb/subsystems/standards.md) and [Deployment Conventions](kb/subsystems/deployment.md).
- `kb/phases/subsystem-a-naprawa.md`: [Current Maintenance Plan (Control Plane)](kb/phases/subsystem-a-naprawa.md).
- `hosts/`: Host-specific configurations and service assignments.
- `services/`: Reusable Docker Compose service definitions.
- `scripts/`: Deployment and management scripts.

## Getting Started

1.  **Standardization**: Follow the [Infrastructure Standards](kb/subsystems/standards.md).
2.  **Deployment**: See [Deployment Conventions](kb/subsystems/deployment.md) for how to roll out changes.
3.  **SATURN**: Remember that SATURN is the only node where commits should be made.

## Documentation Index

- [Current Maintenance Plan (Control Plane)](kb/phases/subsystem-a-naprawa.md)
- [Infrastructure Standards](kb/subsystems/standards.md)
- [Agent Operating Procedures](kb/subsystems/agent-operating-procedures.md) (For AI/Non-Human Agents)
- [Deployment Conventions](kb/subsystems/deployment.md)
- [Hardware](kb/nodes/legacy-hardware.md)
- [Networking](kb/subsystems/networking.md)
- [Services](kb/subsystems/legacy-services-list.md)
- [Node Capabilities](kb/subsystems/capability-model.md)
- [Action Model](kb/subsystems/action-approval-model.md)

---
*Note: This repository documents the state of the homelab. Runtime state lives outside the repository in `/opt/homelab`.*