Uptime Kuma has no widget of its own — it is a self-hosted server with a web dashboard. Widgets come from a third-party client; KumaAlert ships Home Screen, Lock Screen and Control Center widgets on iPhone and iPad, and home-screen widgets plus a Quick Settings tile on Android.
Widgets read status through an Uptime Kuma API key rather than the app's live connection, because the system only wakes a widget briefly. Create one under Profile → API Keys in the web UI and paste it into the app.
The check you stop having to make
Most people who self-host Uptime Kuma have a small ritual: open the app, or the browser tab, and confirm everything is still green. It takes fifteen seconds and you do it several times a day, mostly to find out that nothing has happened.
A widget deletes that ritual. Status is on the Home Screen next to the weather, so the answer arrives without a decision to check. That is the entire value proposition, and it is a larger one than it sounds — the alert tells you when something breaks, and the widget tells you, continuously, that nothing has.
Adding a widget on iPhone and iPad
Install KumaAlert and add your Uptime Kuma server, including an API key (see below).
Long-press an empty area of the Home Screen until the icons jiggle, then tap + in the corner.
Search for KumaAlert and pick a size. Small is a single status summary; larger sizes list individual monitors.
Tap Add Widget, then long-press the placed widget and choose Edit Widget to pick which server or monitors it shows.
Lock Screen widgets are added the same way through Customise on the Lock Screen, and on iPad the same widgets work on the Home Screen and in Today View. There is a Control Center control too, if you would rather reach status by swiping down than by finding a page of icons.
Adding a widget on Android
Long-press an empty area of the home screen and choose Widgets.
Scroll to KumaAlert, then drag the size you want onto a screen.
Pick the server or monitors when the configuration screen appears; resize by long-pressing and dragging the handles.
There is also a Quick Settings tile, which is the fastest of the lot — one swipe from any screen, including the lock screen, without going home first.
Why widgets need an API key
Widgets do not run continuously. The system wakes them on its own schedule, gives them a moment to fetch data, and puts them back to sleep — which rules out the persistent Socket.IO connection the main app uses. Instead the widget reads status through an Uptime Kuma API key, a cheap read that finishes inside the budget the system allows.
In the Uptime Kuma web UI, open Profile → API Keys and add a key.
Copy it once — Uptime Kuma shows it a single time.
In KumaAlert, open the server and paste the key into the API key field.
The same key also backs the Apple Watch and Wear OS apps, so it is worth creating even if widgets are all you are after. Full steps are in the setup guide.
A widget is not an alarm. iOS and Android both refresh widgets on a system-controlled budget, not on demand, so treat the number on your Home Screen as recent rather than live. Anything that must reach you the instant it happens should be a push notification as well.
Getting the most out of it
Show the monitors you would act on. A widget listing thirty monitors is a wall of text you stop reading. Four or five that would genuinely ruin your day is a widget you actually parse at a glance.
Use the tap target. Tapping a monitor in the widget deep-links straight to that monitor's detail screen, not the app's front page — which matters when you are opening it because something is red.
One per server. If you run staging and production separately, two small widgets read faster than one large one trying to merge them.
Lock Screen first. On iPhone the Lock Screen widget is seen an order of magnitude more often than the Home Screen one, because you look at the Lock Screen every time you pick up the phone.
No. Uptime Kuma is a self-hosted server with a web dashboard and ships no mobile app or widget. Widgets come from third-party clients such as KumaAlert.
How often does the widget refresh?
The operating system decides, on a budget it controls and adjusts based on how often you look at it. Expect recent rather than real-time, and rely on push notifications for anything time-critical.
My widget says “no data”
Nearly always a missing or revoked API key. Re-create the key under Profile then API Keys in the Uptime Kuma web UI and paste it into the server in the app. If the widget is pointed at a monitor that has since been deleted, edit the widget and pick a current one.
Does the widget need my server reachable from the internet?
Yes for the widget specifically - it reads live status from your instance, so the phone has to be able to reach it, whether over the internet, a VPN or Tailscale. Push alerts do not have this requirement, because those travel outbound from your server.