Metrics & Hacompanion — Metrics Collection & Home Assistant Integration

Purpose

Comprehensive metrics collection and integration with Home Assistant via hacompanion.

Type null or one of "absolute_humidity", "apparent_power", "aqi", "area", "atmospheric_pressure", "battery", "blood_glucose_concentration", "carbon_dioxide", "carbon_monoxide", "current", "data_rate", "data_size", "date", "distance", "duration", "energy", "energy_distance", "energy_storage", "enum", "frequency", "gas", "humidity", "illuminance", "irradiance", "moisture", "monetary", "nitrogen_dioxide", "nitrogen_monoxide", "nitrous_oxide", "ozone", "ph", "pm1", "pm10", "pm25", "power", "power_factor", "precipitation", "precipitation_intensity", "pressure", "reactive_energy", "reactive_power", "signal_strength", "sound_pressure", "speed", "sulphur_dioxide", "temperature", "timestamp", "volatile_organic_compounds", "volatile_organic_compounds_parts", "voltage", "volume", "volume_flow_rate", "volume_storage", "water", "weight", "wind_direction", "wind_speed"

Default null


Type	null or one of "absolute_humidity", "apparent_power", "aqi", "area", "atmospheric_pressure", "battery", "blood_glucose_concentration", "carbon_dioxide", "carbon_monoxide", "current", "data_rate", "data_size", "date", "distance", "duration", "energy", "energy_distance", "energy_storage", "enum", "frequency", "gas", "humidity", "illuminance", "irradiance", "moisture", "monetary", "nitrogen_dioxide", "nitrogen_monoxide", "nitrous_oxide", "ozone", "ph", "pm1", "pm10", "pm25", "power", "power_factor", "precipitation", "precipitation_intensity", "pressure", "reactive_energy", "reactive_power", "signal_strength", "sound_pressure", "speed", "sulphur_dioxide", "temperature", "timestamp", "volatile_organic_compounds", "volatile_organic_compounds_parts", "voltage", "volume", "volume_flow_rate", "volume_storage", "water", "weight", "wind_direction", "wind_speed"
Default	`null`

The device class for the script in Home Assistant.

`services.metrics.hacompanion.script.<name>.icon`


Type	`string`
Default	`"mdi:script-text-outline"`

The icon to use for the script in Home Assistant.

`services.metrics.hacompanion.script.<name>.name`


Type	`string`

The name of the script as it will appear in Home Assistant.

`services.metrics.hacompanion.script.<name>.path`


Type	`absolute path`

The path to the script to execute.

`services.metrics.hacompanion.script.<name>.type`


Type	`one of "sensor", "switch"`
Default	`"sensor"`

The type of the script in Home Assistant.

`services.metrics.hacompanion.script.<name>.unit_of_measurement`


Type	`null or string`
Default	`null`

The unit of measurement for the script in Home Assistant.

`services.metrics.hacompanion.sensor.audio_volume.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the audio_volume sensor.

`services.metrics.hacompanion.sensor.companion_running.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the companion_running sensor.

`services.metrics.hacompanion.sensor.cpu_temp.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the cpu_temp sensor.

`services.metrics.hacompanion.sensor.cpu_usage.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the cpu_usage sensor.

`services.metrics.hacompanion.sensor.load_avg.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the load_avg sensor.

`services.metrics.hacompanion.sensor.memory.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the memory sensor.

`services.metrics.hacompanion.sensor.online_check.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the online_check sensor.

`services.metrics.hacompanion.sensor.power.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the power sensor.

`services.metrics.hacompanion.sensor.uptime.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the uptime sensor.

`services.metrics.hacompanion.sensor.webcam.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable the webcam sensor.

`services.metrics.hacompanion.storage`


Type	`attribute set of (submodule)`
Default	`{ }`

Storage devices and ZFS pools to monitor

`services.metrics.hacompanion.storage.<name>.name`


Type	`null or string`
Default	`null`

The pretty display name for this storage device in Home Assistant.

`services.metrics.hacompanion.storage.<name>.sensors.avail`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable available space sensor.

`services.metrics.hacompanion.storage.<name>.sensors.read`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable read speed sensor.

`services.metrics.hacompanion.storage.<name>.sensors.temperature`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable temperature sensor.

`services.metrics.hacompanion.storage.<name>.sensors.used`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable used space sensor.

`services.metrics.hacompanion.storage.<name>.sensors.write`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable write speed sensor.

`services.metrics.hacompanion.test`


Type	`anything`
Default	`hacompanionConfig`

This option has no description.

`services.metrics.upgradeStatus.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable Upgrade Status service.

`services.metrics.upgradeStatus.uptimeKuma.enable`


Type	`boolean`
Default	`false`
Example	`true`

Whether to enable Enable Uptime Kuma tracking for Upgrade Status.

Architecture / Services / Scope

hacompanion — Home Assistant companion daemon that publishes system sensors (CPU, memory, storage, uptime, and more) to Home Assistant. It uses a generated TOML configuration file and loads the Home Assistant API token from sops.secrets.HACOMPANION_ENV.
upgradeStatus — reports NixOS upgrade state (idle / running / failed / dirty). When upgradeStatus.uptimeKuma.enable is set, it also sends heartbeat notifications to Uptime Kuma on successful upgrades.

Secrets

HACOMPANION_ENV — Home Assistant API token, declared in hosts/secrets.yaml and consumed via EnvironmentFile.
UPGRADE_STATUS_ID — Uptime Kuma push monitor ID (host-level secrets.yaml), required when upgradeStatus.uptimeKuma.enable is set.

Operational Notes / Assumptions

Hacompanion runs as a DynamicUser with its state in /var/lib/hacompanion.
The upgradeStatus feature can integrate with Uptime Kuma to provide heartbeat notifications for successful system upgrades.

Usage Example

{ ... }: {
  services.metrics.hacompanion = {
    enable = true;
    sensor.cpu_temp.enable = true;
    sensor.memory.enable = true;
    storage.main = {
      name = "Main OS Drive";
      sensors.used = true;
    };
  };
}

References

Hacompanion GitHub Repository

RacciDev