Home Lab Projects

Monitoring Your Services With Uptime Kuma and Home Assistant

Connect Uptime Kuma to Home Assistant to see monitor status, get alerts through two channels, and use push monitors to catch a stalled Home Assistant.

On this page
  1. What Uptime Kuma checks
  2. Choose where Kuma runs
  3. Connect Uptime Kuma to Home Assistant
  4. Build a status view
  5. Alert when a service goes down
  6. Send alerts from Uptime Kuma to Home Assistant
  7. Watch Home Assistant with a push monitor
  8. Certificate expiry and maintenance windows
  9. Public status pages
  10. Security
  11. Common mistakes

Uptime Kuma checks whether your websites and services respond. Home Assistant can show those results on dashboards and send alerts through your existing automations. The two work well together: Kuma watches your services, and Home Assistant can watch Kuma in return. This guide covers both directions, and where to run Kuma so that it can still raise an alarm when Home Assistant fails.

What Uptime Kuma checks

Uptime Kuma is a self-hosted monitoring tool by Louis Lam. It can check HTTP(S) endpoints, HTTP keyword and JSON responses, TCP ports, ping, DNS, Docker containers, MQTT and databases, among other types. The web interface runs on port 3001 by default. The official Docker image is louislam/uptime-kuma.

The default check interval is 60 seconds, and the minimum is 20 seconds. You can set retries before a monitor is marked down, which avoids alerts from a single failed check.

Ping alone is a weak test for a web service. A host can answer pings while the web app on it is broken. Use an HTTP check for web services, or an HTTP keyword check that confirms the page contains text you expect.

Choose where Kuma runs

Don’t run Uptime Kuma on the same machine as the services it watches, or on Home Assistant itself. If that machine fails, Kuma fails with it and can’t send an alert. Run it on a separate small machine, a Raspberry Pi or a VM on another host.

Keep Kuma’s SQLite database off NFS shares. The project’s docs warn that it can become corrupted there.

Connect Uptime Kuma to Home Assistant

The core Uptime Kuma integration gives Home Assistant a status entity for each monitor, along with response time and certificate expiry sensors. To set it up:

  1. In Uptime Kuma, go to Settings > API Keys and create a key. The integration needs a recent Uptime Kuma 2.x release, so check the Home Assistant integration page for the current minimum.
  2. In Home Assistant, go to Settings > Devices & services, select Add integration and choose Uptime Kuma.
  3. Enter the Uptime Kuma URL and the API key.

Older guides use a HACS integration instead. For a new setup, prefer the core integration.

Build a status view

Add monitor entities to a dashboard, as entity cards or a glance card, so each service’s state is visible at a glance. Community cards, such as the Uptime Card, can show history and colour-coded status if you want a richer view.

Alert when a service goes down

Create an automation with a state trigger on a monitor’s status entity, and choose the down state. Then call a notify action. Add a second alert channel too, such as ntfy, Telegram or email. An alert that goes through Home Assistant fails when Home Assistant is down, so the second channel is what reaches you in that case.

Send alerts from Uptime Kuma to Home Assistant

Uptime Kuma can also send alerts straight to Home Assistant. Choose the Home Assistant notification type and enter:

  • Your Home Assistant URL.
  • A long-lived access token. Create it in your Home Assistant profile under Security, and give it a clear name.
  • The notify service name, such as notify.mobile_app_your_phone.

This path depends on Home Assistant being up, so keep it alongside a second channel rather than using it alone.

Watch Home Assistant with a push monitor

Uptime Kuma can also notice when Home Assistant stops working. Create a push monitor in Kuma, which gives you a push URL. Then add an automation in Home Assistant that calls that URL every few minutes. Use a time pattern trigger, and a REST command that calls the push URL.

If Home Assistant stops running the automation, the pushes stop. Kuma then sends its alert through the notification channels you set for that monitor. Use a channel that doesn’t depend on Home Assistant.

Certificate expiry and maintenance windows

For HTTPS monitors, Kuma can alert you before a certificate expires, for example 7, 14 or 21 days ahead. Set maintenance windows for planned work, so the expected downtime doesn’t trigger alerts.

Public status pages

Kuma can publish a status page for a group of monitors, optionally on a custom domain. Publish only services you’re comfortable showing to the public.

Security

  • A Home Assistant long-lived token grants full API access. Create one for Kuma, store it only in Kuma’s settings, and revoke it if it leaks.
  • Kuma’s /metrics endpoint, used by Prometheus, is protected by an API key or basic authentication. Keep that protection on.
  • Don’t expose the Kuma interface to the internet without authentication. Use a VPN or a reverse proxy with TLS.

Common mistakes

  • Running Kuma on the host it monitors. A failure on that host also silences Kuma.
  • Relying on one alert channel. Add a second one that doesn’t depend on Home Assistant.
  • Using ping checks for web services. Use HTTP or keyword checks.
  • Storing the SQLite database on NFS. It can corrupt.

The complete guide to home lab projects

Self-Hosted Apps That Integrate With Home Assistant: Immich, Donetick and TeslaMate
Read the guide

Keep exploring

Guides from other topics

All topics →