In short

Problem: A container that quietly stops, a disk that fills up, a service that answers with the wrong page: on a home server you usually find out when someone in the family says “it doesn’t work”.

Solution: Home Assistant watches the Docker host the same way it watches the rest of the house: one entity per container, host metrics, HTTP checks from the outside, backup status, and a handful of automations that send a Telegram message when something is wrong.

Tested with: Home Assistant 2026.10, the Portainer integration, my own SSH Linux Management add-on (MQTT), about 25 containers on one Docker host, Telegram and the Companion app for notifications

Home Assistant already knows how to tell me when a window is open or a battery is low. So instead of running a separate monitoring stack for my server, I let Home Assistant watch that too. Everything ends up in the same place: one dashboard, one notification channel, and automations I already know how to write. This article shows the two integrations I use to get the Docker host into Home Assistant, the alerts built on top of them, and what I learned along the way.

1. Two integrations, two jobs

Home Assistant runs in a VM, the containers on the host next to it. To see inside the host, I use two integrations, because each one is good at something different:

For the alerts below I use the Portainer status sensors for containers and the SSH add-on for everything about the host. If you only want one, start with Portainer: it’s a built-in integration and gives you the most per container.

2. The Portainer integration

If Portainer already runs on your Docker host, this is the quickest start:

1. In Portainer, open your user profile → Access tokens → Add access token, and copy the token.
2. In Home Assistant: Settings → Devices & services → Add integration → Portainer, enter Portainer’s URL and the token.
3. Home Assistant creates one device per container, with entities like binary_sensor.<container>_status, sensor.<container>_memory_usage, sensor.<container>_restart_count and update.<container>_image_update_available.

One thing Portainer doesn’t do: when you delete a container, its device stays in Home Assistant as “unavailable”. Remove it by hand (Settings → Devices, the device, Delete), or your dashboards and automations slowly fill with dead entities.

3. The SSH add-on: host metrics without root

For the host itself (disk, CPU, RAM, VMs) I wrote a small Home Assistant add-on, SSH Linux Management. It opens one outbound SSH connection to the host and publishes what it finds through MQTT discovery, so the entities appear in Home Assistant without any YAML:

• Docker: the remote Docker socket is forwarded through the SSH connection. No Docker TCP port is opened, and container changes arrive instantly through Docker’s event stream.
• Host metrics: CPU, memory and disk use per mount point (I watch / and the Nextcloud data disk).
• VMs: libvirt VMs as switches with a reboot button, through virsh over the same connection.
• The SSH account is not root: it’s a normal user in the docker (and libvirt) group, and the host key is pinned on the first connection.

A lesson from running it: the first versions named each Docker entity after the container’s ID. Every docker compose up after an update creates a new container with a new ID, so Home Assistant got a new entity each time, and after a few weeks I had switch.…_traefik, …_traefik_2 up to …_traefik_5. Version 0.11.0 keys the entities on the container name and removes discovery entries for containers that are gone. If you write your own MQTT discovery: choose the unique_id from something that survives a recreate.

4. Alert: a container stopped

The most important automation is also the simplest: if any container’s status sensor is off for two minutes, send a message that names it. The two minutes keep normal restarts (updates, a recreate) from sending false alarms:

alias: System - Docker - Container Down Alert
description: A watched container is not running for 2 minutes → Telegram + push.
mode: parallel
max: 10
triggers:
  - trigger: state
    entity_id:
      - binary_sensor.traefik_status
      - binary_sensor.crowdsec_status
      - binary_sensor.authentik_server_status
      - binary_sensor.nextcloud_nextcloud_1_status
      - binary_sensor.vaultwarden_status
      - binary_sensor.zigbee2mqtt_status
      # … one line per container you care about
    to: "off"
    for:
      minutes: 2
actions:
  - action: telegram_bot.send_message
    data:
      title: "🔴 Docker container down"
      message: "{{ trigger.to_state.attributes.friendly_name }} has not been running for 2 minutes."
  - action: notify.mobile_app_your_phone
    data:
      title: "🔴 Docker container down"
      message: "{{ trigger.to_state.attributes.friendly_name }} has not been running for 2 minutes."

