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 and Deployment Conventions.
• 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.
2. Deployment: See Deployment Conventions for how to roll out changes.
3. SATURN: Remember that SATURN is the only node where commits should be made.

Documentation Index

• Infrastructure Standards
• Agent Operating Procedures (For AI/Non-Human Agents)
• Deployment Conventions
• Hardware
• Networking
• Services
• Node Capabilities
• Action Model

---

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