ntfy

ntfy (pronounced “notify”) is a self-hostable, HTTP-based pub-sub notification service that lets you send push notifications to any phone, desktop browser, or connected device using nothing but a simple HTTP request. Whether you’re monitoring a server, automating a home lab, or just want to know when a long-running script finishes, ntfy turns any curl command into a real-time push notification with zero configuration required.

The project ships as a single Go binary that runs both the server and the CLI client. You can subscribe to topics from Android (via Google Play or F-Droid), iOS (App Store), or directly in any modern web browser via WebSocket. On the server side, ntfy supports SQLite for lightweight single-node deployments and PostgreSQL for production-grade installations, with S3 or local filesystem storage for file attachments.

ntfy is openly licensed under Apache 2.0, and a free public instance is available at ntfy.sh for anyone who wants to try it without self-hosting. Paid plans through the ntfy.sh hosted service unlock higher rate limits, larger attachments, reserved topic names, phone call alerts via Twilio, and email delivery. The server itself is fully feature-complete for self-hosters at no cost, and the paid cloud plans exist mainly to support ongoing development.

With over 30,000 GitHub stars, 300+ contributors, and releases shipping multiple times a month, ntfy has grown from a weekend project into a cornerstone tool in the homelab and developer automation community.

What You Get

• Zero-friction HTTP API - Publish a notification to any topic with a single curl command; topics are created on-demand and require no prior setup or registration.
• Native mobile apps - Official open-source Android (Google Play + F-Droid) and iOS (App Store) apps that receive real-time push notifications with priorities, sounds, vibration patterns, and action buttons.
• Web browser subscriptions - Subscribe to topics directly in any browser; the web app uses WebSocket for live delivery and shows desktop notifications via the Notifications API.
• File and image attachments - Send photos, log files, videos, or any binary payload alongside a notification message, with configurable size limits and expiry.
• Interactive action buttons - Embed up to three clickable buttons in notifications that open URLs, broadcast Android intents, or invoke HTTP callbacks—enabling acknowledge flows without a separate app.
• Scheduled and heartbeat delivery - Schedule notifications for future delivery and use dead-man’s-switch patterns to receive an alert if a periodic event fails to arrive.
• Email and phone call delivery - Relay notifications as emails via SMTP or trigger actual phone calls using Twilio for high-urgency alerting (available on hosted plans).
• Access control and token auth - Protect topics with username/password or token-based access controls, with declarative user and ACL management in the server config file.
• Prometheus metrics - Expose a /metrics endpoint for Grafana/Prometheus integration, with a community-maintained dashboard for monitoring message rates and subscriber counts.

Common Use Cases

• Server and cron job monitoring - A sysadmin appends a curl ntfy command to backup scripts and cron jobs so they receive a phone notification the moment a job completes or fails.
• Home automation and IoT alerts - A home lab user configures their motion sensor or 3D printer to POST a photo or status update to an ntfy topic whenever a significant event occurs.
• CI/CD pipeline notifications - A developer adds an ntfy step to their GitHub Actions or GitLab CI workflow to receive a desktop notification the instant a build succeeds or a deployment finishes.
• SSH login and security alerts - A server administrator sets up PAM or a bash script to publish an ntfy notification whenever someone logs into a production machine.
• Changedetection and web scraping - A user wires changedetection.io to ntfy so they get a push notification the moment a web page changes, a price drops, or a product comes back in stock.
• Dead-man’s switch health checks - A developer publishes a heartbeat to an ntfy topic every hour from a background service, configured so an alert fires if the heartbeat stops arriving.

Under The Hood

Architecture ntfy is structured around a central server object that composes all subsystems—HTTP/HTTPS listeners, a WebSocket upgrader, an SMTP ingress server, a topic registry, a visitor rate-limiter, and optional Firebase and web push relay clients—into a single coordinated runtime. The publish path fans out from the HTTP handler through the topic abstraction, which dispatches incoming messages to all active in-memory subscribers via function callbacks registered at subscription time. Persistence is decoupled from the hot path: messages are written to a message cache (SQLite or PostgreSQL via a shared db.DB pool) after fanout, and attachment storage is routed through a Store abstraction that supports both local filesystem and Amazon S3. The user and ACL system lives in its own package with a dedicated Manager that handles authentication, token lifecycle, tier enforcement, and asynchronous stats persistence without blocking the publish path. Build tags isolate platform-specific code (Unix vs. Windows signal handling, Darwin-specific CLI flags) and optional payment/Firebase integrations, keeping the core binary lean for distributions that exclude them.

