If you run AI agents for anything longer than a few seconds, you have probably done something like this: start a task, wait anxiously, keep refreshing a terminal or a browser tab. ntfy (pronounced "notify") solves that in about five minutes. Any script, automation, or AI agent can send a push notification (an alert that appears instantly on your phone or desktop, like a text message from an app) to your phone with a single HTTP request (a standard web call, the same kind your browser makes when you load a page). No app store submission, no third-party account required, no monthly fee.
The project lives at github.com/binwiederhier/ntfy and has crossed 32,000 stars. You can use the free hosted version at ntfy.sh or run your own copy on a server in minutes.
| Fact | Value |
|---|---|
| What it is | HTTP-based push notification service |
| Built by | Philipp Heckel (open-source) |
| License | Apache 2.0, free to use |
| Platforms | Self-hosted (Docker/binary) or ntfy.sh hosted |
| Requires | No setup for basic use; Docker for self-hosted |
| Install method | Use ntfy.sh free tier or pull Docker image |
| Verdict | Install (or use the free hosted tier) if you want any script or agent to alert you on your phone without building a notification app |
What ntfy actually is
ntfy is a pub/sub notification service. Pub/sub (short for publish/subscribe) is a messaging pattern where a sender publishes a message to a named channel and any number of receivers can subscribe to that channel to get the messages. ntfy calls these channels "topics." A topic is just a URL like ntfy.sh/my-build-alerts or ntfy.sh/agent-done. You name it whatever you want; it is created automatically the first time anyone uses it.
Publishing a notification means making one HTTP POST request to that topic URL. Subscribing means installing the ntfy app on your phone (iOS or Android) and adding the same topic URL. That is the entire model. There is no registration, no dashboard to configure before you send the first message, and no SDK (software development kit, a pre-packaged library of code for a specific service) to install. If you can run a curl command (a command-line tool for making HTTP requests), you can send a notification right now:
curl -d "Build finished" ntfy.sh/my-alerts
Anyone with the ntfy app subscribed to my-alerts gets a push notification with the text "Build finished." That is the whole thing.
Because the underlying mechanism is a plain HTTP POST, any tool that can make a web request can send a notification: a bash script, Python, a cron job (a scheduled task that runs automatically at a set time), a GitHub Actions workflow, a webhook handler (a URL that receives automated HTTP calls from other services), or an AI agent running in Claude Code or Cowork. There is no library to add to your project. If the language can make a web request, it already works.
What you get after setting it up
The feature set goes well past simple text alerts.
Message priorities let you distinguish urgency levels. You can send a default notification for "task done," a high-priority one for "task failed," and a maximum-priority alert (which shows up differently in the app and can bypass Do Not Disturb on some devices) for something that truly cannot wait.
Notification actions let you attach buttons to a notification. A tap on the notification can open a URL in the browser, run a follow-up HTTP request, or send you to a specific app. An AI agent that finishes a report can send a notification with a "View report" button that opens the right URL. An agent that needs your approval before proceeding can send an "Approve" button that fires a webhook back to the pipeline.
File and image attachments mean an agent can send you a thumbnail of the output it generated, or attach a CSV for you to open directly from the notification.
Message history keeps the last few messages per topic even if your phone was offline when they arrived. By default the free tier keeps a small history window; self-hosting gives you full control over retention.
Browser push notifications work without the phone app. Subscribe to a topic in the ntfy.sh web interface and notifications arrive as standard browser push alerts on your desktop.
Private topics with access control let you require a token before anyone can publish or subscribe to a topic. This matters if your topic name is something predictable and you do not want random people publishing to it.
Scheduled delivery lets you send a notification with a delay, useful for reminders or follow-up alerts from agents that finish overnight.
The phone apps are genuinely good. Notifications arrive fast (typically under a second in testing), the UI is clean, and the iOS and Android apps both support notification grouping so a busy pipeline does not flood your lock screen.
The install experience
Using ntfy.sh (the free hosted tier): There is no install. Open your phone, download the ntfy app from the App Store or Google Play, and subscribe to a topic you make up on the spot. Then send a curl command from any terminal pointing at that topic. The notification arrives. You are done in under five minutes, and nothing was installed on a server.
The limitation of the free hosted tier is that topic names are public-ish. Anyone who knows your topic URL can publish to it. For anything sensitive, use a random topic name that is hard to guess, or add access control, or self-host.
Self-hosting: ntfy runs as a single binary (a compiled executable file you just run, no install wizard needed) or a Docker container (a self-contained software package that runs identically on any machine with Docker installed). The Docker route takes one command:
docker run -p 80:80 -it binwiederhier/ntfy serve
Point your phone app at your server's address instead of ntfy.sh, and all messages stay on your infrastructure. A more production-ready setup mounts a volume for persistence and adds a config file for access control and retention settings, but the one-liner is enough to see it working.
The config file is a single YAML file (a text-based settings format, readable without any special tools). You configure the base URL, authentication, attachment storage, SMTP (the protocol for sending email) for email delivery, and logging in one place. The documentation at docs.ntfy.sh covers the full config reference.
For a self-hosted install, ntfy is a realistic afternoon project. The binary is small, the config is simple, and there are no databases to set up. Persistent message history needs a SQLite file (a lightweight database stored as a single file on disk) or an attached volume in Docker, but that is one line in the config.
Where it fits and what to compare it to
ntfy sits in a small category of tools whose job is to let software send push notifications to humans without building a mobile application. The real alternatives are:
Pushover is the well-known paid option: $5 one-time per platform (iOS, Android, desktop separate), proprietary backend, no self-hosting. It works well and has good app quality. The upside over ntfy is a more polished notification history and grouping UI; the downside is the cost, the closed source, and the fact that all your notifications go through a third party's servers.
Pushbullet requires an account, has a free tier with rate limits, and has had a history of neglect from its maintainers. The service still works but it is not a project with an active development community.
Gotify is the closest open-source alternative to ntfy: self-hosted, MIT licensed, active project. The architecture is similar. Where ntfy wins is the hosted option (ntfy.sh means zero server required for basic use), better phone app quality in practical day-to-day use, and the simpler sending API. Gotify requires a token for every publish; ntfy works without any authentication by default on public topics.
For AI agent workflows specifically, ntfy has a clear edge over all of the above because the barrier to integration is as close to zero as possible. An agent does not need an SDK, a library import, or a configured client. It needs one HTTP call. That is the kind of integration that survives model updates, environment changes, and the general chaos of early-stage agent pipelines.
Email is the obvious fallback, but push notifications and email are not the same thing. Email is asynchronous and filtered; a push notification demands attention in real time. If you are running an agent that takes 45 minutes and you want to know the moment it finishes without polling, push wins.
Verdict
Install ntfy, or use ntfy.sh. The free hosted tier is enough for most personal and small-team workflows. If you handle anything sensitive or want unlimited message history, self-hosting is a straightforward Docker deploy.
The case for doing this is simple: every AI agent you run, every script you schedule, every cron job that runs overnight becomes observable without you having to watch it. The agent finishes, your phone buzzes, you look at the result. That is a real quality-of-life change for anyone running agents regularly, and it takes less time to set up than writing this paragraph took to read.
The caveats are minor. ntfy.sh topic names are effectively public (anyone who guesses your topic can publish to it), so use random or obscure names on the free tier if your notifications contain anything sensitive. The self-hosted message history requires persistence configuration; the default in-memory mode does not survive a server restart. Neither of these is a reason not to use it.
At 32,000 stars and with active maintenance from its author, ntfy is a stable and well-regarded project. The Apache 2.0 license means you can embed it in commercial workflows, run it inside a client's infrastructure, or integrate it into a product without restrictions.
If you have an agent doing real work and you are not getting notifications when it finishes, ntfy is the fastest fix available.