Watchtower – Home Assistant Integration

Custom integration for Home Assistant that talks directly to Watchtower's HTTP API - no MQTT bridge required. It creates one device per container Watchtower monitors (current image digest, whether an update is available, and an Install action), plus a "Watchtower" server device with check-all/update-all actions and diagnostics for the instance as a whole.

Source project

https://github.com/nicholas-fedor/watchtower

This integration depends on the nicholas-fedor/watchtower fork's HTTP API (/v1/containers/details, /v1/check, /v1/update, /v1/config, /v1/status, /v1/events) - it does not talk to Docker directly.

---

Installation

Installation via HACS

1. Add this repository as a custom repository to HACS:

2. Use HACS to install the integration.
3. Restart Home Assistant.
4. Set up the integration using the UI:

Manual Installation

1. Download the integration files from the GitHub repository.
2. Place the custom_components/watchtower folder in the custom_components directory of Home Assistant.
3. Restart Home Assistant.
4. Set up the integration using the UI:

Setup

1. Go to Settings → Devices & Services
2. Click "Add Integration"
3. Select Watchtower
4. Enter:
   • URL of your Watchtower instance (e.g. http://192.168.1.10:8080)
   • API token (WATCHTOWER_HTTP_API_TOKEN)
   • Events token (optional, WATCHTOWER_HTTP_API_EVENTS_TOKEN) - enables the Scanning/Updating sensors and prompt data refresh; safe to leave blank
   • Whether to verify the SSL certificate (only relevant for https:// URLs)

The URL, both tokens and SSL verification can be changed later from the integration's Reconfigure option, without needing to remove and re-add it. Data poll interval and automatic-check behavior are separate, changeable anytime from the integration's Configure option.

Requirements

• A running Watchtower instance (nicholas-fedor/watchtower image) with, at minimum:

  environment:
    - WATCHTOWER_HTTP_API_TOKEN=some-long-random-token
    - WATCHTOWER_HTTP_API_ENDPOINTS=health,metrics,update,containers,check,config,events
    # Optional, only needed for the Scanning/Updating sensors:
    - WATCHTOWER_HTTP_API_EVENTS_TOKEN=some-other-long-random-token

  That endpoint list is exactly what this integration uses - nothing more: health (readiness probe), metrics (also covers /v1/status), update, containers (covers /v1/containers/details), check, config, and events (optional - only needed for the Scanning/Updating sensors and the Events debug sensor; drop it and leave WATCHTOWER_HTTP_API_EVENTS_TOKEN unset if you don't want those). All must be reachable with the same WATCHTOWER_HTTP_API_TOKEN (events additionally accepts WATCHTOWER_HTTP_API_EVENTS_TOKEN).
• Home Assistant 2024.10 or newer (uses the config entry "Reconfigure" flow).

---

Devices & Entities

For every container Watchtower reports (via /v1/containers/details), it creates one device, automatically added when first seen and automatically removed if Watchtower stops reporting it (recreated from scratch if it later reappears):

• update.<container> - current image digest, whether a newer one is available, and an Install action that triggers a Watchtower update scoped to that container.
• button.<container>_check - "Check for update", scoped to that container (/v1/check).
• button.<container>_update - "Update", a plain-button alternative to the update entity's own Install action.
• Diagnostic entities (disabled by default, enable per-entity as needed): monitoring enabled, monitor-only, no-pull, image digest. "Running" is enabled by default.

One "Watchtower" server device holds:

• Check all / Update all buttons (unscoped /v1/check and /v1/update).
• A Configuration diagnostic sensor (Watchtower's active settings).
• Five diagnostic sensors from the most recent scan summary: scanned, updated, failed, restarted, skipped.
• A Connectivity binary sensor.
• Scanning / Updating binary sensors, driven by /v1/events - reflect whether Watchtower is currently looking for updates or applying one (only active if an events token is configured).
• An Events debug sensor showing the raw state of the /v1/events stream (connection status, last received event) - see "Notes" below.

Features

• Dynamic device creation and cleanup - containers added later get a device automatically, and devices for containers that disappear are removed automatically.
• Two independently configurable intervals: a cheap data poll (seconds) that just re-reads current state, and an optional automatic check (minutes, off by default) that actually queries the image registry via Watchtower.
• When an events token is configured, scan_completed/update_completed/ update_failed events trigger an immediate data refresh instead of waiting for the next scheduled poll, and drive the Scanning/Updating sensors in real time.
• Full configuration and reconfiguration from the UI, including connection settings and poll/check intervals, without removing and re-adding the integration.
• English and Czech translations.

Notes

• Watchtower's /v1/check matches its container filter by exact name, while /v1/update's container filter is a Go regular expression - the integration handles this difference internally.
• update_available / the latest digest are only known once a check has run (manually, or via the auto-check schedule); until then, entities show as up to date.
• /v1/events support depends on your Watchtower version - scan_started/scan_completed/update_started/update_completed/ update_failed need a reasonably recent build to fire for both check-only and update runs. The Events debug sensor is there specifically to verify what your instance actually sends.
• Since Watchtower's update events aren't scoped to a specific container, an update entity's in_progress state clears when any update finishes, not necessarily the one it triggered.

---

Support

If you find this integration useful, you can support the development:

---

License

This project is licensed under the MIT License.

Copyright (c) 2026 metaathron

You are free to use, modify, and distribute this software in accordance with the MIT License.

If you find this project useful, attribution and a link back to the original repository are appreciated: https://github.com/metaathron/ha-watchtower