kuvasz-uptime/kuvasz 4.5.0

v4.5.0

on GitHub

Documentation: v4.5.0- kuvasz-uptime.dev

docker pull kuvaszmonitoring/kuvasz:4.5.0

Features

🐳 Docker monitoring

Docker monitors ask the Docker daemon itself whether a container is running and healthy, so they catch what a port check misses: crash loops, OOM kills, paused containers, failing healthchecks, and containers without any port at all. The errors tell you what actually happened, e.g. "The container exited (137) after it was OOM killed", and the image of the container is recorded with every incident. The restart count is recorded as well, and you can get alerted when it goes up. With metrics history enabled, the CPU and memory usage of the container is charted too.

The daemons are configured as named Docker hosts in your configuration file: the local socket, a socket proxy, or a remote daemon over TCP with (mutual) TLS, from Engine 19.03 onwards (see the compatibility matrix).

Docker monitors are fully integrated across Kuvasz: they're manageable via the Web UI, REST API, or YAML, participate in incidents, uptime stats, status pages, maintenance windows, notifications, the metrics exporter, YAML import/restore, and are exposed to AI assistants through the MCP server.

🤖 Slack Bot integration

The new Slack Bot integration posts the notifications to a Slack channel as a Slack app, instead of an incoming webhook. It keeps every incident and maintenance in a thread of its own, so a flapping monitor doesn't flood the channel anymore: the first message of the thread always shows the current state with its color (e.g. it turns green once the incident is resolved), and the bot can also react to it. The notes of the incidents are posted into their threads too (public ones only by default). The messages are color-coded by the severity of the event, and if Slack refuses one (e.g. because of a missing scope, or the bot not being in the channel), the error tells you how to fix it. It supports the usual global and excluded events settings, and it can be tested right from the UI.

🔀 Checking monitors through proxies

HTTP and TCP monitors can be checked through an outbound HTTP or SOCKS5 proxy now (with or without authentication), e.g. a corporate egress proxy, or a SOCKS5 proxy into a private network (like ssh -D through a bastion host).

📝 Incident notes, details with a timeline, and incidents on the status pages

Every incident has its own details page now, with a timeline of its story: its start, the integrations that were notified about it (and about its resolution), its resolution, and the notes you add to it. A note has a status (Investigating, Identified or Resolved), a plain text content, an optional custom time, and it can be marked as public. Notes are manageable via the Web UI, the REST API and the MCP server.

The status pages got a lot more talkative too: the active and the recently resolved incidents are listed right below the overall status, with their public notes, every monitor card counts its incidents and lists them on click, and hovering a day tells its downtime and the time span of its incidents. Everything else about the incidents (e.g. the errors of the checks, or the private notes) stays private. The pages refresh themselves in place instead of reloading the whole page.

🖥️ A fully redesigned dashboard

Instead of repeating the same set of stat cards for every monitor type in a boring way, the brand new dashboard gives you a single overview of all of your monitors now: a verdict in the header about what needs your attention, the key figures (uptime, incidents, downtime and mean time to resolve), an uptime timeline per monitor type, the recent incidents (both ongoing and resolved), the certificates that need your attention, the active and upcoming maintenance windows, and the least reliable monitors of the period. The period it covers can be picked with a period selector (from the last hour up to the last 30 days).

🔌 Connectivity check

When the host running Kuvasz loses its own outbound network access — an ISP blip, a router reboot, a restarted Docker network, a flapping VPN — every monitor fails at the very same moment, and you get an incident storm, a matching recovery storm and permanently polluted uptime percentages, all because of something that has nothing to do with the services you monitor.

The new connectivity check periodically dials a few well-known endpoints, and while none of them can be reached, it suspends every check Kuvasz initiates on its own — no checks, no events, no alerts — exactly the way a maintenance window does.

Improvements

• Interactive install script: on Linux and macOS, the new install script sets up the Docker Compose stack for you: it asks for the credentials, the database, the timezone, the authentication mode, the API keys, the MCP server, and whether to run as non-root or mount the Docker socket, then writes the files and starts Kuvasz. No more default secrets left in the compose file by accident.
• Connecting to PostgreSQL through its unix socket: if DATABASE_HOST points to the directory of the socket (e.g. /var/run/postgresql), Kuvasz connects through it instead of TCP, just like psql does. So when your database runs on the same host, you can mount its socket into the container and don't need to expose PostgreSQL on the network at all.
• Virtual thread scheduling (experimental, disabled by default): the scheduled checks can run on virtual threads now, so a lot of unreachable TCP, DNS or Docker targets waiting for their timeout can't delay the checks of your other monitors anymore.
• UI refresh: Tabler UI has been bumped to 1.6.x, which brings sharper focus indicators and a lot of small visual improvements, while keeping the familiar color scheme. If you'd like a different one, you can pick a gray palette and an accent color on the Settings page now: your choice is saved in your browser (just like the dark/light mode). The public status pages aren't affected by it, but each of them can get its own gray palette instead (the default one included). The start of a one-off maintenance window is picked with a proper date and time picker now (it can still be typed in, as YYYY-MM-DD HH:mm, or with seconds, as YYYY-MM-DD HH:mm:ss, which the picker itself can't select).
• A more locked-down Helm chart: the chart runs Kuvasz with a non-root group too (1000:1000, instead of 1000:0), and with a read-only root filesystem by default. Since the only place Kuvasz writes to is /tmp, the chart always mounts an emptyDir volume there. If you've added your own /tmp volume via extraVolumes and extraVolumeMounts, remove it before upgrading, otherwise Kubernetes rejects the deployment because of the duplicate mount. See the security context of the chart for the details, including a fix for ICMP monitors on older container runtimes.
• Lower memory usage on the database side: Kuvasz keeps only 2 idle database connections open instead of 10, which saves a few megabytes of memory on your PostgreSQL server while there's nothing to do. The pool still grows (up to 10 connections) when it's needed.
• More aliases in the YAML configuration: if you share common settings between your monitors with anchors and merge keys (e.g. <<: *http-monitor-defaults), more than 50 references to them made Kuvasz fail to start with a Number of aliases for non-scalar nodes exceeds the specified max=50 error. The limit can be raised now with the new YAML_MAX_ALIASES environment variable (50 by default).

Fixes

• Shutting down could hang while monitors were failing: on shutdown, Kuvasz waited for every running check to finish, while the checks of the other monitor types kept starting new ones, and the finished ones even re-scheduled themselves. With enough slow or unreachable targets, it never stopped on its own, and Docker (or whatever runs it) had to kill it. Now no new check starts once the shutdown begins, and the running ones get at most 5 seconds to finish.
• Markup in the Slack and Telegram notifications: the names of the monitors and maintenance windows, their URLs and descriptions, the reasons of the invalid certificates, and the changed DNS records are escaped now, so they're shown as they are. Before, a <, > or & in them could garble the message, make Telegram reject it altogether (e.g. a monitor called API <prod>), or even turn a DNS record into a link or a mention (e.g. <!channel>) in Slack.

Docs

• Added a recipe about reaching a proxy over TLS with a stunnel sidecar, since Kuvasz can't talk TLS to a proxy itself.
• Added a new recipe about running Kuvasz as a non-root user (optionally without any capabilities, and with a read-only root filesystem), including the things to look out for with ICMP and Docker monitors. The Docker Compose example comes with the related settings too, commented out.

New sponsors

• Big kudos to @Morethanevil for his support! <3

Full changelog: 4.4.0...4.5.0