Declare an alert once. Deliver it anywhere.
A self-hosted, API-driven notification microservice — you declare inputs,
rules, templates and channels; it evaluates and delivers, with throttling,
retries and a full audit trail.
Apache-2.0 · Python 3.12 · FastAPI · MySQL 8 · Română
Naming. The product is Klopot; the daemon, its image entry point and its
ALERTD_*settings are still calledalertdthrough 1.x. Klopot was born as the alerting service of a home-energy monitoring stack, but nothing in it is domain-specific.
Release status. 1.2.0 (2026-11-16) is the current release — ready to face the internet: a private-by-default proxy, budgets on every way in, and per-key / per-input address and rate limits; several defaults are stricter, so read its upgrade notes. 1.1.1 removed the default passwords. 1.1.0, on top of the 1.0.x durable escalation, rule incidents, Telegram actions, MQTT output and operational monitoring it adds Alertmanager/Grafana ingestion, native ntfy / Gotify / Pushover, SMS providers, packs, a setup guide, the activity log, Web Push to an installable admin UI and generated client SDKs. Read the upgrade notes before upgrading an existing install; project status summarises the release.
Fire an alert from anything that can make an HTTP request — a script, a cron job, Node-RED, another service. The caller needs only an API key and an alert type; Klopot owns routing, channels and secrets:
curl -X POST https://your-host/v1/fire \
-H "X-API-Key: $KLOPOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "backup_failed", "context": {"job": "nightly-db", "error": "timeout"}}'{ "id": "ntf_1794139677372_7fc1…", "dispatched": true,
"channels": ["ui_default", "telegram_oncall"], "status": "sent",
"title": "Backup failed: nightly-db", "severity": "warning" }Delivery channels — add one by configuration, no code:
UI (live WebSocket) · Telegram · SMS (via a gateway) · Email · Web Push (the admin UI installs as an app, iPhone included) · MQTT · ntfy · Gotify · Pushover (incl. emergency until acknowledged) · Slack / Discord / Home Assistant (generic webhook)
Telegram supports opt-in acknowledgement and snooze buttons through a dedicated bot. See the setup and action semantics (Romanian).
MQTT output publishes JSON with stable replay identities. Operational monitoring includes an admin page, Prometheus metrics, a Grafana dashboard and example alert rules.
Native ntfy, Gotify and Pushover, the SMS providers (http, twilio,
teltonika) and Web Push devices (details) arrived in 1.1.0.
Client libraries (install from sdk/): Python klopot-client and
TypeScript @klopot/client — await klopot.fire("disk_full", { host: "nas" }).
See sdk/README.md.
Inputs — where values come from: MQTT · HTTP poll · inbound webhook · inbound SMS · cron schedules · Alertmanager / Grafana.
A self-contained demo (Klopot + MySQL + Mosquitto + a sine-wave sensor + a webhook sink) that fires a real alert end to end:
git clone https://github.com/sm26449/klopot.git
cd klopot
export ALERTD_BOOTSTRAP_ADMIN_KEY="alertd_$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose -f compose.demo.yml up -d --build
./demo/smoke.sh # asserts a notification reaches the sink within 2 min
docker compose -f compose.demo.yml down -vProduction uses MySQL 8 only. SQLite is an in-memory test harness, with a separate real-MySQL test gate; it is not a runtime fallback. See testing.
Requirements: Docker with Compose v2 (docker compose), MySQL 8 (the
bundled container or your own server), and an x86-64 host — the published
image is linux/amd64 only (other platforms build from source). Klopot
typically uses ~150 MB of RAM; see resource limits.
cp .env.example .env # DB passwords, MQTT broker, admin password, channel secrets
docker compose up -d # Klopot + MySQL + nightly backups, port 127.0.0.1:5090
open http://localhost:5090/admin/ # admin UI
open http://localhost:5090/docs # OpenAPI / Swagger (open on plain-HTTP localhost)Compose variants that ship with the repo:
| Variant | Command |
|---|---|
| Production, no proxy | docker compose up -d |
| Production behind traefik (TLS), private to your LAN/VPN | docker compose -f docker-compose.yml -f compose.traefik.yml up -d |
… plus POST /v1/fire open to the internet, with limits |
docker compose -f docker-compose.yml -f compose.traefik.yml -f compose.public.yml up -d |
| Development (builds locally, bundled MQTT broker) | docker compose -f docker-compose.yml -f compose.dev.yml up --build |
Migrations run on startup. Deploy covers the traefik setup (docker or file provider), backups and upgrades. Then follow Getting Started, or install a ready-made pack from Admin UI → Packs (service heartbeat, sensor threshold, Alertmanager — see Packs).
Synthetic demo data; regenerate with scripts/screenshots.sh. The admin UI also works on a phone and installs as an app.
- API-first. Every input, variable, rule, template, channel, route and
schedule is a DB row, editable over REST. Live OpenAPI at
/docs. - Rules. A whitelisted expression language (no raw
eval), N-of-N persistence, per-rule eval interval, Alertmanager-style inhibition. - Incidents (opt-in). Track rule problems through acknowledgement and recovery, with hysteresis and optional recovery notices. Details.
- Gating. Enable flags, snooze (type / rule / channel), quiet hours, min-repeat throttling, duplicate coalescing.
- Durable delivery (at-least-once). A fire is persisted with a per-channel delivery row before any external send; a background worker retries failures with backoff and reconciles after a restart.
- Observability. An Operations page for queues, workers and connections;
Prometheus
/v1/metrics, portable Grafana dashboard and alert rules; structured logs, request trace ids and configuration audit. - Activity log. Every request received, every attempt to a provider with its HTTP exchange, and state changes of inputs, rules and channels, with editable keep / ignore rules. Details.
- Packs and import / export. Install ready-made configuration with parameters, export any selection as a pack, and import item by item with a preview. Details.
- Admin UI at
/admin— a dependency-light, build-less SPA to manage it all, watch the live log, and test channels: a setup guide for a new installation, global search (Ctrl+K / ⌘K), English and Romanian, light / dark and OS-native themes, phone layout, installable as an app for Web Push (keyboard-accessible, AA contrast).
Klopot subscribes to the declared inputs and keeps a live state cache of
variable values. Every few seconds it evaluates each enabled rule against
that cache; a rule that matches for its required consecutive ticks builds an
envelope for the dispatcher. The dispatcher applies gating, then persists a
notifications_log row and a deliveries row per routed channel in one
transaction before sending. It makes a synchronous first attempt; any channel
that fails retryably stays pending and a background delivery worker
retries it with backoff. Channel adapters enforce their own rate limits and
circuit breakers, and every config change is audited.
| Doc | What it covers |
|---|---|
| Getting Started · RO | Core concepts + an end-to-end walkthrough |
| API Reference · RO | Every REST + WebSocket endpoint, auth, errors |
| Deploy & Operations | Install, env vars, backups, upgrades, rollback |
| Project status | Released baseline, later work, verified deployment and next steps |
| Operational monitoring | Queue visibility, metrics, Grafana and Prometheus setup |
| MQTT output · Telegram actions | Setup, replay identities, acknowledgement and snooze |
| Architecture | Components, data flow, the transactional outbox |
| Expression language | Rule condition syntax + built-in functions |
| Packs | Install, write and export packs (config with parameters) |
| Activity log · Web Push | What is recorded and kept; notifications on a device without an app |
| All docs → | The full index |
Licensed under the Apache License 2.0 — see LICENSE and NOTICE. Bundled frontend runtime (vendored, build-less): Preact (MIT) · htm (Apache-2.0).
See CONTRIBUTING.md for dev setup and conventions, SECURITY.md for reporting vulnerabilities, and CHANGELOG.md for history.
Website: klopot.dev. Bugs and ideas go to Issues; anything else — questions, help with an installation, an integration — to contact@klopot.dev or the form on the site.
Built by Stefan Maldaianu — product owner, operator and the person who gets paged at 02:00 — together with Claude (Anthropic), pair-programmer across architecture, code, audits, documentation and the Klopot brand.
Human judgement, machine stamina. The best team in the stack.