• mode: parallel: if Docker itself restarts, several containers stop at once. Each one should get its own message, not just the first.
• to: "off", not “not on”: a sensor that turns unavailable (Portainer unreachable, container deleted) doesn’t fire. That’s on purpose: it prevents a flood of alerts when Portainer restarts, but it also means a deleted container is silently dropped from monitoring.

5. Running isn’t the same as working: HTTP checks

A container can be “running” while the service inside answers with an error page, or while the reverse proxy in front of it sends traffic nowhere. So every ten minutes Home Assistant also calls the public addresses, the way a visitor would, and checks the HTTP status code. The calls are shell_command entries in configuration.yaml:

shell_command:
  curl_check_nextcloud: "curl -s -o /dev/null -w '%{http_code}' --max-time 10 https://cloud.example.com/status.php"
  curl_check_traefik: "curl -s -o /dev/null -w '%{http_code}' --max-time 10 https://traefik.example.com/dashboard/"

The automation runs each command, reads the status code from the response, and compares it with what that service should answer:

triggers:
  - trigger: time_pattern
    minutes: "/10"
actions:
  - action: shell_command.curl_check_traefik
    response_variable: traefik
  - if:
      - condition: template
        value_template: "{{ traefik.stdout not in ['302', '401'] }}"
    then:
      - action: telegram_bot.send_message
        data:
          title: "🔴 Traefik dashboard check failed"
          message: "Expected a login (302/401), got {{ traefik.stdout }}."

• Check for the right answer, not just any answer. My Traefik dashboard and wiki sit behind single sign-on, so they must answer with a redirect to the login (302) or 401. A 200 would mean they’re suddenly open to everyone. The check catches a broken login, not just a broken service.
• Plan for maintenance. My nightly Nextcloud backup puts it into maintenance mode, which answers with 503. Between 02:55 and 04:30 the automation ignores exactly that code for Nextcloud, and only that one.

6. Disk space and the host

A full disk is the classic reason for a whole server to fail at once: databases stop writing, containers crash, logs can’t be written to explain why. The SSH add-on’s disk sensors make this a two-line trigger:

triggers:
  - trigger: numeric_state
    entity_id:
      - sensor.ssh_host_myserver_host_disk_use
      - sensor.ssh_host_myserver_host_disk_use_data
    above: 85
actions:
  - action: telegram_bot.send_message
    data:
      message: "⚠️ {{ trigger.to_state.attributes.friendly_name }} is at {{ trigger.to_state.state }} % used."

85 % gives me days, not minutes, to react. The same sensors go on the dashboard as gauges, next to CPU and memory.

7. Backups and updates

• Backups: a script on the host writes the state of every backup job into a JSON file every five minutes. The SSH add-on reads that file and creates a sensor per job plus one “backup problem” binary sensor. If that is on for ten minutes (a job failed, a snapshot is older than 26 hours, the backup disk isn’t mounted), I get a message with the reason. The details are in my backup article.
• Updates: an automation runs my Docker update script over SSH three times a week at 04:00 (docker compose pull and up -d per stack). The container alert above is the safety net: if an update breaks a container, I know before breakfast. For the reverse proxy, a pinned major version keeps that risk small (see my Traefik article).
• Version changes: for Zigbee2MQTT I also store the last known version in an input_text helper and send a message when it changes, with a reminder to read the release notes. I added it after an update changed how some devices behaved and I only noticed days later.

8. The dashboard

A “Server” view on my main dashboard shows the host gauges (CPU, RAM, both disks), the backup status, and one tile per container. Each tile shows whether the container runs, and tapping its icon restarts it:

type: tile
entity: switch.ssh_host_myserver_docker_vaultwarden
name: Vaultwarden
icon: mdi:restart
icon_tap_action:
  action: perform-action
  perform_action: button.press
  target:
    entity_id: button.ssh_host_myserver_docker_vaultwarden_restart

