homelab-codex-ws/kb/subsystems/control-plane.md

okf	type	visibility	status	updated	links	superseded_by
0.1	subsystem	private	deprecated	2026-05-27	../runbooks/control-plane-deploy-recovery.md	przepisany tor redeploy, commity da151fc/79bfe8c 2026-08-03

VPS Control Plane

The VPS Control Plane is the orchestration brain of the homelab platform. It runs on the Hetzner VPS (Tailscale IP: 100.95.58.48) and provides observability, automated reconciliation, and a web-based operator interface.

Architecture

The control plane consists of four core services running as a Docker Compose stack under services/control-plane/:

Container	Role
control-plane-observer	Synthesizes world state from events in /opt/homelab/events/
control-plane-supervisor	Detects drift between desired state (hosts/*/services.yaml) and actual state (world/services.json); writes pending actions
control-plane-executor	Executes approved actions from /opt/homelab/actions/approved/
control-plane-ui	Web interface for system monitoring and action approval; serves port 18180

All services use filesystem-first semantics with /opt/homelab/ as the data exchange layer. All four run with network_mode: host and as UID 1000 (homelab user).

Supervisor Behavior

Desired State

Loaded from hosts/*/services.yaml each reconcile cycle. Services with monitor: false are silently skipped — use this for services without a node-agent (e.g. homeassistant on chelsty-ha).

Drift Types

• missing_service — service is in desired state but absent from services.json
• unhealthy_service — service exists in services.json but status != healthy

Action Types

Trigger	Action type	Risk
containers_not_running, mqtt_unreachable	container_restart	low
Any other / unknown	redeploy	guarded
Node disk_pressure: high	disk_cleanup	guarded

Action ID Stability

Action IDs are deterministic: redeploy-{node}-{service} or container-restart-{node}-{service}. The same drift always produces the same filename, making reconcile truly idempotent across supervisor restarts.

Auto-Cancel

Pending redeploy and container_restart actions are automatically moved to cancelled/ when:

• drift_resolved_auto — the service becomes healthy in actual state
• service_removed_from_desired_state — the service was removed from services.yaml or marked monitor: false

Only pending actions are auto-cancelled. Approved/running actions have been committed to by the operator and are never cancelled automatically.

Node Name Resolution

The supervisor supports a NODE_ALIAS_MAP environment variable (JSON string) to map event/world-state node names to canonical topology names:

NODE_ALIAS_MAP='{"node-2": "chelsty-infra", "node-1": "piha"}'

Action Approval Workflow

Supervisor writes → /opt/homelab/actions/pending/<id>.json
                 → Operator UI (port 18180) or Telegram Bot notifies
                 → Operator clicks Approve
                 → /opt/homelab/actions/approved/<id>.json
                 → Executor executes → completed / failed

Possible action states: pending → approved → running → completed / failed / rejected
Auto-cancel path: pending → cancelled/

Integration

piha agent-system webui (port 18180 on piha)

The agent-system-runtime-materializer on piha polls the VPS control-plane API every 10 seconds and mirrors world state to piha's local /opt/homelab/world/. This ensures the "Copy for AI" button in the piha webui (agent-system-webui) reflects the same clean state as the VPS API.

Override: hosts/piha/runtime/agent-system/docker-compose.override.yml — sets CONTROL_PLANE_URL=http://100.95.58.48:18180.

Nginx Proxy Manager

The operator UI at port 18180 can be proxied via NPM for external access. No WebSocket support required.

Log Locations

• Container logs: docker compose logs -f (from services/control-plane/)
• Runtime events: /opt/homelab/events/YYYY-MM-DD/
• World state: /opt/homelab/world/
• Action queue: /opt/homelab/actions/{pending,approved,running,completed,failed,cancelled}/