probeglass

A small, self-hosted watchdog for your homelab.

Website: j000k3r.github.io/probeglass-website — what it does, with pictures · Documentation: j000k3r.github.io/probeglass-docs — installation, configuration, the sensor and channel references, the HTTP API, and troubleshooting

ProbeGlass is a single-container monitoring daemon: it probes your services on a schedule, keeps their history, draws the graphs, and shouts at you when something breaks. It is built to stay out of the way — one binary, one SQLite file, a few megabytes of RAM — while still answering the questions you actually ask during an outage: what is down, since when, and how often has it happened?

Every picture below is the real dashboard, filled with the sample data the setup wizard creates for you — not a mock-up.

One page, five views of the same sensors. The cards above are the default. A denser list, a tree that folds by site and group, a wall of tiles, and the map are one click apart in the top bar.

One sensor. Its charts, uptime and incidents for the window you pick — an hour to ninety days — and the raw probes they are drawn from.	The tree. Everything the installation holds, folded by site and by group, which is how you find one sensor among a hundred.

The wall puts every sensor of a site on one screen with its recent history as a heartbeat, which is what you want on a monitor on the wall of the room the rack is in.

The map draws the world from public-domain data embedded in the binary — no tile server, no request to anywhere, and it therefore also works on a network with no internet. A tile URL in Settings puts real tiles underneath it, and the borders and names are a switch.

Zoomed in, the provinces and their names appear, the water comes with them, and the bigger cities fill in what a province-sized name cannot name.

⚖️ A hobby project, vibe coded, and nobody is liable for anything

ProbeGlass is not a product, and it is not written by a professional software developer. It is one person's homelab watchdog: spare time, their own machines, and a codebase written in dialogue with an AI coding agent (Claude Code). It is shared in the hope that somebody else is looking for something similar — that is the whole of its ambition, and it is not an argument against any of the other monitoring tools out there.

There is no company behind it, no support contract, no paid tier and no SLA, and no promise that a bug gets fixed or that a breaking change waits for a major version. The issue tracker is read and patches are welcome — what is not on offer is a timeline.

It has had no design review and no security audit, and not every line has been read by a second human. Most of the code was written by the agent and then run, measured and corrected; some of it was written or reworked by hand. Expect the rough edges that come with that, and please report them.

It is MIT licensed and provided "as is", without warranty of any kind — which covers data loss, a container that will not start, and the case this project exists to catch: a service that was down for a day while the dashboard said it was fine. Do not make it your only line of defence. If a missed alert would cost you money, keep a second, independent check on the things that matter most.

How it came about, how it is written today, and what that means for you: Who makes this, and how.

Where to go next: Why another monitor? · Features · Quick start · Sensors · Alerts · Configuration · HTTP API · Operating · Development · Status · License

There are other monitoring tools, and this is not an argument against any of them. There is also no shortage of them. It is simply that most of them are a lot bigger than a homelab needs, in memory and in moving parts. ProbeGlass makes the opposite bet:

The whole program is a Go binary with the dashboard baked in via embed.FS. There is no build step between editing a .js file and reloading the page, and building the image needs nothing but the Go toolchain — no npm, no bundler, no frontend pipeline to keep alive.

