Skip to main content
Version: Next 🚧

Home Assistant (MQTT Auto-Discovery)

The Home Assistant MQTT integration provides native Update entities, device topology, and one-click container installations.

🏠 Home Assistant Integration​

WUD integrates deeply with Home Assistant via MQTT Auto-Discovery. This is the recommended and most feature-rich way to connect WUD to Home Assistant.

services:
  whatsupdocker:
    image: getwud/wud
    environment:
      - WUD_TRIGGER_MQTT_HASS_URL=mqtt://homeassistant.local:1883
      - WUD_TRIGGER_MQTT_HASS_HASS_ENABLED=true
      - WUD_TRIGGER_MQTT_HASS_HASS_DISCOVERY=true

🔄 Update Entity & One-Click Install​

Containers are exposed in Home Assistant as native update entities (e.g. update.wud_local_my_container):

  • Installed Version: Displays the current image tag (or digest).
  • Latest Version: Displays the available update tag (or truncated digest for digest-based updates).
  • Update Action ("Install" button): When clicking Install on an update entity in Home Assistant, an MQTT command is sent to WUD via command_topic ({topic}/{watcher}/{container}/install with payload INSTALL).
  • In-Progress State: WUD sets in_progress: true while the update runs, triggers your configured update triggers (such as docker or docker-compose), and resets in_progress: false once completed.
Requirements for One-Click Install

To enable the Install button to perform container updates, make sure you have configured an update trigger such as:

📦 Device Topology (Per-Watcher Devices)​

To keep Home Assistant devices organized and clean:

  • Watcher Devices: Each watcher gets its own dedicated device (e.g. wud (local) for a watcher named local). All containers monitored by this watcher are grouped under this device.
  • Global WUD Device: Represents the core WUD service, providing connection status (binary_sensor), total container count (sensor), total update count (sensor), and global update status (binary_sensor).
Migrating from Previous Versions

When upgrading to this version, if the legacy monolithic wud device already exists in Home Assistant, it is recommended to delete it from the Home Assistant UI (Settings > Devices & services > MQTT > wud device > Delete). Home Assistant will then cleanly rediscover the new per-watcher devices (wud_<watcher>) alongside the global wud device without orphan entities or duplicates.

🔐 MQTT Permissions & Broker ACLs​

When using an MQTT broker with Access Control Lists (ACLs) enabled (e.g. Mosquitto):

  • Read & Write on WUD Topics: WUD requires both publish and subscribe permissions on {topic}/# (by default wud/container/#) to publish container states and listen for install commands on {topic}/+/+/install.
  • Write on Discovery Topics: WUD needs publish permissions on {prefix}/# (by default homeassistant/#) to register entities via auto-discovery and publish empty retained tombstones when containers are removed.

⚙️ Configuration Variables​

The Home Assistant integration uses the underlying MQTT trigger. You can use all MQTT generic configuration options.

Here are the variables specifically relevant to Home Assistant:

WUD_TRIGGER_MQTT_{trigger_name}_HASS_DEVICEID
Optionalstringdefault: wud

Device identifier in Home Assistant

WUD_TRIGGER_MQTT_{trigger_name}_HASS_DEVICENAME
Optionalstringdefault: wud

Device display name in Home Assistant

WUD_TRIGGER_MQTT_{trigger_name}_HASS_DISCOVERY
Optionalbooleandefault: false

Enable Home Assistant MQTT Auto-Discovery

WUD_TRIGGER_MQTT_{trigger_name}_HASS_ENABLED
Optionalbooleandefault: false

Enable Home Assistant integration and publish state updates

WUD_TRIGGER_MQTT_{trigger_name}_HASS_PREFIX
Optionalstringdefault: homeassistant

MQTT discovery prefix topic for Home Assistant

Customizing Entity Names & Icons in Home Assistant

You can customize how containers display in Home Assistant using the wud.display.name and wud.display.icon labels.