ntfy is a lightweight, open-source notification service that enables users to send push notifications to their mobile devices or desktop browsers via simple HTTP PUT or POST requests. Designed for developers, sysadmins, and automation enthusiasts, it solves the problem of receiving real-time alerts from scripts, servers, or IoT devices without requiring complex infrastructure or user registration.
Built in Go and powered by a REST API, ntfy supports self-hosting, WebSocket-based browser subscriptions, and integrates with tools like curl, Python, JavaScript, and GitHub Actions. It offers both a free public instance (ntfy.sh) and paid Pro plans, with open-source Android and iOS apps available for native notification handling.
What You Get
- HTTP-based Pub-Sub API - Send notifications via simple PUT/POST requests using curl, Python, or any HTTP client; topics are created on-demand without registration.
- Mobile Push Notifications - Receive alerts on Android and iOS via official open-source apps that support priorities, sounds, vibrations, and action buttons.
- Desktop Browser Notifications - Subscribe to topics directly in your web browser to receive pop-up notifications without installing any app.
- File Attachments - Send images, videos, logs, or documents (up to 250MB on Pro) directly to your phone or desktop as part of a notification.
- Action Buttons - Embed clickable buttons in notifications to trigger URLs (e.g., “Acknowledge”, “Stop Alarm”, or “Open Dashboard”).
- Priority Levels & Emojis - Set notification priorities (low, default, high, urgent) to control sound, vibration, and visibility; include emojis for visual context.
Common Use Cases
- Monitoring server health - A sysadmin uses ntfy to receive instant alerts when a cron job fails or a disk fills up, using a simple curl command in their script.
- Home automation alerts - A smart home user configures their Raspberry Pi to send a photo notification via ntfy when the security camera detects motion.
- GitHub Actions notifications - A developer sets up a workflow to send a desktop notification when their CI/CD pipeline succeeds or fails.
- TV show episode alerts - A user runs a script with changedetection.io to monitor a streaming site and gets a push notification when a new episode is released.
Under The Hood
Architecture
- Centralized application logic in main.go with a unified CLI interface powered by urfave/cli/v2, enabling seamless server and client command execution
- Clear separation between server and client components via dedicated cmd/ subpackages, with platform-specific implementations managed through build tags for portability
- Modular design using package-level configuration structs and environment variables for dependency injection, avoiding global state and enhancing testability
- Decoupled build and deployment workflows via Makefile, supporting targeted compilation of server, client, web, and documentation artifacts
Tech Stack
- Go-based binaries with embedded SQLite storage and CGO support, compiled across multiple platforms using GoReleaser with static linking and metadata injection
- Lightweight Docker deployment using Alpine Linux, with explicit volume mounts for configuration and cache persistence
- Modern web interface built with npm, Prettier, and ESLint, integrated into MkDocs documentation with theming and dark/light mode support
- Infrastructure-as-code practices with systemd templates, NFPMS packaging, and automated generation of Docker images, binaries, and installers
Code Quality
- Comprehensive test coverage spanning unit, integration, and end-to-end scenarios using testify for assertions and server mocking
- Well-defined interfaces and modular components (server, CLI, logging, storage) enabling clear separation of concerns and easy extension
- Robust error handling with structured HTTP responses, descriptive codes, and context-aware propagation across API layers
- Consistent Go idioms in naming, strong typing for API payloads and user contexts, and dynamic logging with JSON output for observability
What Makes It Unique
- Native cross-platform CLI with system-level integrations (signals, shell scripts) enabling push notifications without external daemons
- Unified pub/sub architecture supporting HTTP, MQTT, and SNS from a single binary, eliminating fragmented notification gateways
- Client-side error boundaries with IndexedDB fallback and user-guided recovery for private browsing modes
- Bi-directional i18n and RTL support embedded in the web UI via custom styling plugins, without third-party dependencies
- Decentralized notification routing where self-hosted instances operate independently yet integrate with cloud services
- Built-in token-based access control and subscription tiers managed through a unified API, reducing reliance on external auth providers