Tech Stack ntfy is written entirely in Go and compiled to a self-contained static binary using GoReleaser with CGO enabled for SQLite via mattn/go-sqlite3. The server supports both SQLite (for single-node deployments) and PostgreSQL via jackc/pgx/v5 (for production multi-replica setups). Real-time delivery to browsers uses gorilla/websocket and Server-Sent Events over plain HTTP. The web front-end is a React/Preact single-page application built with Vite, bundled and embedded into the Go binary at compile time. Mobile push is relayed through Firebase Cloud Messaging (FCM) for Android and Web Push (RFC 8030 via SherClockHolmes/webpush-go) for browsers. Optional integrations include Stripe (stripe-go/v74) for billing, Twilio for phone calls, SMTP for email delivery, Prometheus (prometheus/client_golang) for metrics, and AWS S3/GCS for attachment storage.

Code Quality The test suite is extensive, spanning unit tests, integration tests, and end-to-end HTTP tests across nearly every subsystem—server routing, account management, billing flows, SMTP ingress, web push, and Firebase. Tests use testify/require for assertions and rely on a shared test helper that spins up an in-process server against a real SQLite database, enabling realistic integration coverage without external dependencies. Error handling follows Go conventions with typed sentinel errors and structured HTTP error responses that include machine-readable codes alongside human-readable messages. The codebase uses consistent naming, strong typing for all API payloads and visitor contexts, a structured JSON logger with dynamic log levels, and an internal Sprig-based templating engine for parameterized notifications. CI runs on GitHub Actions with code coverage tracked via Codecov, and Go Report Card shows a clean bill of health.

What Makes It Unique ntfy’s defining characteristic is radical simplicity at the interface level combined with substantial depth underneath. Publishing a notification requires no SDK, no authentication by default, and no pre-registered topic—a single curl PUT is all it takes. Yet underneath, the system supports WebSocket, SSE, JSON, and raw streaming endpoints on the same topic URL, delivering messages to heterogeneous clients simultaneously. The unified pub-sub model eliminates the need for separate webhook registrations, polling loops, or message queue infrastructure for notification use cases. The addition of templated notifications with Sprig functions, declarative config-driven user and ACL management, dead-man’s-switch scheduling, and interactive action buttons in the same lightweight binary makes ntfy a surprisingly complete notification platform rather than just a relay service.

Self-Hosting

ntfy is dual-licensed: the main server codebase is Apache License 2.0, and an alternative GPLv2 license is also available (both are included in the repository). Apache 2.0 is a permissive open-source license that allows commercial use, modification, distribution, and private use without any copyleft obligations. You can run ntfy internally in your organization, integrate it into proprietary products, and modify the source code without being required to open-source your changes. The only requirement is preserving copyright and license notices.

Operationally, self-hosting ntfy is straightforward for a single-node deployment: a single Go binary, a YAML config file, and either SQLite (zero additional infrastructure) or PostgreSQL (for multi-replica or high-availability setups). Docker images are provided for both amd64 and ARM. You are responsible for TLS termination (typically via a reverse proxy like nginx or Caddy), backups of the SQLite database or PostgreSQL instance, keeping the binary updated when new releases ship (roughly monthly), and configuring rate limits and access controls appropriate to your threat model. For high-traffic deployments, the attachment store can be pointed at S3 or GCS, and PostgreSQL with read replicas is supported. The operational burden is low for small teams but grows proportionally with scale.

The hosted ntfy.sh service offers paid plans starting at $5/month that provide reserved topic names, higher message and attachment limits (up to 250 MB per file), phone call alerts via Twilio, managed uptime, and implicit support for the project’s development. Self-hosters get the full server feature set at no cost but forgo managed upgrades, the hosted status page, commercial support SLAs, and the Twilio phone-call integration (which requires your own Twilio account and configuration). There is no enterprise tier or support contract currently available, so organizations with strict SLA requirements need to factor in their own operational investment.