homelab-codex-ws/services/stability-agent/README.md

Stability Agent

A lightweight filesystem-first watchdog and observer agent for CHELSTY.

Features

• Continuous Monitoring: Runs as a background service.
• Docker Inspection: Checks container status via read-only Docker socket.
• Disk Usage: Monitors local disk utilization.
• Tailscale Check: Verifies Tailscale availability.
• MQTT Reachability: Checks connectivity to the local MQTT broker.
• Zigbee2MQTT Monitoring: Specifically monitors the Zigbee2MQTT container.
• Event Logging: Writes append-only JSON events to /opt/homelab/events/YYYY-MM-DD/chelsty/.
• State Reporting: Writes heartbeat and status summary to /opt/homelab/state/.

Configuration

Environment variables:

• STABILITY_CHECK_INTERVAL: Interval between checks in seconds (default: 60).
• DISK_THRESHOLD_PCT: Disk usage percentage to trigger warning (default: 90).
• MQTT_HOST: Hostname or IP of the MQTT broker to check.
• MQTT_PORT: Port of the MQTT broker (default: 1883).

Safety

• No automatic restarts are performed.
• Read-only access to Docker socket.
• No configuration mutation.
• No secrets stored in the repository.

Event Schema

Events are written as JSON lines with the following fields:

• id: Unique event UUID.
• timestamp: ISO 8601 timestamp (UTC).
• node: chelsty.
• source: stability-agent.
• type: Type of event (e.g., disk_usage_high, containers_not_running).
• severity: info, warning, or error.
• message: Human-readable description.
• details: Object containing specific check results.