Uptime Kuma widget for Omarchy

A bar widget for the Omarchy shell (Quickshell). It shows a heartbeat icon whose colour reflects the worst state across your monitors, and opens a dropdown listing every monitor grouped by category with its 24-hour uptime and last response time.

How it gets the data

Uptime Kuma has no general REST API for reading monitor status, but a published status page exposes two unauthenticated JSON endpoints that between them carry everything this widget needs:

• GET {baseUrl}/api/status-page/{slug} — groups and their monitors
• GET {baseUrl}/api/status-page/heartbeat/{slug} — recent heartbeats + 24h uptime

The status-page groups become the categories in the dropdown.

Responses are treated as untrusted: curl runs with -q (ignores ~/.curlrc), is pinned to http/https for both requests and redirects, follows no redirects, and is capped at 2 MB; Model.js bounds every parsed collection and text field and keys untrusted maps on a null prototype; all endpoint-derived strings render as plain text (never QML rich text).

The widget fetches whatever URL you configure, over the network, from inside your desktop session — it does not blocklist private or link-local addresses, because pointing it at http://localhost:3001 or a homelab 192.168.x.x is a normal setup. So point it only at a status page you control or trust, and prefer https (a plain-http endpoint on an untrusted network can be MITM'd).

Requirements

• Omarchy with the Quickshell-based omarchy-shell (Quattro / 4.x).
• curl — used for the two HTTP polls. Ships with Omarchy; nothing to install.
• A reachable Uptime Kuma instance with a published status page.

Setup

1. Create a status page in Uptime Kuma

1. Status Pages → New Status Page. Pick a slug, e.g. omarchy.
2. Add a group per category and drag the monitors you want into each.
3. Save, and make sure the page is published. "Unlisted" is fine; a password-protected page will not work.
4. Check it:

   curl https://your-kuma-host/api/status-page/omarchy
   

   You should get JSON containing publicGroupList.

2. Install the widget

omarchy plugin add https://github.com/p145085/omarchy-uptime-kuma.git --enable --yes
omarchy bar move io.github.p145085.uptime-kuma --section right

Or drop this directory into ~/.config/omarchy/plugins/io.github.p145085.uptime-kuma/ by hand, then omarchy-shell shell rescanPlugins and omarchy plugin enable io.github.p145085.uptime-kuma.

3. Point it at your instance

Click the bar icon. While it's unconfigured the dropdown shows a small form — enter your instance URL and the status-page slug, hit Save. The icon has an edit link next to the status pill to change it later.

Equivalently, from a shell:

omarchy bar set io.github.p145085.uptime-kuma baseUrl "https://status.example.com"
omarchy bar set io.github.p145085.uptime-kuma slug "omarchy"

or edit the widget's entry in ~/.config/omarchy/shell.json:

{ "id": "io.github.p145085.uptime-kuma", "baseUrl": "https://status.example.com", "slug": "omarchy" }

Setting	Default	Meaning
baseUrl	""	Base URL of your Uptime Kuma instance. Must be an http:// or https:// URL; anything else is ignored and the widget stays unconfigured
slug	""	Slug of the published status page to read
refreshIntervalSec	60	Poll interval, clamped to 15–3600s (set via omarchy bar set or shell.json)

This Omarchy build has no settings-form GUI for plugins — settingsForm and schema in a manifest are currently inert. The in-panel form and omarchy bar set are the ways in.

Behaviour

• Icon tint — theme foreground when everything is operational, amber for pending/maintenance, red (theme urgent) when anything is down. A small red badge shows the down count.
• Left click — toggle the dropdown. Middle click — force a refresh. Right click — open the status page in your browser.
• In the dropdown — j/k or arrows move the selection, Enter opens the status page, r refreshes, Esc closes. Clicking a row opens the status page (Uptime Kuma status pages have no per-monitor deep link).
• A failed poll keeps the last good data on screen and shows an "offline" strip rather than blanking out.

Removing

omarchy plugin remove io.github.p145085.uptime-kuma --yes

That takes the widget off the bar and deletes ~/.config/omarchy/plugins/io.github.p145085.uptime-kuma/. If you installed by hand, delete that directory and remove the widget's entry from ~/.config/omarchy/shell.json, then omarchy restart shell. The plugin writes nothing outside its own shell.json entry.

Development

npm test          # unit tests for Model.js (pure parsing/formatting)

Model.js holds all the pure logic and is plain CommonJS so it runs under Node. KumaService.qml polls; Panel.qml is the bar button plus dropdown.

Changes to widget QML are picked up by omarchy restart shell (a plain rescanPlugins does not reliably clear the QML component cache for bar widgets).

Not included (yet)

• Prometheus /metrics enrichment (response-time history, TLS cert expiry)
• Acknowledging or pausing monitors (needs the authenticated socket API)

License

MIT — see LICENSE.