On 7 October I moved Uptime Kuma onto my ZimaBlade. While I was repointing everything at it, I noticed something a bit embarrassing: nothing had ever added a monitor automatically. Kuma watched exactly what I'd remembered to click into it, and nothing else. Every new container was unwatched until I happened to think of it.

So I wrote a small script that compares what's actually running with what Kuma is watching. Its first run found 18 services and 5 gaps. I approved all 5. Today I've cleaned it up and published it as kuma-discover.

kuma-discover finding two unwatched containers, adding one after approval and rejecting the other

What it does

  • Looks at your Docker hosts over SSH for containers with a published port. Loopback-only ports don't count, because Kuma can't reach them anyway.
  • Optionally looks at Proxmox LXC containers and your Cloudflare Tunnel hostnames.
  • Works out what's already covered: same IP, same host and port, same hostname, a watched tunnel hostname in front of it, or a monitor with the same name.
  • Asks before adding anything. That's either kuma-discover review at the terminal, or ✅ / ❌ in a Discord channel, where only my reaction counts.
  • Remembers every answer. Say no once and it never asks again.

There's no AI model in it. Every decision is a rule you can read.

The three bugs

1. Kuma 2 broke the library's add call. uptime-kuma-api was written for Kuma 1. On Kuma 2 its add_monitor() fails, because a new conditions column can't be empty. The fix is to build the same payload and send it with conditions set. kuma-discover tries the normal way first and only falls back when it sees that error.

2. The notification list that added notification "0". My first live add failed with a foreign-key error. Kuma loops over the keys of notificationIDList, so sending [1] (a list) meant it tried to attach notification id 0, which doesn't exist. It has to be {"1": true}. Found and fixed the same night.

3. It tried to monitor itself. I didn't find this one, my own test did. The setup check runs a real Kuma container on GitHub, and I'd named it kuma instead of uptime-kuma. kuma-discover only skipped Kuma by name, so it happily proposed "Svc: kuma". It now skips the louislam/uptime-kuma image too, whatever the container is called.

There was a fourth, softer one. Logging in sometimes timed out against my Kuma on the Zima, 2 runs out of 7 one morning. It retries 3 times now.

The setup guide is tested

Same as my other repos now: docs/SETUP.md gets followed by CI on every change. It runs against real Uptime Kuma 1.23.16 and 2.5.6 containers, and a real Docker host over SSH, from install to an approved monitor actually showing up in Kuma. The screenshot above is from that run. Proxmox, Cloudflare and Discord need real accounts, so they're marked "not CI-tested" instead of quietly assumed.

Try it 

pipx install git+https://github.com/casareanderson/kuma-discover curl -fsSLO https://raw.githubusercontent.com/casareanderson/kuma-discover/main/config.example.toml mv config.example.toml kuma-discover.toml # set your Kuma URL and Docker hosts export KUMA_USERNAME=admin KUMA_PASSWORD='...' kuma-discover scan --dry-run

Free and MIT: github.com/casareanderson/kuma-discover.

How many of your containers does your monitoring actually know about? I thought I was close to all of them. I wasn't.

🤖 Drafted with AI assistance from my own homelab notes, logs and repos, then reviewed and edited before publishing.