Argus is a thin rail at the edge of the screen with a dot for each of my services: green when it’s up, red when it’s down, amber while it’s checking. Hover and it expands into a list with icons and names, click one and it opens in your browser. You can see that something’s down without alt-tabbing to a dashboard. This note is how it was built.
Where it came from
Argus didn’t start as an app. It began as a small status sidebar inside the private repository I use to run my homelab, and on 17 June 2026 it was moved out into a project of its own and named Argus. Most of the work happened in the four days after that. A second round in August turned it into something other people can install.
It also became a template. When I built Brimdock, an SSH dock that lives on the same screen edge, its design document says the stack, the packaging and the release pipeline mirror Argus.
What it watches
Argus can read from Uptime Kuma, from its own checks, or from both at once.
Uptime Kuma: Argus talks to it over Socket.IO. It logs in, then listens for the monitor list and each heartbeat as it arrives. Kuma reports four states, and Argus maps them to three colours: up is green, down is red, and both kinds of pending are amber.
One small detail makes clicks more useful. Monitors usually point at a health endpoint, like /api/health, which isn’t
a page you’d want to open. So a click opens the site’s base address instead.
Its own checks cover services that aren’t in Kuma. Any 2xx or 3xx response counts as up, and redirects aren’t followed. There’s a 5-second timeout, and at most 8 checks run at once.
Icons come from the homarr dashboard-icons set first, because internal services often hide their favicon behind a login page.
The Settings window that fought Wayland
Argus lives at the screen edge as a layer-shell surface, the kind of window Wayland lets a compositor anchor for you. The first Settings page was one too, and it went wrong in several ways:
- It filled the screen. With no anchors, KWin stretched it to the whole display. Setting no anchors on purpose made it a centred 600 by 640 box.
- Dragging it was jumpy. Moving the window by changing its margins fed back into the pointer’s position and snapped it to the edges. A full-screen transparent canvas with the panel dragged inside it fixed the jumping.
- Then I stopped fighting. In the end the Settings page became an ordinary window, with a title bar and a taskbar entry. Only the rail itself needs to be special, and an ordinary window behaves the way people expect.
Two more bugs from that window:
- Settings crashed when opened a second time, with “Internal C++ object already deleted”. Python’s garbage collector had freed the component that builds the window. It’s now kept alive.
- The Save button silently did nothing. The form data arrived from QML as a JavaScript value rather than a Python dictionary, and the error never reached the screen. It’s converted now, and a test makes sure it stays that way.
Saving keeps your file intact: the config is TOML, written with a library that preserves your comments and the secrets you put there.
Tests, and the bug that only showed up on Python 3.14
Argus has 53 tests, run in CI without a screen through Qt’s offscreen platform. The parts tests can’t reach, like how the rail behaves on a real compositor, were checked by hand on a live KWin session.
The oddest bug was in the tests themselves. Under Python 3.14, the test run crashed on exit with code 139, a segmentation fault. The tests were starting threads that fetched real icons over the network, and those threads were still running while Python shut down. Tests now get a resolver that never touches the network.
Packaging
The release pipeline builds packages for Arch, Debian and Fedora, test-installs the Debian and Fedora ones to make
sure they work, and only then publishes. Releases are GPG-signed and come with a signed SHA256SUMS.
Most of the bugs here were about names and versions:
- Debian rejected a version that didn’t start with a digit. The real cause was git refusing to read the repository, so the version came out wrong.
- On Fedora the Socket.IO library is
python3-socketio, not the name you’d guess from pip. - The name
arguswas already taken in the AUR, so the package there isargus-sidebar. - The CI signing key had a passphrase, and
gpgsat waiting for someone to type it.
Where it is now
Argus is at version 0.1.2, with packages on its GitHub releases.
The code is closed for now, until I’ve finished working on it; the GitHub repository has the documentation and the signed releases.