Home Assistant
Home Assistant runs on a dedicated machine and handles smart home control, automations, and integrations. The configuration is fully managed in a git repository.
Configuration structure
The main entry point is configuration.yaml, which loads all feature packages automatically:
Each file under packages/ is a self-contained feature area with its own automations, scripts, and entities:
| Package | Covers |
|---|---|
media.yaml | Entertainment state machine, Sonos, Music Assistant |
lighting.yaml | Adaptive lighting, Zigbee remote control |
adaptive_lighting.yaml | Adaptive Lighting integration configuration |
air_quality.yaml | CO2, PM2.5, VOC monitoring and alerts |
thermal_comfort.yaml | Per-room thermal comfort (apparent temperature, dew point) |
weather.yaml | Weather-derived template sensors — cloud cover, estimated illuminance |
sauna.yaml | Notifies phone and Sonos when the sauna RuuviTag passes 40 °C — see ESPHome |
routines.yaml | Wake-up and sleep routines |
climate.yaml | Heating schedules |
presence.yaml | Presence detection |
safety.yaml | Safety automations |
plants.yaml | Plant monitoring |
vacuum.yaml | Robot vacuum scheduling when away from home |
transport.yaml | HSL public transport departures via Digitransit GraphQL |
maintenance.yaml | Low-battery alerts and other upkeep reminders |
messaging.yaml | Notification channels — SMTP, mobile app, the shared notify_person script |
network.yaml | Wake-on-LAN switches for TV, NAS and kontti |
frontend.yaml | Lovelace dashboards and themes |
system.yaml | System-level configuration (logger, etc.) |
zigbee.yaml | Placeholder — Zigbee devices are managed through the ZHA UI |
Custom components
Custom components are managed via HACS:
| Component | Purpose |
|---|---|
| Adaptive Lighting | Dynamic brightness and colour temperature based on time of day |
| Better Thermostat | Improved thermostat control |
| FMI | Finnish Meteorological Institute weather integration |
| OpenPlantBook | Plant species database, used together with the Plant integration |
| Proxmox VE | Proxmox monitoring in HA |
| Spook | HA extensions and utilities |
| Spook Inverse | Companion to Spook with the opposite set of safety-rail behaviours |
| Thermal Comfort | Apparent temperature and dew-point sensors (used by thermal_comfort.yaml) |
| mass_queue | Custom Music Assistant queue management |
Key integrations
- Sonos — multi-room audio, controlled via Music Assistant
- Music Assistant — music server and playback control (runs as a HA add-on)
- ZHA — Zigbee coordinator for lights and remotes
- Matter — smart home protocol for compatible devices, including radiator thermostats
- ESPHome — air quality sensors
- MCP server — exposes HA to AI assistants via the Model Context Protocol
Observability
The Home Assistant host runs a Grafana Alloy agent that ships its systemd journal logs to Loki and system metrics to Prometheus on the monitoring server, so HA is covered by the same monitoring stack as the rest of the homelab.
Notable incidents
NVMe failure and a corrupt "latest" backup (2026-07-20)
The server's internal NVMe SSD failed. After replacing the drive, restoring from the most recent backup through the web UI failed repeatedly with a 500 Internal Server Error, surfaced by Supervisor as SupervisorBadRequestError.
The cause was the failed drive itself: it had already been degrading when the last scheduled backup was written, so the archive was truncated mid-write. The file looked plausible — around 550 MB — but the trailing backup.json metadata never made it to disk, and Supervisor rejected the upload as malformed. Inspecting it from a shell confirmed it:
$ tar -tf Automatic_backup_2026.7.2_2026-07-16_07.00_00004655.tar
homeassistant.tar.gz
a0d7b954_vscode.tar.gz
tar: invalid tar magic
Recovery was straightforward because the backups don't live only on the failing host: an older, intact archive was pulled from the Synology DS920+ and restored via Settings → System → Backups → Upload backup. HA came back cleanly on the older snapshot, losing only the few days between it and the corrupt one.
The lesson reinforced the backup strategy: retaining a history of backups off the host — not just the newest one, and not on the same drive being backed up — is what made recovery possible. A backup that only exists on the disk that's dying isn't a backup. The follow-up is to treat "backup ran" and "backup is restorable" as different facts, and to spot-check archive integrity rather than trusting file size alone.
My experience
Home Assistant has worked well. I've started using AI for automations and configuration, which has been helped by Home Assistant's recent investment in documentation — partly motivated by LLM training.
The most useful integrations in daily life have been:
- Adaptive Lighting — the best custom component I've installed. It genuinely improves comfort by adjusting brightness and colour temperature throughout the day.
- Apollo Air-1 sensors — great for tracking CO2 levels. Home Assistant alerts me when levels are high, so I know when to ventilate.
- Matter radiator thermostats — I have three, and they keep the apartment at a consistent temperature in winter. I also lower the bedroom temperature at night for better sleep.
- Plant sensors — I get a phone notification when a plant needs watering, via Bluetooth-proxying ESP32 devices.
Zigbee and Matter have both worked well. The ESP32 devices also serve as Bluetooth proxies for the plant sensors.