• Sensors — HTTP(S), TCP (with optional TLS and send/expect), TLS certificate expiry, ICMP ping, DNS, Docker containers, and SNMP. Configured in the web UI or declared in YAML.
• Dashboard — five views of the same sensors: cards, a dense list, a foldable tree by site and group, a wall of tiles carrying the last forty checks as a heartbeat, and a map of your sites. The map draws the world from public-domain data embedded in the binary — coastlines, the lakes and rivers, country, district and province borders, and the names of countries, provinces, cities and towns, appearing as you zoom — so it works on a network with no internet and tells nobody anything; a tile URL in Settings puts real tiles under it for anybody running a tile server of their own, and a switch turns the borders and names off without touching the water. Two exceptions to the public domain: Austria's district borders come from Statistik Austria and the town names from GeoNames, both under CC BY 4.0, which asks to be named — say so wherever you show them. One setting, not five pages, with a switcher in the top bar. Per-sensor response-time charts, uptime bars, incident timeline. Updates over SSE: a probe result redraws the one card it belongs to — the status dot, the latency, the sparkline and the heartbeat — instead of reloading the page, so an open tree branch stays open and the focus stays where you put it. A Live indicator in the top bar shows whether the stream is connected and turns it off entirely with one click.
• Search — one field in the middle of the top bar, looking through everything the installation holds: sensors, sites, channels, incidents, the individual probe messages of the retention window, the settings panels, and (for administrators) the accounts. Press a hit and it takes you there — open the sensor, jump to the settings panel, show the outage in its own context. Credentials are never searched: a sensor's options and a channel's configuration are not looked through, and a search box that answers with a bot token is worse than none.
• Sites — the places your sensors are: the rack in the cellar, the VPS at a hoster. A site has a kind (local or external) and optional coordinates; it groups the tree and the wall, and with coordinates it is drawn on the map. Optional throughout — a sensor without a site behaves exactly as it did before sites existed.
• History — raw samples for 7 days, hourly rollups for 90 days, daily rollups forever. Uptime percentages stay correct at every zoom level because exactly one resolution answers any given range.
• Incidents — a sensor that starts failing opens an incident, a recovery closes it. You see what is broken now and what broke last Tuesday, and the list filters by state, by sensor, by period and by a word you remember from the message — with a reset that puts the whole list back. An open incident can be acknowledged with a note: the reminders stop, the probing and the history do not, and the recovery alert still arrives.
• Alerts — Telegram, Discord, Matrix, ntfy, Slack, and generic webhooks with an HMAC signature. Per-sensor channel selection, per-sensor reminder intervals, custom message templates.
• Two interfaces, one program — choose a simple or advanced interface during setup and change it later. Simple hides the areas a casual user does not need and folds the rest; it never disables anything, so a sensor keeps probing at the interval it had. Every field carries a ? that opens one sentence about what it is for and one example, instead of a paragraph under the form.
• Not empty on day one — setup creates four example sensors (this dashboard, a gateway, a public resolver, a public website), attached to no channel, so there is something to look at before you have configured anything: they arrive with a week of history, an outage to explain, and one of them reading Flaky, which is what the dashboard looks like once it is doing its job. They are marked as examples and can be removed in one click from Settings.
• Troubleshooting built in — probeglass doctor on the command line, and the same checks in the dashboard under Settings → Diagnostics, with the docker exec command to run it yourself.
• Auth — first-run setup creates the first account (a username and a password, with a strength indicator), and every account is a viewer, an operator or an admin. Passwords are bcrypt, sessions are signed cookies that carry the account and are re-checked on every request, and two-factor authentication (TOTP) is optional per account and comes with eight one-time recovery codes. An API key is available for scripts and Home Assistant.
• Backup and restore — Settings → Backup writes the installation out as one JSON file: the configuration and the accounts, or that plus the incidents and the hourly and daily rollups of the last 7, 30 or 90 days, or of everything. A restore checks the file, takes a byte-exact VACUUM INTO safety copy beside the database, and replaces only what the file names, so a configuration rollback never wipes history. The file carries every secret in clear text — password hashes, TOTP secrets, the API key and every channel's credentials — because a backup with masked credentials restores a channel that cannot send anything. See SECURITY.md.
• Config as code — sensors, sites and channels can be declared in a YAML file, so a rebuild from zero takes seconds.
• Small — a ~14 MB static binary in a 27 MB image (about 6 MB to pull), distroless, no shell, no package manager, ~3 MB of RAM while idle. The container starts as root only long enough to take its data directory over and drops to PUID:PGID before it opens anything — see SECURITY.md.

git clone https://github.com/j000k3r/probeglass.git
cd probeglass
docker compose up -d

Then open http://localhost:8080 and create the first account in the setup wizard.

docker run -d \
  --name probeglass \
  --restart unless-stopped \
  -p 8080:8080 \
  -v probeglass-data:/data \
  --cap-add NET_RAW \
  ghcr.io/j000k3r/probeglass:0.2.1

Every release is published under three tags: 0.2.1, the exact version; 0.1, which follows the 0.1.x patch releases; and latest, which follows the newest release of all. dev is a build of whatever is in the tree today.

NET_RAW is only needed for ICMP ping sensors. Without it, ProbeGlass falls back to an unprivileged UDP ping and tells you in the sensor result if that is not available either.

Building the image yourself needs BuildKit (docker buildx), because the Dockerfile pins its builder to $BUILDPLATFORM and cross-compiles to the target architecture rather than emulating it. BuildKit is bundled with Docker Desktop and is the default on current Docker engines; with Homebrew's docker formula it is a separate brew install docker-buildx. Without it, make run builds and serves the same binary natively.

make run          # builds the binary and serves :8080, data in ./data
make seed         # fills ./data with demo sensors and a week of synthetic history
make test         # runs the test suite

docker run --rm -p 8080:8080 -v probeglass-demo:/data \
  ghcr.io/j000k3r/probeglass:0.2.1 seed --demo --days 7
