KumaStatusBar Support

Uptime Kuma status pages in your Mac's menu bar and on your iPhone.

Get it free on the App Store, for Mac and iPhone.

Need help? Email support@defingo.net with your macOS or iOS version, the KumaStatusBar version (Settings → About) and what you're seeing.

What you need

• A Mac with Apple silicon running macOS 14 or later, or an iPhone running iOS 17 or later.
• An Uptime Kuma server with a status page that lists the monitors you want to see. KumaStatusBar reads the status page, so no Uptime Kuma login or API key is needed.

Getting started

1. Open KumaStatusBar. It lives in the menu bar (there's no Dock icon). Click its icon, then Open Settings. To look around first, click Try Demo Mode instead.
2. In Settings → Connection, enter your Uptime Kuma address. You can paste the status page's address, the one you open in a browser, such as https://status.example.com/status/home.
3. Click Test. You should see the page name and how many monitors it has.

The end of the address, …/status/home, tells KumaStatusBar which status page to show. A plain server address such as http://192.168.1.20:3001 also works if Uptime Kuma's Settings → General → Entry Page is set to a status page, or if the status page has its own domain.

Home and remote URLs

For a homelab, KumaStatusBar can connect to Uptime Kuma directly on your network and through a tunnel or public address everywhere else:

• Home URL: the status page on your network, for example http://192.168.1.20:3001/status/home. Plain http:// is fine here.
• Remote URL: the status page's address from anywhere, such as through a Cloudflare Tunnel. It can be a different status page from the home one.
• Route: Automatic tries the home URL first and falls back to the remote one, re-checking when your network changes. It works on Wi-Fi, Ethernet and over a VPN home. You can also choose Always home or Always remote.

The badge in the top-right of the popover shows which one the last check used: Home or Remote.

Cloudflare Access

If your remote URL is protected by Cloudflare Access, KumaStatusBar can send a service token:

1. In Cloudflare Zero Trust, create a service token (Access → Service credentials).
2. On the Access application for your status page, add a policy with action Service Auth that includes the token. A normal Allow policy doesn't accept service tokens.
3. In Settings → Connection, click Add token… under Cloudflare Access token, paste the Client ID and secret, click Test remote URL, then Save token.

The token is stored in your Keychain and is only ever sent to the remote URL.

On iPhone

The iPhone app shows the same status page, with the same Settings (tap the gear). Pull down to refresh, or tap the compass to open the status page in Safari.

• Widgets: long-press the Home Screen, tap Edit → Add Widget and choose KumaStatusBar (small or medium). For the Lock Screen, long-press it and tap Customize. Widgets check your status page on their own every 15–30 minutes (iOS decides exactly when) and update whenever you open the app.
• Alerts: iOS only lets apps check while they're open, so the iPhone app notifies you while it's open. For instant alerts when it isn't, add an Uptime Kuma notification to an iPhone app such as ntfy, Pushover or Bark.

Incidents, maintenance and tags

Above the monitors, a row of counts shows how many are up, down, pending, in maintenance and unknown, like Uptime Kuma's Quick Stats (paused monitors aren't on status pages, so they aren't counted). Click or tap a count to list only those monitors, and again to list them all. When your status page has an incident posted or maintenance in progress, KumaStatusBar shows it there too, like Uptime Kuma's own banners. To see each monitor's tags next to its name, turn on Show monitor tags (Settings → General on the Mac, Settings → Display on iPhone); the status page needs Show Tags turned on in Uptime Kuma. When there isn't room for every tag, hover over them on the Mac.

Monitor details: click a monitor in the Mac popover, or tap it on iPhone, to see its details: the latest message, a response-time chart, average and range, 24-hour uptime, recent outages, and all its tags. The monitor's address and certificate expiry appear too when the status page shares them (the monitor's option to show its URL, and the page's Show Certificate Expiry). Status pages share the last 100 checks, so that's the history shown.

Using a Mac and an iPhone

• iCloud sync: with the App Store versions, your addresses, route and check interval stay the same on both, and so does your Cloudflare token through iCloud Keychain. Set up one device and the other follows. Both can be turned off under Other devices in Settings.
• Share Setup: shows a QR code and link with your addresses, and the token if you choose. Scan it with the iPhone Camera, or open the link on another device. The app asks before changing anything. This also works with the downloadable Mac version and for setting up someone else's phone.

Alerts

When a monitor goes down, the menu bar icon gets a red dot, you get a notification and a sound plays; a different sound plays when it recovers. A yellow dot means a monitor is pending or the status page can't be reached; a blue dot means maintenance, and a green dot means everything is up. To show a dot only when something needs attention, turn off the green dot in Settings → General. Choose the sounds in Settings → Alerts, and turn on Settings → Testing → Simulate status changes to see and hear them: every 15 seconds a monitor goes down and recovers, turns pending, or enters maintenance.

Troubleshooting

It always says Remote, or the home URL fails with “The Internet connection appears to be offline”

macOS needs permission for apps to reach devices on your local network. Open System Settings → Privacy & Security → Local Network and turn on KumaStatusBar.

“Access denied”

Cloudflare Access rejected the request. Check the Client ID and secret, and that your Access application has a Service Auth policy including the token.

“No status page …” or “This server opens its dashboard”

The address doesn't point at a status page. Open the status page in a browser and paste its whole address, ending in /status/…, into Settings → Connection.

The token didn't sync to my other device

Click Save token after entering it: the token only syncs once it's saved. Also check that iCloud Keychain is on for both devices (on the Mac, System Settings → [your name] → iCloud → Passwords; on iPhone, Settings → [your name] → iCloud → Passwords & Keychain). It can take a few minutes.

The widget isn't updating

iOS decides when widgets refresh, usually every 15–30 minutes, and less often when the battery is low. Opening KumaStatusBar updates the widget right away.

No notifications

Check System Settings → Notifications → KumaStatusBar. Sounds play even when notification sounds are off; you can turn them off in Settings → Alerts.

A monitor I expect is missing

KumaStatusBar shows what's on the status page. Add the monitor to the status page in Uptime Kuma. Group monitors appear as a single entry, as they do on the page.

Privacy

KumaStatusBar collects no data. See the privacy policy.