ntfy (pronounce: notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, entirely without signup, cost or setup.


For this guide you should be familiar with the basic concepts of


Your ntfy URL needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
[isabell@stardust ~]$


Like a lot of Go software, ntfy is distributed as a single binary, which in this case is the server and the client component. Download ntfy’s latest release, verify the checksum specified in the respective .sha256 file and finally extract the files.

[isabell@stardust ~]$ mkdir ~/ntfy
[isabell@stardust ~]$ wget -O ntfy.tar.gz https://github.com/binwiederhier/ntfy/releases/download/v2.8.0/ntfy_2.8.0_linux_arm64.tar.gz
[isabell@stardust ~]$ tar --strip-components=1 -xzf ntfy.tar.gz -C ~/ntfy/
[isabell@stardust ~]$ rm ntfy.tar.gz
[isabell@stardust ~]$


Create a configuration file

Use your favourite editor to edit ~/ntfy/server/server.yml with the following settings. Make sure to replace the base-url and <username> with your own.

 base-url: https://isabell.uber.space
 listen-http: ":8008"
 cache-file: /home/<username>/ntfy/cache.db
 cache-duration: "12h"
 auth-file: "/home/<username>/ntfy/auth.db"
 auth-default-access: "deny-all"
 behind-proxy: true
 attachment-cache-dir: "/home/<username>/ntfy/attachments"
 attachment-total-size-limit: "1G"
 attachment-file-size-limit: "1M"
 attachment-expiry-duration: "3h"
 keepalive-interval: "45s"
 manager-interval: "2m"
 web-root: /
 upstream-base-url: "https://ntfy.sh"
 visitor-subscription-limit: 30
 log-level: INFO

Configure web server


ntfy will be running on port 8008.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Setup daemon

To start ntfy automatically and run it in the background, create ~/etc/services.d/ntfy.ini with the following content:

command=%(ENV_HOME)s/ntfy/ntfy serve --config %(ENV_HOME)s/ntfy/server/server.yml

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

Finishing installation

Point your browser to the URL you set up, e. g. https://isabell.uber.space.

Add admin user

To protect access to your ntfy instance, the default configuration above permits no access.

To add a new admin user:

[isabell@stardust ~]$ ./ntfy/ntfy user --config ~/ntfy/server/server.yml add --role=admin isabell
[isabell@stardust ~]$ ./ntfy/ntfy user --config ~/ntfy/server/server.yml list
user isabell (role: admin, tier: none)
- read-write access to all topics (admin role)
user * (role: anonymous, tier: none)
- no topic-specific permissions
- no access to any (other) topics (server config)
[isabell@stardust ~]$

To add a non-admin user, use --role=user:

[isabell@stardust ~]$ ./ntfy/ntfy user --config ~/ntfy/server/server.yml add --role=user isabell
[isabell@stardust ~]$

Add access token

To avoid having to use your credentials on multiple clients, generate an access token for your user:

[isabell@stardust ~]$ ./ntfy/ntfy token --config ~/ntfy/server/server.yml add --expires=2d isabell
token tk_<token-id> created for user isabell, expires <time when token expires>
[isabell@stardust ~]$

Set up UnifiedPush

UnifiedPush application servers (e.g. synapse, mastodon) need to have anonymous write access to the push message topic. Enable anonymous write-access to UnifiedPush topics (prefixed with up*):

[isabell@stardust ~]$ ./ntfy/ntfy access --config ~/ntfy/server/server.yml '*' 'up*' write-only
granted write-only access to topic up*

user * (role: anonymous, tier: none)
- write-only access to topic up*
- no access to any (other) topics (server config)
[isabell@stardust ~]$



Ntfy must be updated manually.

Tested with ntfy 1.28.0 Uberspace

Written by: jpmens <https://jpmens.net>