Linux companion agent

Home Assistant has companion apps for Android and iOS, and Windows has HASS.Agent. ha-linux-agent fills that role on Linux: a daemon that reports a machine’s state to Home Assistant and accepts commands from it.

It needs nothing installed on the Home Assistant side. It announces its entities through MQTT discovery, publishes all of its state as one retained document, and listens for commands on its own topics.

Backends

What a machine reports depends on which backends are enabled:

• generic: CPU, memory, battery, lock and idle state, suspend, notifications
• niri and kde: the compositor and desktop
• zfs, syncthing and headscale: pools, folders and the tailnet
• gamescope and lutris: what game is running
• launcher: systemd units as switches and selects
• hardware: backlight and CPU frequency

A backend is two small traits, one for sensors and one for commands. Each poll and each command runs with a five-second limit so that one slow backend cannot stall the rest.

There is deliberately no entity that runs an arbitrary shell command.

Staying up

A daemon like this is judged by whether it is still working in a month. The parts that took the most care:

• An MQTT client that reconnects is not a client that resubscribes: surviving a broker restart.
• sysinfo's refresh_all never forgets a process: a memory leak of 130 MB a day.
• Three ways Home Assistant MQTT discovery fails quietly: entities that silently never appear.

On shutdown it marks itself offline. It reconnects with a backoff of 1 to 60 seconds, reports readiness and a watchdog to systemd, and has a decommission mode that removes everything it ever published.

It installs as a NixOS module or a systemd unit. There is no release yet.