It’s not meant for daily use. It’s the page I open when a message arrives, to see at a glance whether one container is down or the whole host has a problem, and to restart the obvious candidate from my phone.

What I learned

• One place for alerts. I read Telegram anyway. A separate monitoring system with its own app would be one more thing I ignore.
• Check from the outside, too. “Container running” and “service works for a visitor” are two different questions. A container can run perfectly while its login is broken or the proxy points elsewhere.
• Check the expected answer. A login page that suddenly answers 200 is a security problem, not a success.
• Give every alert a short delay. Two minutes for containers, ten for backups: real problems stay, restarts don’t wake you up.
• Clean up after removing a container. Delete its device, take it out of the alert list and the dashboard. Dead entities make a dashboard you stop trusting.

In short

Problem: Radiator thermostats measure the temperature right next to the hot radiator, a shared blueprint stopped reacting, and an update silently broke the heating.

Solution: Three small automations per room (Toggle, Target Sync, Calibration), a real room sensor fed into every valve, and a few safety nets that tell me when something drifts.

Tested with: Home Assistant, Zigbee2MQTT 2.14, 12 SONOFF TRVZB radiator valves, Zigbee temperature and motion sensors

Our house has nine heated rooms with twelve smart radiator valves. The goal was simple: warm when someone is in the room, a few degrees less when not, and no heating with the window open. Getting there took a few rebuilds. This is the setup that works now, and the problems we hit on the way.

The building blocks per room

Every room uses the same set of helpers. That makes the automations almost identical, and a new room is mostly copy and rename.

On top of that, each room has three automations:

• Toggle follows the master switch and turns the valve and the Target Sync on or off.
• Target Sync decides between Comfort and ECO and writes the target to the valve.
• Calibration feeds the real room temperature into the valve.

Why I dropped the blueprint

At first all rooms ran on one shared heating blueprint. It was convenient until it wasn’t: at the end of August it simply stopped reacting to some inputs, because an internal guard condition failed. One bug in a shared blueprint means every room is affected at once, and the logic is hard to debug from the outside.

I replaced it with three plain automations per room. That is more automations (33 for the whole house), but each one is short, does one thing, and shows up clearly in the trace when something goes wrong.

1. Toggle

When the master switch goes on, the valve is set to heat, the Target Sync is enabled and run once, so the right temperature is applied immediately. When it goes off, the Target Sync is disabled first, then the valve is switched off.

alias: Office - Heating - Toggle
triggers:
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "on"
    id: turned_on
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "off"
    id: turned_off
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: turned_on
        sequence:
          - action: climate.set_hvac_mode
            target:
              entity_id: climate.office_heating_valve
            data:
              hvac_mode: heat
          - action: automation.turn_on
            target:
              entity_id: automation.office_heating_target_sync
          - action: automation.trigger
            target:
              entity_id: automation.office_heating_target_sync
      - conditions:
          - condition: trigger
            id: turned_off
        sequence:
          - action: automation.turn_off
            target:
              entity_id: automation.office_heating_target_sync
          - action: climate.set_hvac_mode
            target:
              entity_id: climate.office_heating_valve
            data:
              hvac_mode: "off"
mode: single

2. Target Sync

The Target Sync is where the rooms differ. In the office it follows a motion sensor: Comfort after two minutes of motion, ECO after ten minutes without. The delays stop the heating from jumping up and down when someone just walks through.

alias: Office - Heating - Target Sync
triggers:
  - trigger: state
    entity_id: binary_sensor.office_motion
    to: "on"
    for: { minutes: 2 }
  - trigger: state
    entity_id: binary_sensor.office_motion
    to: "off"
    for: { minutes: 10 }
  - trigger: state
    entity_id:
      - input_number.temperature_comfort_office
      - input_number.temperature_eco_office
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "on"
conditions:
  - condition: state
    entity_id: input_boolean.heating_office_on
    state: "on"
