How to monitor Uptime Kuma from outside
Monitor Uptime Kuma from outside with a heartbeat: point a Kuma HTTP monitor (or a cron job on the same machine) at a Vigil heartbeat URL every minute. While Kuma runs, the pings arrive; when Kuma, its server or your internet connection stops, the pings stop and Vigil alerts you. It fits on Vigil's free plan.
What can go wrong with Uptime Kuma from outside
- The box goes down. Power cut, kernel panic, a full disk or a stopped Docker daemon takes Kuma down with everything it watches, and Kuma cannot notify you about its own death.
- The connection goes down. A homelab on a home connection loses its uplink or its public IP changes; every service is unreachable from outside, yet Kuma, inside, sees them all as up and has no route to send alerts.
- Kuma itself hangs. The Node process stops scheduling checks (a stuck SQLite database at a few hundred monitors is the usual report) while the container still shows as running.
- Notifications break silently. A Telegram bot token is revoked or an SMTP password changes; checks fail, but no alert leaves the box.
- Upgrades. A major-version database migration keeps Kuma offline for longer than planned, with nothing watching in the meantime.
The signals that matter, with alert thresholds
| Signal | Alert when | Why it matters |
|---|---|---|
| Heartbeat from Kuma | no ping within period + grace | Kuma, its host or its connection stopped. |
| Public status page or reverse proxy | non-2xx or TLS error from outside | Visitors cannot reach it even if the box is up. |
| TLS certificate of the Kuma domain | fewer than 14 days left | Automatic renewal failed. |
| Kuma database size (by hand) | growing fast, or past a few hundred MB | Prune heartbeat history before it slows down. |
Thresholds are starting points. Tune them after a week of data: an alert nobody acts on should be raised or removed.
How to check Uptime Kuma from outside by hand
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}}'
docker logs uptime-kuma --since 1h 2>&1 | grep -iE 'error|sqlite|timeout' | tail -20
curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' http://127.0.0.1:3001/
du -sh /var/lib/docker/volumes/uptime-kuma/_data/kuma.db
Container and volume names above are the defaults from Kuma's docker run example; adjust them to yours.
How to watch Uptime Kuma from outside with Vigil
- In New monitor create a Heartbeat named "Uptime Kuma". Set the period to 1 minute and a grace of 5 minutes, so one missed ping during a restart does not page you. Copy its ping URL, https://puzaricloud.in/ping/<token>.
- In Uptime Kuma, add a monitor of type HTTP(s) with that ping URL, a heartbeat interval of 60 seconds and 0 retries. Every successful Kuma check now pings Vigil; Vigil accepts GET, POST and HEAD and needs no API key.
- No Kuma UI access, or want to prove Kuma answers and not just the network? Use cron on the same host instead:
* * * * * curl -fsS -m 10 -o /dev/null http://127.0.0.1:3001/ && curl -fsS -m 10 --retry 2 https://puzaricloud.in/ping/<token>. The ping is sent only when Kuma answered locally. - Add an alert channel that does not run through the homelab: Telegram, Discord, Slack, WhatsApp or email from Vigil reach your phone even when your network is down.
- If your Kuma status page is published, add an uptime monitor for its public URL in New monitor too. It catches a broken reverse proxy, DNS or certificate that the heartbeat cannot see; certificate expiry is checked on the same monitor.
- Planned upgrade? Create a maintenance window for the heartbeat first, so the migration does not wake you.
Every alert goes to the channels you pick: email, Slack, Telegram, Discord, Microsoft Teams, Pushover, webhooks or on-call paging. Failures are confirmed by a second check before anyone is woken up.
Uptime Kuma from outside monitoring FAQ
Why not let Uptime Kuma watch itself?
A monitor cannot report its own death: when the process, the server or the uplink stops, nothing is left to send the alert. The watcher has to run somewhere else, and a heartbeat (dead man's switch) is the simplest way to do that.
Is this free?
Yes. Vigil's free plan has 20 monitors, and heartbeats can use a 1-minute period on it. The Kuma heartbeat plus a public status-page check uses two of them, with commercial use allowed.
Will I get an alert when my home internet is down?
Yes, that is the point: the pings stop arriving, so after the grace period Vigil alerts you through its own channels, which do not depend on your network. When the connection returns, the next ping resolves the incident.
I have hundreds of monitors in Kuma. Should I move them?
Only if Kuma is causing you trouble. If it is slowing down or you need more than one login, see switching from Uptime Kuma: the importer reads a Kuma backup JSON in one step.