Arnecc: created initial page

2026-08-29T21:58:03Z

created initial page

New page

'''[https://ntfy.sh/ ntfy]''' is a HTTP-based pub-sub notification service. It allows sending notifications to a phone or desktop via scripts from any computer, and/or using a REST API. It can be used for free, with a paid plan or self-hosted. The latter is documented in this article.

== Installation ==

Enable the ntfy module in your configuration and define some basic options:

{{bc|1=
services.ntfy-sh = {
enable = true;
settings = {
base-url = "https://ntfy.yourdomain.com";
behind-proxy = true;
};
};
}}

You also should set up a virtual host via nginx or caddy:

{{bc|1=
services.nginx.virtualHosts = {
"ntfy.yourdomain.com" = {
forceSSL = true;
enableACME = true;
locations."/" = {
proxyPass = "http://localhost:2586";
proxyWebsockets = true; # Required for ntfy streaming
};
};
};
}}

If you haven't done so for other services, you will also need an [[ACME]] setup. A minimal working example:

{{bc|1=
security.ACME = {
acceptTerms = true;
defaults.email = <youremail>;
};
}}

Also note that you might need to restart the ACME service after first setup due to a bug:

{{ic|sudo systemctl restart acme-ntfy.yourdomain.com.service}}

=== Authentication (optional but recommended) ===

For a private instance you should restrict access. Set up a user database and default to denying all access:

{{bc|1=
services.ntfy-sh.settings = {
auth-file = "/var/lib/ntfy-sh/user.db";
auth-default-access = "deny-all";
enable-signup = false;
};
}}

Define users and access tokens (tokens can be generated with {{ic|ntfy token generate}}).

{{bc|1=
services.ntfy-sh.settings = {
auth-users = [
# <username>:<password-hash>:<role> role is "user" or "admin"
"admin:$2a$10$<bcrypt-hash>:admin"
"backup-service:$2a$10$<bcrypt-hash>:user"
];
auth-tokens = [
# <username>:<token>[:<optional free form label>]
"admin:tk_<token>"
"backup-service:tk_<token>:backup script token"
];
};
}}

Define an access control list (ACL). The format is {{ic|username:topic-pattern:access}}, where access is {{ic|read-write}}/{{ic|rw}}, {{ic|read-only}}/{{ic|ro}}, {{ic|write-only}}/{{ic|wo}} or {{ic|deny-all}}. The wildcard {{ic|*}} matches any number of characters in a topic pattern, and the special user {{ic|*}} means "everyone" (including anonymous):

{{bc|1=
services.ntfy-sh.settings = {
auth-access = [
"user:*:rw" # you can read & write everything
"backup-service:backups:*:rw" # only its own topics
];
};
}}

After a {{ic|nixos-rebuild switch}}, the {{ic|user.db}} is created automatically and the users/tokens/ACL entries are applied.

If your ntfy instance is private ({{ic|1=auth-default-access = "deny-all"}}), and you want to use it as a [https://unifiedpush.org/ UnifiedPush] push server (e.g. for [[MollySocket]] or Matrix/fediverse push), you must explicitly allow anonymous write access to the {{ic|up*}} topic prefix as application servers such as mollysocket are not registered users and cannot authenticate:

{{bc|1=
services.ntfy-sh.settings = {
auth-access = [
"*:up*:write-only" # anonymous app-servers may publish to UnifiedPush topics
];
};
}}

== Use ==

=== Publishing ===

Publishing is done via HTTP PUT/POST or the {{ic|ntfy}} CLI. Topics are created on the fly by publishing or subscribing to them, so for basic use no configuration is needed at all. Because there is no sign-up, a topic name is essentially a password. That's why you should pick something not easily guessable:

{{bc|1=
# Simple message (default priority)
curl -d "Backup finished" https://ntfy.yourdomain.com/mytopic

# With title, priority and tags
curl -H "Title: Backup" -H "Priority: high" -H "Tags: warning" \
-d "Backup of server failed" https://ntfy.yourdomain.com/backups

# From a script
ntfy publish mytopic "Something has happened"
}}

If access control is enabled and the topic does not allow anonymous writes, authenticate with a token ({{ic|ntfy://:TOKEN@DOMAIN/TOPIC}} or {{ic|Authorization: Bearer}}):

{{bc|1=
curl -H "Authorization: Bearer tk_..." -d "Backup finished" \
https://ntfy.yourdomain.com/backups
}}

=== Subscribing ===

Subscribe via the web app ([https://ntfy.sh/app ntfy.sh/app] on your own instance), the mobile app, or the API. The subscription API supports plain HTTP streams (JSON, SSE or raw) and WebSockets:

{{bc|1=
# Stream as JSON lines
curl -s https://ntfy.yourdomain.com/mytopic/json

# Server-sent events
curl -s https://ntfy.yourdomain.com/mytopic/sse

# WebSocket (wss://)
wscat -c wss://ntfy.yourdomain.com/mytopic/ws
}}

Android (Play Store + F-Droid) and iOS apps are available, too. On Android, the app can also act as a [https://unifiedpush.org/ UnifiedPush] distributor, forwarding pushes to other apps (e.g. Molly/[[MollySocket]]). On NixOS, the {{ic|ntfy}} package can be used to subscribe to topics and receive notifications on your desktop.

== See also ==

* [[MollySocket]] - Use ntfy to provide notifications for the Signal-fork [https://molly.im/ Molly]

== References ==

* '''Full documentation:''' [https://docs.ntfy.sh/ ntfy docs], [https://docs.ntfy.sh/config/ configuration], [https://docs.ntfy.sh/publish/ publishing].

[[Category:Server]]

Ntfy - Revision history

Arnecc: created initial page