actions:
  - if:
      - condition: state
        entity_id: binary_sensor.office_motion
        state: "on"
    then:
      - action: climate.set_temperature
        target:
          entity_id: climate.office_heating_valve
        data:
          temperature: "{{ states('input_number.temperature_comfort_office') | float }}"
    else:
      - action: climate.set_temperature
        target:
          entity_id: climate.office_heating_valve
        data:
          temperature: "{{ states('input_number.temperature_eco_office') | float }}"
mode: restart

Other rooms use other signals with the same pattern:

• Schedule only (kitchen, bedroom, bathroom): Comfort inside the schedule, ECO outside it.
• Schedule and presence (rooms that belong to one person): Comfort only if the schedule is on and that person is at home.
• A device as presence: in the gaming room the AV receiver is the best sign that someone is there. Receiver on means Comfort, receiver off means a lower setback.

3. Calibration: the part that matters most

A radiator thermostat measures the temperature where it sits: right next to the hot radiator. So it thinks the room is warm long before it is, and closes too early.

The SONOFF TRVZB can use an external temperature instead. In Zigbee2MQTT it has two relevant entities:

• a select “Temperature sensor”: local_temperature (its own sensor) or remote_temperature (an external value)
• a number “External temperature input” that receives the external value

The Calibration automation copies a real room sensor into that input whenever the reading has been stable for two minutes. It also checks the select, because after a reconnect or a battery change the valve sometimes falls back to its own sensor.

alias: Office - Climate - Calibration
triggers:
  - trigger: state
    entity_id: sensor.office_temperature
    for: { minutes: 2 }
  - trigger: state
    entity_id: select.office_heating_valve_temperature_sensor_select
    not_to:
      - remote_temperature
      - remote_source_offline
      - unavailable
      - unknown
conditions:
  - condition: numeric_state
    entity_id: sensor.office_temperature
    above: 0
actions:
  # switch the valve back to the external sensor if it reverted
  - if:
      - condition: not
        conditions:
          - condition: state
            entity_id: select.office_heating_valve_temperature_sensor_select
            state:
              - remote_temperature
              - remote_source_offline
    then:
      - action: select.select_option
        target:
          entity_id: select.office_heating_valve_temperature_sensor_select
        data:
          option: remote_temperature
        continue_on_error: true
  # feed the real room temperature into the valve
  - action: number.set_value
    target:
      entity_id: number.office_heating_valve_external_temperature_input
    data:
      value: "{{ states('sensor.office_temperature') | float }}"
mode: single

The condition above: 0 keeps a sensor that reports 0 or nothing from cooling the house down. With the calibration in place, the room finally reaches the temperature it shows on the dashboard.

4. No heating with the door open

The living room has a terrace door and two windows, and the heating kept running when they were open. The pause automation switches the three valves off after a door or window has been open for one minute, and switches them back on when all of them are closed again.

The important detail: it does not touch the master switch. Instead it sets its own flag (input_boolean.heating_living_room_paused). Toggle and Target Sync leave the valves alone while the flag is on. Because the flag is a helper and not a wait in the automation, it also survives a Home Assistant restart. A start trigger restores the heating if everything was closed while Home Assistant was down.

triggers:
  - trigger: state
    entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
    to: "on"
    for: { minutes: 1 }
    id: opened
  - trigger: state
    entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
    from: "on"
    to: "off"
    id: closed
  - trigger: homeassistant
    event: start
    id: ha_start
