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:
- 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.
- In Home Assistant, go to Settings > Devices & services, select Add integration and choose Uptime Kuma.
- 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
/metricsendpoint, 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.