docker run --rm -p 8080:8080 -v probeglass-demo:/data \
  ghcr.io/j000k3r/probeglass:0.2.1 serve --listen :8080

The demo set brings invented sensors of several types, a week of plausible history with outages in it, and no alert channels — a seeded install never sends you anything, which is the right default for something you are only looking at. Delete the volume when you are done.

A sensor is a name, a type, a target, an interval, and a handful of options that depend on the type. Everything is editable in the UI; the same objects can be declared in YAML.

Common to all types: interval, timeout, retries (how many consecutive failures before an incident opens), group, tags, reminder_every, enabled, and the list of notification channels.

sensors:
  - name: Router
    type: ping
    target: 192.168.1.1
    interval: 30s
    retries: 3
    group: Network

  - name: Nextcloud
    type: http
    target: https://cloud.example.org/status.php
    interval: 60s
    timeout: 10s
    options:
      expected_status: 200
      body_contains: '"installed":true'
    channels: [telegram]

  - name: DNS resolves the web host
    type: dns
    target: cloud.example.org
    interval: 5m
    options:
      record_type: A
      expected: 10.0.0.42

Every channel takes an optional title_template and body_template — Go text/template strings rendered against the sensor name, type, target, status, message, latency, incident start, and duration. The built-in wording differs per event (down, reminder, recovery, test), and a template that fails to parse or execute falls back to it rather than losing the alert.

Generic webhooks POST a JSON payload and, when a secret is configured, sign the exact request body with HMAC-SHA256 in the X-ProbeGlass-Signature header. The event name travels in X-ProbeGlass-Event (down, up, reminder, or test).

Credentials are never returned by the API — the UI shows a StoredMarker placeholder instead — and the Telegram bot token is stripped from error messages, so a failed send cannot leak it into your logs.

The dashboard stores its settings in the database; the process reads its configuration from four places. Later sources win:

1. built-in defaults
2. a YAML file — -config PATH, else $PROBEGLASS_CONFIG, else <data_dir>/probeglass.yaml if that file exists
3. PROBEGLASS_* environment variables
4. command-line flags

listen: ":8080"
data_dir: /data
base_url: https://probeglass.lan     # used in links inside alerts
log_level: info                        # debug | info | warn | error
log_format: text                       # text | json
trust_proxy: false                     # honour X-Forwarded-* from a reverse proxy

retention:
  raw: 7d                              # individual probe results
  hourly: 90d                          # hourly rollups (daily rollups are kept forever)

Every key has an environment variable: PROBEGLASS_LISTEN, PROBEGLASS_DATA_DIR, PROBEGLASS_DB, PROBEGLASS_BASE_URL, PROBEGLASS_LOG_LEVEL, PROBEGLASS_LOG_FORMAT, PROBEGLASS_ADMIN_PASSWORD, PROBEGLASS_TRUST_PROXY, PROBEGLASS_RETENTION_RAW, PROBEGLASS_RETENTION_HOURLY.

Durations accept Go syntax (30s, 5m, 2h) plus the day and week suffixes these settings are naturally written in (7d, 90d, 2w), or a bare number of seconds.

PROBEGLASS_ADMIN_PASSWORD creates an administrator account named admin on a database that has no accounts at all, and is ignored afterwards — handy for automated deployments, harmless afterwards.

See docs/CONFIGURATION.md for the full reference.

The dashboard is a client of the same API you can script against. Authenticate with the session cookie or, for scripts, with X-API-Key (or Authorization: Bearer). Generate a key in Settings → API key. The key is not tied to an account and has full administrator rights, so treat it like a root password.

curl -H "X-API-Key: $PG_KEY" http://localhost:8080/api/summary | jq
curl -H "X-API-Key: $PG_KEY" localhost:8080/api/sensors/1/series?range=24h | jq
curl -H "X-API-Key: $PG_KEY" localhost:8080/api/sensors/1/uptime?range=30d | jq

A route's method is also its permission boundary. Reads are open to every signed-in role; acting on an outage needs the operator role; changing the configuration, the API key or the accounts needs the admin role. The few routes that touch only the caller's own account — GET/PUT /api/settings, PUT /api/password, /api/me/totp/* and POST /api/onboarding/tour — sit at viewer, because they are nobody else's business.

Mutating requests are checked against Origin, so a browser on another site cannot drive the API even with a valid cookie.

• Data lives in a single SQLite file (default /data/probeglass.db, WAL mode). Back up that file, or the whole volume, and you have backed up everything — byte for byte, which is still the right backup when you want everything. For a portable copy that can be trimmed,

  Read the rest on GitHub