actions:
  - choose:
      - conditions:   # opened while heating is on -> pause
          - condition: trigger
            id: opened
          - condition: state
            entity_id: input_boolean.heating_living_room_on
            state: "on"
        sequence:
          - action: input_boolean.turn_on
            target: { entity_id: input_boolean.heating_living_room_paused }
          - action: climate.set_hvac_mode
            target: { entity_id: [climate.living_room_heating_1, climate.living_room_heating_2, climate.living_room_heating_3] }
            data: { hvac_mode: "off" }
      - conditions:   # all closed and paused by us -> resume
          - condition: trigger
            id: [closed, ha_start]
          - condition: state
            entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
            state: "off"
          - condition: state
            entity_id: input_boolean.heating_living_room_paused
            state: "on"
        sequence:
          - action: input_boolean.turn_off
            target: { entity_id: input_boolean.heating_living_room_paused }
          - if:
              - condition: state
                entity_id: input_boolean.heating_living_room_on
                state: "on"
            then:
              - action: climate.set_hvac_mode
                target: { entity_id: [climate.living_room_heating_1, climate.living_room_heating_2, climate.living_room_heating_3] }
                data: { hvac_mode: heat }
              - action: automation.trigger
                target: { entity_id: automation.living_room_heating_target_sync }
mode: queued

5. Safety nets

Automations fail quietly. These three make sure I hear about it:

• Child lock enforcement: after a battery change or a re-pair, a valve’s child lock can be off, and then anyone can turn the knob. If any of the twelve locks is off for 10 seconds, or Home Assistant starts, all locks are switched on again.
• Target mismatch alert: 10 minutes after a valve’s target or a Comfort/ECO value changes, a template checks every valve. If a target matches neither its room’s ECO nor its Comfort value (tolerance 0.25 °C), I get a Telegram message. Rooms with heating off, valves that are off and the paused living room are skipped. This catches a Target Sync that didn’t reach the valve.
• Zigbee2MQTT version alert: a message whenever Zigbee2MQTT runs a new version. The reason is the next section.

The core of the mismatch check, simplified to one valve:

{% set target  = state_attr('climate.office_heating_valve', 'temperature') | float %}
{% set eco     = states('input_number.temperature_eco_office') | float %}
{% set comfort = states('input_number.temperature_comfort_office') | float %}
{{ (target - eco) | abs > 0.25 and (target - comfort) | abs > 0.25 }}

The issues we had

What I learned

• Small, boring automations per room beat one clever shared blueprint. They are easier to read, test and fix.
• A radiator thermostat without an external sensor heats to the wrong temperature. Feeding it a real room sensor is worth the extra automation.
• Use a flag helper instead of a wait for anything that must survive a restart.
• Every automation that can fail silently needs an alert that checks the result, not just the trigger.

In short

Problem: Run Zigbee2MQTT in Docker for about 80 devices, and battery sensors that keep showing as offline.

Solution: A small Docker Compose file, a clean configuration.yaml, and understanding why “offline” often doesn’t mean “gone”.

Tested with: Zigbee2MQTT 2.14, TI CC2652 USB coordinator (Z-Stack), Home Assistant, Mosquitto

My Zigbee network has grown to around 80 devices: radiator thermostats, temperature and motion sensors, door contacts, plugs and a lot of smart bulbs. Zigbee2MQTT connects all of them to Home Assistant through MQTT. Here is the setup I use, and the one problem that kept bugging me.

1. Docker Compose

Zigbee2MQTT runs as a single container. The USB stick is passed in by its by-id path, so it still works when USB devices are enumerated in a different order after a reboot.

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    environment:
      TZ: Europe/Berlin
      ZIGBEE2MQTT_CONFIG_FRONTEND_ENABLED: "true"
      ZIGBEE2MQTT_CONFIG_FRONTEND_PORT: "8080"
      # the frontend password lives in .env, not in this file
      ZIGBEE2MQTT_CONFIG_FRONTEND_AUTH_TOKEN: ${Z2M_AUTH_TOKEN:?set Z2M_AUTH_TOKEN in .env}
    volumes:
      - ./:/app/data
      - /run/udev:/run/udev:ro
    devices:
      # find yours with: ls -l /dev/serial/by-id/
      - /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0:/dev/ttyUSB0
    ports:
      # frontend only on the host itself
      - "127.0.0.1:8080:8080"

2. configuration.yaml

This is my configuration with all secrets removed. On a new installation, GENERATE lets Zigbee2MQTT create a random network key and PAN IDs on the first start. Never copy these values from someone else’s example.

