A ntfy.sh desktop client built with Electron which supports Windows, Linux, and MacOSX. This client rests in your taskbar tray and allows you to receive push notifications to your desktop without requiring you to leave your browser open.
This project allows you to access the official free / paid notification service ntfy.sh, or your own self-hosted version of ntfy from within a desktop application which utilizes Electron as the wrapper.
ntfy.sh (pronounced "notify") is a simple HTTP-based pub-sub notification service. With ntfy, you can send notifications to your phone or desktop via scripts from any computer, without having to sign up or pay any fees. If you'd like to run your own instance of the service, you can easily do so since ntfy is open source.
To install Ntfy on your system, visit the following links:
- Supports both the official ntfy.sh website / service or your own self-hosted instance
- To self-host, you must install Ntfy server on a local machine.
- View docs at https://docs.ntfy.sh/install/
- Two modes for minimizing app, configure in settings
- Close button exits app completely; OR
- Close button sends app to tray. Right-click tray icon to quit / show app
- Start app minimized
- Shortcut key-binds
- Can disable the keyboard shortcuts
- Receive push notifications from ntfy server to desktop
- Ability to adjust polling rate
- Modify Datetime format
- Optional persistent (sticky) notifications which require user interaction to clear
- Topic filtering
- Supports Ntfy API token
- Includes command-line arguments
To use this desktop client, you will be required to either have an Ntfy.sh account, or you must host your own instance of the Ntfy.sh server to pull notifications from.
You can install your own self-hosted copy of Ntfy server from:
Be aware that the official ntfy.sh website will rate-limit users who have not purchased a paid package. Out of box, this ntfy-desktop client polls for new notifications every 30 seconds; if you are on the free plan and decrease this timer in the desktop client settings, you will get an error saying that you have gone over your rate-limit.
If you are self-hosting your own copy of Ntfy, you must open the Ntfy Desktop client, click the top menu item App, go down to Settings and then click Instance. You must set your instance URL to your personal self-hosted instance. To set your instance URL back to the official ntfy server, clear the URL box and save.
You can set the polling rate lower without any limitations or rate limits:
This section explains how to use ntfy-desktop once you have it ready to go on your system.
The following keybinds can be used within ntfy-desktop:
| Key(s) | Description |
|---|---|
CTRL + R |
Refresh page |
CTRL + Q |
Quit application |
CTRL + M |
Minimize to tray |
CTRL + = |
Zoom in |
CTRL + - |
Zoom out |
CTRL + 0 |
Zoom reset |
CTRL + SHIFT + I |
Developer tools |
F12 |
Developer tools |
CTRL + G |
Show General settings window |
CTRL + I |
Show URL / Instance window |
CTRL + T |
Show API Token settings window |
CTRL + SHIFT + T |
Show Topics settings window |
CTRL + N |
Show Notifications settings window |
Note
Hotkeys are disabled by default. To enable hotkeys, select App in the top menu, and select Settings -> General.
Enable Allow usage of hotkeys to navigate
This client allows you to utilize the following command-line arguments with ntfy-desktop:
| Argument | Description | Available as setting |
|---|---|---|
--hidden |
Start app hidden in tray, suitable for auto-starting on system login/boot | ✅ |
--hotkey |
Start app with hotkeys enabled | ✅ |
--quit |
Top-right close button will completely exit app instead of minimize to tray | ✅ |
--dev |
Start app with developer tools in App menu |
✅ |
If you are running ntfy-desktop from node, you can pass arguments using the following example:
npm run start -- --hidden --hotkeyThere are numerous ways to build this application.
This method makes use of the build.bat and build.sh scripts provided in this repository. Find your operating system below and follow the instructions:
Run the following commands to install NodeJS + NPM, and then Ntfy Desktop:
# Install NodeJS and NPM
sudo apt update
sudo apt install git nodejs npm wine64
# Clone ntfy-desktop repo, make sure you are in an EMPTY folder:
mkdir ntfy-desktop && cd ntfy-desktop/
git clone https://github.com/aetherinox/ntfy-desktop.git .
npm install
npm install -g electron-packager
sudo ln -s /usr/bin/wine /usr/bin/wine64
sudo chmod +x build.sh
# build ntfy-desktop
./build.shInstall NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
Next, run the following commands in Powershell or Windows Command Prompt:
# Clone ntfy-desktop repo, make sure you are in an EMPTY folder:
mkdir ntfy-desktop && cd ntfy-desktop/
git clone https://github.com/aetherinox/ntfy-desktop.git .
npm install
npm install -g electron
# build ntfy
./build.batInstall NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
Install Git on your system next:
Open your Terminal app and run the following commands:
# Clone ntfy-desktop repo, make sure you are in an EMPTY folder:
mkdir ntfy-desktop && cd ntfy-desktop/
git clone https://github.com/aetherinox/ntfy-desktop.git .
npm install
npm install -g electron-packager
sudo chmod +x build.sh
# build ntfy-desktop
./build.shYou can also build your own copy of ntfy-desktop by executing the included package.json run commands.
To run the npm commands, you must install NodeJS and NPM on your system. To install them, visit:
The package.json includes the commands listed below. Because the build commands have dynamic variables; you must run the command based on what operating system you are building from.
If you are building ntfy-desktop from a Windows machine:
npm run build:win:windowsnpm run build:win:linuxnpm run build:win:mac
If you are building ntfy-desktop from a Linux or MacOS machine:
npm run build:lin:windowsnpm run build:lin:linuxnpm run build:lin:mac
Run the following commands to install NodeJS + NPM, and then Ntfy Desktop:
# Install NodeJS and NPM
sudo apt update
sudo apt install git nodejs npm wine64
# Clone ntfy-desktop repo, make sure you are in an EMPTY folder:
mkdir ntfy-desktop && cd ntfy-desktop/
git clone https://github.com/aetherinox/ntfy-desktop.git .
npm install
npm install -g electron-packager
sudo ln -s /usr/bin/wine /usr/bin/wine64
# build ntfy-desktop from Windows machine
npm run build:win:linux
# build ntfy-desktop from Linux machine
npm run build:lin:linuxInstall NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
Next, run the following commands in Powershell or Windows Command Prompt:
# Clone ntfy-desktop repo, make sure you are in an EMPTY folder:
mkdir ntfy-desktop && cd ntfy-desktop/
git clone https://github.com/aetherinox/ntfy-desktop.git .
npm install
npm install -g electron
# build ntfy-desktop from Windows machine
npm run build:win:windows
# build ntfy-desktop from Linux machine
npm run build:lin:windowsInstall NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
Install Git on your system next:
Open your Terminal app and run the following commands:
# Clone ntfy-desktop repo, make sure you are in an EMPTY folder:
mkdir ntfy-desktop && cd ntfy-desktop/
git clone https://github.com/aetherinox/ntfy-desktop.git .
npm install
npm install -g electron-packager
# build ntfy-desktop from Windows machine
npm run build:win:mac
# build ntfy-desktop from Linux machine
npm run build:lin:macThis repository contains tests in order to test the functionality of this project. We utilize a Github workflow to handle the automation, however, you can run the tests locally.
In order to run these tests, you must have some dependencies installed on your system or runner:
sudo apt install xvfb -y
npm install
npx playwright install-depsIf you do not run the command playwright install-deps; then you will need to install all of the dependencies manually with the command:
sudo apt install xvfb -y
sudo apt-get install libasound2 libxslt-dev woff2 libevent-dev libopus0 \
libopus-dev libwebpdemux2 libharfbuzz-dev libharfbuzz0b libwebp-dev \
libenchant-2-dev libsecret-1-0 libsecret-1-dev libglib2.0-dev libhyphen0 \
libglfw3-dev libgles2-mesa-dev libudev1 libevdev2 libgles2-mesa yasm \
libudev1 libudev-dev libgudev-1.0-0 libx264-dev libgconf-2-4 libatk1.0-0 \
libatk-bridge2.0-0 libgdk-pixbuf2.0-0 libgtk-3-0 libgbm-dev libnss3-dev \
libxss-dev -y
npx playwright installYou can fork this repository and run the Github workflow
In order for the workflow to work, your Github or self-hosted runner must have numerous dependencies installed. Ensure you do not remove the npm install and apt install commands from the workflow; otherwise the tests will fail.
You can manually test this project by running the command:
npm run testYou should see numerous windows open and multiple copies of Ntfy Desktop start up. This is normal, and is the test checking out the functionality of the application.
If you want to run the tests from a CI without having a GUI available to see the tests; you can run the command:
xvfb-run --auto-servernum --server-args="-screen 0 1280x960x24" npx playwright test --trace onIf you want to run the tests, while having Electron running in debug / verbose mode; run the command:
DISPLAY=:0 DEBUG=pw:browser xvfb-run --auto-servernum --server-args="-screen 0 1280x960x24" npx playwright test --trace onThe tests should show something similar to the following:
[chromium] › tests/main.spec.js:65:1 › ✅ ensure interface can fully load
✅ Open New Window: About
[webkit] › tests/main.spec.js:65:1 › ✅ ensure interface can fully load
✅ Open New Window: About
[chromium] › tests/main.spec.js:65:1 › ✅ ensure interface can fully load
✅ Saved screenshot: test-results/fullload_1749458422355.png
[webkit] › tests/main.spec.js:65:1 › ✅ ensure interface can fully load
[SubscriptionManager] No browser subscription currently exists, so web push was never enabled or the notification permission was removed. Skipping.
✅ Saved screenshot: test-results/fullload_1749458422373.png
[firefox] › tests/main.spec.js:143:1 › ✅ fail to sign into invalid account
ntfy
[chromium] › tests/main.spec.js:143:1 › ✅ fail to sign into invalid account
ntfy
[webkit] › tests/main.spec.js:143:1 › ✅ fail to sign into invalid account
ntfy
9 passed (15.3s)
To open last HTML report run:
npx playwright show-reportThese steps allow you to validate the files sha256sum.txt.asc, sha1sum.txt.asc, and sha256sum.sig which we provide with every release.
Validating these files helps ensure that the actual .zip or binary files you have downloaded indeed came from the real developer. Before you start reading the sections below; ensure you have the following packages installed:
- GPG
- sha1sum
- sha256sum
You can install these by running the commands:
# Ubuntu / Debian Systems
sudo apt update
sudo apt install gpg gnupg sha1sum sha256sum
# Fedora / Redhat
(yum | or | dnf ) install gpg gnupgEach release includes two .sig files; these are known as a GPG Detached Signature.
- sha1sum.sig
- sha256sum.sig
To validate that these signatures are good, download each of the files to your local machine:
# sha1sum
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha1sum.sig
# sha256sum
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha256sum.sigNext, you will need the two associated files:
- sha1sum.txt.asc
- sha256sum.txt.asc
To download these, run the commands:
# sha1sum.txt.asc
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha1sum.txt.asc
# sha256sum.txt.asc
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha256sum.txt.ascNow we can validate that these files indeed came from the original developer; run the command:
gpg --verify sha1sum.sig sha1sum.txt.ascYou should see the output:
gpg: using RSA key 6921C2D3F6AE1188B7721C72F397BC89486A29A6
gpg: Good signature from "Binary Ninja (RSA 4096) <thebinaryninja@proton.me>" [unknown]
Primary key fingerprint: E8BA 8C94 B334 1673 0D8C 05C2 5769 7A1C BA63 B9FE
Subkey fingerprint: 6921 C2D3 F6AE 1188 B772 1C72 F397 BC89 486A 29A6Now validate the sha256sum.sig with the sha256sum.txt.asc:
gpg --verify sha256sum.sig sha256sum.txt.ascYou should see the output:
gpg: using RSA key 6921C2D3F6AE1188B7721C72F397BC89486A29A6
gpg: Good signature from "Binary Ninja (RSA 4096) <thebinaryninja@proton.me>" [unknown]
Primary key fingerprint: E8BA 8C94 B334 1673 0D8C 05C2 5769 7A1C BA63 B9FE
Subkey fingerprint: 6921 C2D3 F6AE 1188 B772 1C72 F397 BC89 486A 29A6If you get the above results; you have validated the signature files.
This section explains how you can validate the downloaded .zip files and see if they are indeed authentic from the original developer. Before you can validate these files, you need to download the public GPG key we use when we sign releases. You can download it by running the following command:
curl -s https://github.com/BinaryServ.gpg | gpg --importDownload the sha256sum.txt.asc and validate the file itself:
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha256sum.txt.asc
gpg --verify sha256sum.txt.ascYou should see the following. The value 6921C2D3F6AE1188B7721C72F397BC89486A29A6 is the key's fingerprint.
gpg: Signature made Mon 01 Jun 2025 00:00:00 UTC
gpg: using RSA key 6921C2D3F6AE1188B7721C72F397BC89486A29A6
gpg: Good signature from "Binary Ninja (RSA 4096) <thebinaryninja@proton.me>" [ultimate]You can view your existing GPG key fingerprints by running:
gpg --list-keys --keyid-format=long --fingerprint --with-fingerprintThis will allow you to see where the 692XXXXX value comes from:
pub rsa4096 2025-04-21 [C]
E8BA 8C94 B334 1673 0D8C 05C2 5769 7A1C BA63 B9FE
uid [ unknown] Binary Ninja (RSA 4096) <thebinaryninja@proton.me>
sub rsa4096 2025-04-21 [S]
>>>> 6921 C2D3 F6AE 1188 B772 1C72 F397 BC89 486A 29A6
sub rsa4096 2025-04-21 [E]
25E9 AFEC C12F 2072 AA6E D5AB B077 63D0 A12F 0ED8
sub rsa4096 2025-04-21 [A]
AD79 A1EA CE17 962F B4ED B30A DBA8 EA76 62FC 54E2Next, download the sha256sum.sig
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha256sum.sigTo validate the .sig file and your sha256sum file, run the command:
gpg --verify sha256sum.sig sha256sum.txt.ascYou should see:
gpg: using RSA key 6921C2D3F6AE1188B7721C72F397BC89486A29A6
gpg: Good signature from "Binary Ninja (RSA 4096) <thebinaryninja@proton.me>" [unknown]
Primary key fingerprint: E8BA 8C94 B334 1673 0D8C 05C2 5769 7A1C BA63 B9FE
Subkey fingerprint: 6921 C2D3 F6AE 1188 B772 1C72 F397 BC89 486A 29A6You can now validate the sha256sum.txt.asc file against the files you have downloaded from our repository. In order to verify that the files are legit, you must download them from the Releases page. They end with the extension .zip. You can also download them using wget. Make sure you download the zip files to the same folder where you downloaded the sha256sum.txt.asc and sha256sum.sig
# Download ntfy-desktop-2.1.1-darwin-amd64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-darwin-amd64.zip
# Download ntfy-desktop-2.1.1-darwin-arm64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-darwin-arm64.zip
# Download ntfy-desktop-2.1.1-linux-amd64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-linux-amd64.zip
# Download ntfy-desktop-2.1.1-linux-arm64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-linux-arm64.zip
# Download ntfy-desktop-2.1.1-linux-armv7l.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-linux-armv7l.zip
# Download ntfy-desktop-2.1.1-win32-amd64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-win32-amd64.zip
# Download ntfy-desktop-2.1.1-win32-arm64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-win32-arm64.zip
# Download ntfy-desktop-2.1.1-win32-ia32.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-win32-ia32.zipNext, extract the hashes from the hash digest sha256sum.txt.asc file by running the command:
gpg --output sha256sum.txt --verify sha256sum.txt.ascThe command above will create a new file called sha256sum.txt, now run that file with the program sha256sum:
sha256sum --check sha256sum.txtWhich will output:
# Successful validation
ntfy-desktop-2.1.1-win32-ia32.zip: OK
ntfy-desktop-2.1.1-darwin-amd64.zip: OK
ntfy-desktop-2.1.1-win32-amd64.zip: OK
ntfy-desktop-2.1.1-win32-arm64.zip: OK
ntfy-desktop-2.1.1-darwin-arm64.zip: OK
ntfy-desktop-2.1.1-linux-armv7l.zip: OK
ntfy-desktop-2.1.1-linux-amd64.zip: OK
ntfy-desktop-2.1.1-linux-arm64.zip: OK
# Files missing for validation
ntfy-desktop-2.1.1-linux-arm64.zip: FAILED open or read
# File did not pass validation
ntfy-desktop-2.1.1-linux-arm64.zip: FAILEDIf you see FAILED and the files are indeed there, ensure you downloaded them from our repository and not somewhere else.
If you see OK; this means the files are valid.
This section explains how you can validate the downloaded .zip files and see if they are indeed authentic from the original developer. Validating the sha1sum.txt.asc is similar to the sha256sum.txt.asc, first, download the public GPG key we use when we sign releases. You can download it by running the following command:
curl -s https://github.com/BinaryServ.gpg | gpg --importNext, download the sha1sum.txt.asc file:
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha1sum.txt.ascNow verify that the sha1sum.txt.asc is properly signed:
gpg --verify sha1sum.txt.ascYou should see the following. The value 6921C2D3F6AE1188B7721C72F397BC89486A29A6 is the key's fingerprint.
gpg: Signature made Mon 01 Jun 2025 00:00:00 UTC
gpg: using RSA key 6921C2D3F6AE1188B7721C72F397BC89486A29A6
gpg: Good signature from "Binary Ninja (RSA 4096) <thebinaryninja@proton.me>" [ultimate]You can view your existing GPG key fingerprints by running:
gpg --list-keys --keyid-format=long --fingerprint --with-fingerprintThis will allow you to see where the 692XXXXX value comes from:
pub rsa4096 2025-04-21 [C]
E8BA 8C94 B334 1673 0D8C 05C2 5769 7A1C BA63 B9FE
uid [ unknown] Binary Ninja (RSA 4096) <thebinaryninja@proton.me>
sub rsa4096 2025-04-21 [S]
>>>> 6921 C2D3 F6AE 1188 B772 1C72 F397 BC89 486A 29A6
sub rsa4096 2025-04-21 [E]
25E9 AFEC C12F 2072 AA6E D5AB B077 63D0 A12F 0ED8
sub rsa4096 2025-04-21 [A]
AD79 A1EA CE17 962F B4ED B30A DBA8 EA76 62FC 54E2Next, download the sha1sum.sig
wget https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/sha1sum.sigTo validate the sha1sum.sig file and your sha1sum.txt.asc file, run the command:
gpg --verify sha1sum.sig sha1sum.txt.ascYou should see:
gpg: using RSA key 6921C2D3F6AE1188B7721C72F397BC89486A29A6
gpg: Good signature from "Binary Ninja (RSA 4096) <thebinaryninja@proton.me>" [unknown]
Primary key fingerprint: E8BA 8C94 B334 1673 0D8C 05C2 5769 7A1C BA63 B9FE
Subkey fingerprint: 6921 C2D3 F6AE 1188 B772 1C72 F397 BC89 486A 29A6You can now validate the sha1sum.txt.asc file against the files you have downloaded from our repository. In order to verify that the files are legit, you must download them from the Releases page. They end with the extension .zip. You can also download them using wget. Make sure you download the zip files to the same folder where you downloaded the sha1sum.txt.asc and sha1sum.sig
# Download ntfy-desktop-2.1.1-darwin-amd64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-darwin-amd64.zip
# Download ntfy-desktop-2.1.1-darwin-arm64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-darwin-arm64.zip
# Download ntfy-desktop-2.1.1-linux-amd64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-linux-amd64.zip
# Download ntfy-desktop-2.1.1-linux-arm64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-linux-arm64.zip
# Download ntfy-desktop-2.1.1-linux-armv7l.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-linux-armv7l.zip
# Download ntfy-desktop-2.1.1-win32-amd64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-win32-amd64.zip
# Download ntfy-desktop-2.1.1-win32-arm64.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-win32-arm64.zip
# Download ntfy-desktop-2.1.1-win32-ia32.zip
wget \
https://github.com/Aetherinox/ntfy-desktop/releases/download/2.1.1/ntfy-desktop-2.1.1-win32-ia32.zipNext, extract the hashes from the hash digest sha1sum.txt.asc file by running the command:
gpg --output sha1sum.txt --verify sha1sum.txt.ascThe command above will create a new file called sha1sum.txt, now run that file with the program sha1sum:
sha1sum --check sha1sum.txtWhich will output:
# Successful validation
ntfy-desktop-2.1.1-win32-ia32.zip: OK
ntfy-desktop-2.1.1-darwin-amd64.zip: OK
ntfy-desktop-2.1.1-win32-amd64.zip: OK
ntfy-desktop-2.1.1-win32-arm64.zip: OK
ntfy-desktop-2.1.1-darwin-arm64.zip: OK
ntfy-desktop-2.1.1-linux-armv7l.zip: OK
ntfy-desktop-2.1.1-linux-amd64.zip: OK
ntfy-desktop-2.1.1-linux-arm64.zip: OK
# Files missing for validation
ntfy-desktop-2.1.1-linux-arm64.zip: FAILED open or read
# File did not pass validation
ntfy-desktop-2.1.1-linux-arm64.zip: FAILEDIf you see FAILED and the files are indeed there, ensure you downloaded them from our repository and not somewhere else.
If you see OK; this means the files are valid.
Ntfy Desktop relies on the following packages, some of these are also made by us:
| Package | Language | Version | Description |
|---|---|---|---|
| ntfy-toast | C++ |  |
Command-line application which handles toast notifications on Windows 8 and newer |
| toasted-notifier | Javascript |  |
Node package which acts as a wrapper to send notification data between Ntfy Desktop and ntfy-toast |
| electron-plugin-prompts | Javascript |  |
Node package which allows for more detailed and customizable interface forms |
We are always looking for contributors. If you feel that you can provide something useful to this project, then we'd love to review your suggestion. Before submitting your contribution, please review the following resources:
Want to help but can't write code?
- Review active questions by our community and answer the ones you know.
The following people have helped get this project going:
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
![@renovate[bot]](https://avatars.githubusercontent.com/in/2740?s=64&v=4){kind=small}