2026-05-07 21:16:03 +02:00
|
|
|
# Homelab Codex
|
2026-04-15 17:37:25 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
GitOps-lite orchestration for a distributed homelab environment.
|
2026-04-15 17:37:25 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
## Architecture
|
2026-04-15 17:37:25 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
The homelab consists of several nodes connected via a Tailscale internal mesh.
|
2026-04-15 17:37:25 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
| 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. |
|
2026-05-05 17:25:50 +02:00
|
|
|
|
docs: add planner-agent docs and session summary 2026-05-27
- services/planner-agent/README.md: full service doc (what it does,
LLM fallback chain, env vars, deploy steps, local run, redis-cli
end-to-end test, healthcheck)
- README.md: add Agent System section with all agents and their roles
- docs/sessions/2026-05-27-planner-agent.md: session summary (built
files, architectural decisions, problems + solutions, deployment
status, pending work)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-27 22:35:59 +02:00
|
|
|
## 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.
|
|
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
## Repository Structure
|
2026-05-05 17:25:50 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
- `docs/`: [Infrastructure Standards](docs/standards.md) and [Deployment Conventions](docs/deployment.md).
|
|
|
|
|
- `hosts/`: Host-specific configurations and service assignments.
|
|
|
|
|
- `services/`: Reusable Docker Compose service definitions.
|
|
|
|
|
- `scripts/`: Deployment and management scripts.
|
2026-05-05 17:25:50 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
## Getting Started
|
2026-05-05 17:25:50 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
1. **Standardization**: Follow the [Infrastructure Standards](docs/standards.md).
|
|
|
|
|
2. **Deployment**: See [Deployment Conventions](docs/deployment.md) for how to roll out changes.
|
|
|
|
|
3. **SATURN**: Remember that SATURN is the only node where commits should be made.
|
2026-05-05 17:25:50 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
## Documentation Index
|
2026-04-15 17:37:25 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
- [Infrastructure Standards](docs/standards.md)
|
2026-05-20 12:06:23 +02:00
|
|
|
- [Agent Operating Procedures](docs/agents.md) (For AI/Non-Human Agents)
|
2026-05-07 21:16:03 +02:00
|
|
|
- [Deployment Conventions](docs/deployment.md)
|
2026-04-15 17:37:25 +02:00
|
|
|
- [Hardware](docs/hardware.md)
|
|
|
|
|
- [Networking](docs/networking.md)
|
|
|
|
|
- [Services](docs/services.md)
|
2026-05-20 12:06:23 +02:00
|
|
|
- [Node Capabilities](docs/capabilities.md)
|
|
|
|
|
- [Action Model](services/agent-system/action-model.md)
|
2026-04-15 17:37:25 +02:00
|
|
|
|
2026-05-07 21:16:03 +02:00
|
|
|
---
|
|
|
|
|
*Note: This repository documents the state of the homelab. Runtime state lives outside the repository in `/opt/homelab`.*
|
