Gatus vs Uptime Kuma: When a YAML File Beats Another Docker Dashboard

Uptime Kuma is the default answer when someone asks how to watch a homelab. It is pretty, it runs in Docker, and you can click your way from zero monitors to a wall of green in an afternoon. That is also why a quieter tool keeps winning for people who already treat infrastructure as code: Gatus.

Gatus does not try to be a second control plane. It wants a YAML file, a process that stays up, and alerts that mean the check you wrote actually failed. If that sentence sounds boring, you are probably still happy with Kuma. If it sounds like relief, keep reading.

This is not a feature matrix. It is the decision that shows up after the fifth “temporary” monitor you created through a web UI and then forgot to document.

What each tool is actually optimizing for

Uptime Kuma is a dashboard-first uptime suite. You define HTTP, TCP, ping, keyword, and push monitors in a browser. You get latency charts, certificate expiry warnings, status pages, and a notification stack that can fan out to Discord, Telegram, ntfy, and a long list of other channels. For a household that wants to see whether Nextcloud, Immich, and the NAS web UI are reachable, that model is excellent.

Gatus is a config-first health dashboard. Endpoints live in YAML (or equivalent structured config). Conditions are explicit: status code, body content, certificate expiry windows, DNS answers, and custom evaluations. The UI exists to show results, not to be the source of truth. If the container dies and you still have the file in git, you still have the monitoring design.

That difference matters more than the logo on the container image. Kuma’s source of truth is the SQLite (or other) database behind the UI. Gatus’s source of truth is the file you already know how to review in a pull request.

When Kuma is still the right click-path

Stay with Uptime Kuma if most of these are true:

• You change monitors weekly and hate editing files for small tweaks.
• Non-technical household members need a status page that looks intentional.
• You want a rich monitor catalog without writing conditions by hand.
• You already invest time in the Kuma UI the way other people invest in Home Assistant dashboards.

Kuma also wins when the failure mode is social, not technical. Showing a partner a green tile labeled “guest Wi-Fi portal” is clearer than pointing them at a Git commit. Public or semi-public status pages are a first-class product surface in Kuma. Gatus can expose status, but it does not try to be a polished incident page for strangers.

If your entire monitoring need is “tell me when the house services are down,” and you are fine clicking, Kuma is not a compromise. It is the product that matches that job.

When a YAML file beats another Docker dashboard

Gatus starts to win when monitoring becomes part of how you ship changes. You add a service in Compose, you add an endpoint block next to it, and you review both in the same change. There is no second memory of “I meant to add that in Kuma later.”

That workflow is awkward in Kuma unless you treat the UI as temporary and export/backup obsessively. People do that. Many of them still lose a monitor after a volume wipe because the backup ritual was the thing that failed.

YAML also forces honesty about what “up” means. In Kuma it is easy to create an HTTP monitor that only checks for a 200 on /. That path often returns a marketing page while the app behind /api/health is wedged. Gatus does not magically prevent that mistake, but conditions in a file make it natural to assert body content, JSON fields, or multiple checks for one service. The configuration style nudges you toward readiness, not a polite homepage.

There is a second operator benefit: diffs. When a check flaps after a deploy, you can see who changed the expected status code, the path, or the alert group. “The dashboard looked different yesterday” is a worse incident narrative than a three-line diff.

The failure modes that actually decide this

1. The monitor host is also the thing you care about

Both tools are useless if they only run on the same NUC that just lost power. That is not a Gatus-versus-Kuma problem; it is an architecture problem. Still, config-as-code makes it cheaper to run a second tiny instance on a VPS or a friend’s basement with the same file rendered for remote checks. Duplicating a carefully curated Kuma instance usually means exporting, importing, and hoping notification credentials survived.

If you already keep secrets in a password manager and Compose overlays in git, Gatus slots in. If your “backup” of Kuma is a screenshot of the monitor list, stay with Kuma until the backup habit exists.

2. Alert noise from UI experiments

Kuma makes it easy to create five near-duplicate monitors while you are debugging. Those duplicates still page you at 2 a.m. after you forget to delete them. Gatus makes experimentation slightly more annoying—you edit a file and restart or reload—and that friction is protective for people who over-click.

Conversely, if you under-monitor because editing YAML feels like work, Kuma’s low friction is the safety feature.

3. Keyword and content checks without ceremony

Kuma’s keyword monitors are excellent for “page must contain this string.” Gatus conditions cover the same ground with more explicit operators. Neither replaces a real synthetic transaction for a multi-step login. Both can lie if you check the wrong surface. The decision is whether you want those content checks as form fields or as reviewed assertions.

4. Team of one versus household of many

A solo builder who already lives in git will feel at home in Gatus. A household where three people occasionally add a new service will fight less with Kuma. Monitoring tools fail when only one person knows how to change them. Pick the interface your actual operators will use under stress.

Resource and operational shape

Both are light by modern standards. Kuma’s UI and history database are heavier than a small Gatus process, but on a typical mini PC neither is the reason you buy more RAM. What costs attention is operational surface: upgrades, reverse proxies, authentication in front of the dashboard, and where notification tokens live.

Kuma’s dashboard is a temptation to expose something friendly on the LAN or through a tunnel. That is useful and also a hostname disclosure risk if you publish a status page carelessly. Gatus can be kept almost invisible—config in, alerts out—with the UI only on Tailscale. If your instinct is “I do not want another pretty panel on the internet,” Gatus matches that instinct.

Storage is another quiet difference. Kuma accumulates monitor history you will stare at during incidents. Gatus can keep results, but the culture around it is less “chart archaeology” and more “did the condition fail.” If charts are how you debug, Kuma. If logs and conditions are how you debug, Gatus.

A practical split that works in real homes

You do not have to marry one tool forever. A pattern that holds up:

• Use Gatus (or another config-first checker) for services you deploy yourself and can define in the same repo as Compose.
• Use Uptime Kuma for human-facing status, guest-visible checks, and one-off monitors you will delete next week.
• Keep push/cron heartbeats somewhere purpose-built when the job is “did the backup script finish,” not “is the TCP port open.”

That last point matters. Neither Gatus nor Kuma is a perfect substitute for a heartbeat service aimed at scheduled jobs. People stretch HTTP monitors until a cron failure looks like uptime. Do not let the dashboard choice become an excuse to misuse the check type.

Migration without a purity spiral

If you are drowning in Kuma monitors and craving YAML, do not rewrite everything in a weekend. Export or list the monitors that have paged you in the last ninety days. Those are the ones that earned a file. Leave vanity checks in Kuma until they annoy you enough to delete.

If you are on Gatus and family keeps asking for a prettier page, add Kuma for that surface only. The mistake is forcing every stakeholder through the interface you personally prefer.

When you move a check, change one thing at a time: path, expected body, interval, alert channel. Parallel-run for a week. Turning off the old monitor the same night you invent a stricter condition is how you learn which false positives you had been depending on.

Decision checklist

Choose Uptime Kuma when you want a clickable ops console, polished status pages, and monitors that change with household whims.

Choose Gatus when monitors should live beside your Compose files, conditions should be reviewable, and another SQLite-backed dashboard would be one UI too many.

Choose both when different people need different interfaces, and you are disciplined enough not to double-page yourself for the same outage.

The YAML file does not win because it is morally superior. It wins when your failure mode is “I clicked something last month and cannot remember what up meant.” For a lot of solo builders past the first honeymoon with green tiles, that is exactly the failure mode that hurts.