version: 5
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mqtt-broker:1883
  user: zigbee2mqtt
  password: '!secret mqtt_password'
serial:
  port: /dev/ttyUSB0
  adapter: zstack
  baudrate: 115200
  rtscts: false
advanced:
  channel: 15
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE
  transmit_power: 20
  adapter_delay: 100
  last_seen: ISO_8601
  log_level: error
availability:
  enabled: true
homeassistant:
  enabled: true
frontend:
  enabled: true
  port: 8080

A few notes on the settings:

• channel: pick it once and don’t change it later. Changing the channel means re-pairing many devices. Zigbee channels 15, 20 and 25 overlap least with the common Wi-Fi channels 1, 6 and 11.
• last_seen: ISO_8601: adds a timestamp to every device. You need this to understand the offline problem below.
• availability: marks devices as online or offline in Home Assistant. Useful, but it causes most of the confusion described next.
• password: '!secret mqtt_password' reads the value from a separate secret.yaml, so the configuration can be shared or backed up without the password.

3. Sensors that keep leaving the network

This is the part that kept bugging me. Every few days some battery sensors, mostly door and window contacts, show up as offline in Zigbee2MQTT and Home Assistant. So far the fix has always been the same: open and close the door once, and the sensor is back online immediately. No re-pairing, no battery change.

That a simple open and close brings them back is actually a good clue. There are two likely explanations, and they can both happen in the same network.

Reason 1: the sensor never left, it was just quiet

Battery devices sleep most of the time and only send something when their state changes or at a long check-in interval. Zigbee2MQTT cannot ask them “are you still there?”. With availability turned on, it simply waits: if a battery device has sent nothing for 25 hours (the default), it is marked offline. A door that nobody opened for a day looks exactly like a dead sensor. Opening it sends a message, and the sensor is “back”.

You can recognise this case by the last seen time: if the sensor went offline almost exactly 25 hours after it was last seen, it is the timeout and not a real problem. The fix is a longer timeout for these devices:

availability:
  enabled: true
  active:
    timeout: 10       # minutes, mains-powered devices (they can be pinged)
  passive:
    timeout: 1500     # minutes, battery devices (default = 25 hours)

# or only for single devices, in the devices section:
devices:
  '0x00158d0001234567':
    friendly_name: Front door
    availability:
      timeout: 4320   # 3 days

Reason 2: the sensor lost its parent router

Battery devices don’t talk to the coordinator directly. They attach to a nearby router, which is any mains-powered device such as a plug or a smart bulb. If that router disappears, the sensor is orphaned. It only notices when it tries to send something, and then looks for a new parent. That is why opening the door “repairs” it: the open event forces the sensor to rejoin.

Typical reasons a router disappears or drops its children:

• Smart bulbs switched off at the wall. Every bulb is a router. Switch it off and every sensor attached to it is orphaned. This is the most common cause.
• Weak routers. Many cheap bulbs and plugs can only keep a few children, or drop them after a firmware glitch.
• Aqara/Xiaomi sensors. They don’t follow the Zigbee standard completely and often only stay connected to certain routers. With other brands as parents they drop off regularly.

What I’m doing about it

1. Check the last seen time of each sensor that goes offline, to separate the timeout from real drop-outs.
2. Raise the availability timeout for door and window contacts. They don’t need to report every day.
3. Keep bulbs that act as routers powered all the time and switch them through Zigbee instead of the wall switch.
4. Add a dedicated, always-on router (a USB router stick or a good smart plug) near the sensors that drop most often.
5. Look at the network map in the Zigbee2MQTT frontend to see which router each problem sensor hangs on.

What I learned

• “Offline” in Zigbee2MQTT often just means “hasn’t said anything for 25 hours”.
• The routers decide how stable the network is, not the coordinator. Bulbs on wall switches are bad routers.
• Back up the network key and coordinator backup. They are the difference between swapping a stick in minutes and re-pairing 80 devices.

I’ll update this article once I know which of the two reasons applies to my sensors.