• About

• Usage

• Build

• Tests

• Linting
• Signed Releases

• Dependencies
• Contributors ✨

About

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.

What is Ntfy

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 Ntfy API token
• Taskbar unread message count / count
• Includes command-line arguments

Self-hosted vs Ntfy.sh

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:

• https://github.com/binwiederhier/ntfy/releases

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:

Architecture Outline

We provide numerous different architectures you can download this app for. Below is a list:

| Architecture | Bits | Devices / Examples | | ------------ | ---- | -------------------------------------------------------------- | | ARMv7l | 32 | Raspberry Pi 2 & 3 (32-bit), Nexus 7, PS Vita (ARM Cortex-A9) | | ARMv6l | 32 | Raspberry Pi 1, Pi Zero, iPhone 3G | | ARM64 | 64 | Apple M1/M2/M3 Macs, Raspberry Pi 4 (64-bit OS), iPhone 5s+ | | AMD64 | 64 | Modern PCs, PS5, Xbox Series X, Steam Deck | | I386 | 32 | 386-era PCs, Windows 95 machines, Compaq Deskpro, old netbooks | | IA32 | 32 | Same as i386; Intel Atom netbooks, Pentium 4 PCs |

Usage

This section explains how to use ntfy-desktop once you have it ready to go on your system.

Key Binds

| 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

CLI Arguments

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 | ✅ | | --devtools | Start app with developer tools in App menu | ✅ | | --env | Define startup environment | ❌ |

If you are running ntfy-desktop from node, you can pass arguments using the following example:

``shell ignore npm run start -- --hidden --hotkey

<br />

If using the pre-built binaries, pass arguments by opening your terminal / command prompt, and passing the arguments using:

<br />

<br />
Build
There are numerous ways to build this application.
<br />
Method: Build Script
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:

Windows
Linux
MacOSX
<br />
Windows
Install NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
https://nodejs.org/en/download
<br />
Next, run the following commands in Powershell or Windows Command Prompt:

<br />
<br />
Linux
Run the following commands to install NodeJS + NPM, and then Ntfy Desktop:

<br />
<br />
MacOSX
Install NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top.
<br />
To install node / npm, download from:
https://nodejs.org/en/download
<br />

To install Git on your system:
https://git-scm.com/downloads/mac
<br />
Open your Terminal app and run the following commands:
<br />

<br />
<br />
Method: Package.json Command
You can also build your own copy of ntfy-desktop by executing the included package.json run commands.

Windows
Linux
MacOSX
<br />
Summary
To run the npm commands, you must install NodeJS and NPM on your system. To install them, visit:

https://nodejs.org/en/download
<br />
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:windows

npm run build:win:linux

npm run build:win:mac

<br />
If you are building ntfy-desktop from a Linux or MacOS machine:
npm run build:lin:windows

npm run build:lin:linux

npm run build:lin:mac

<br />
<br />
Windows
Install NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
https://nodejs.org/en/download
<br />
Next, run the following commands in Powershell or Windows Command Prompt:

<br >
<br >
Linux
Run the following commands to install NodeJS + NPM, and then Ntfy Desktop:

<br />
<br />
MacOSX
Install NodeJS with NPM by going to the following URL. Make sure to select your current operating system at the top:
https://nodejs.org/en/download
<br />
Install Git on your system next:
https://git-scm.com/downloads/mac
<br />
Open your Terminal app and run the following commands:

<br />

<br />
Tests
This 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.
<br />
In order to run these tests, you must have some dependencies installed on your system or runner:

<br />

If you do not run the command playwright install-deps; then you will need to install all of the dependencies manually with the command:

<br />

Github Workflow
You can fork this repository and run the included Github workflows
https://github.com/Aetherinox/ntfy-desktop/blob/f794bb835cb68a2b6da74d9161e7432c673179ea/.github/workflows/npm-tests.yml
<br />

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.

<br />
Manual Test
You can also run the included tests manually without a Github workflow with the instructions below.
<br />
Playwright Tests
These tests specifically check the Electron app itself. They will attempt to open ntfy-desktop and make sure the application is in working order. These tests do NOT test the back-end code of the app.

<br />

You 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.
<br />
If you want to run the tests from a CI without having a GUI available to see the tests; you can run the command:

<br />

If you want to run the tests, while having Electron running in debug / verbose mode; run the command:

<br />

The tests should show something similar to the following:

<br />
<br />

Vitest Tests
These tests check the back-end functionality of the app, including a lot of the functions that the source code comes with.

<br />

The results for the tests will be printed in your terminal / command prompt.

<br />


<br />
Linting
This node package comes with ESlint, and a set of rules which should be followed. If you have intentions of creating new features and contributing to this repository; you must follow these linter rules. You can check the current status of your code by running:

<br />

Any failures will be reported in console:

<br />

You must fix these before submitting a contribution. You can opt to automatically fix errors by running the command:

<br />

> [!WARNING]
> Opting to automatically fix linting errors may result in mis-aligned brackets. Make sure these are fixed before submitting any pull requests.
<br />

<br />
Signed Releases
These 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
<br />
You can install these by running the commands:

<br />
Validate .Sig
Each release includes two .sig files; these are known as a GPG Detached Signature.

sha1sum.sig
sha256sum.sig
<br />
To validate that these signatures are good, download each of the files to your local machine:

<br />
Next, you will need the two associated files:
sha1sum.txt.asc
sha256sum.txt.asc
<br />
To download these, run the commands:

<br />
Now we can validate that these files indeed came from the original developer; run the command:

<br />

You should see the output:

<br />

Now validate the sha256sum.sig with the sha256sum.txt.asc:

<br />

You should see the output:

<br />

If you get the above results; you have validated the signature files.
<br />
<br />
Validate SHA256SUM
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:

<br />

Download the sha256sum.txt.asc and validate the file itself:

<br />

You should see the following. The value 6921C2D3F6AE1188B7721C72F397BC89486A29A6 is the key's fingerprint.

<br />

You can view your existing GPG key fingerprints by running:

<br />

This will allow you to see where the 692XXXXX value comes from:

<br />

Next, download the sha256sum.sig

<br />

To validate the .sig file and your sha256sum file, run the command:

<br />

You should see:

<br />

You 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

<br />
Next, extract the hashes from the hash digest sha256sum.txt.asc file by running the command:

<br />

The command above will create a new file called sha256sum.txt, now run that file with the program sha256sum:

<br />

Which will output:

<br />
If you see FAILED and the files are indeed there, ensure you downloaded them from our repository and not somewhere else.

<br />
If you see OK; this means the files are valid.

<br />
Validate SHA1SUM
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:

<br />

Next, download the sha1sum.txt.asc file:

<br />

Now verify that the sha1sum.txt.asc is properly signed:

<br />

You should see the following. The value 6921C2D3F6AE1188B7721C72F397BC89486A29A6 is the key's fingerprint.

<br />

You can view your existing GPG key fingerprints by running:

<br />

This will allow you to see where the 692XXXXX value comes from:

<br />

Next, download the sha1sum.sig

<br />

To validate the sha1sum.sig file and your sha1sum.txt.asc file, run the command:

<br />

You should see:

<br />

You 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

<br />
Next, extract the hashes from the hash digest sha1sum.txt.asc file by running the command:

<br />

The command above will create a new file called sha1sum.txt, now run that file with the program sha1sum:

<br />

Which will output:

If 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.

Dependencies

Ntfy Desktop relies on the following packages, some of these are also made by us:

| Package | Language | Version | Description | --- | --- | --- | --- | | ntfy-toast | C++ | [![Version][ntfy-toast-github-version-img]][ntfy-toast-github-version-uri] | Command-line application which handles toast notifications on Windows 8 and newer | | toasted-notifier | Javascript | [![Version][toasted-notifier-npm-version-img]][toasted-notifier-npm-version-uri] | Node package which acts as a wrapper to send notification data between Ntfy Desktop and ntfy-toast | | electron-plugin-prompts | Javascript | [![Version][plugin-prompts-npm-version-img]][plugin-prompts-npm-version-uri] | Node package which allows for more detailed and customizable interface forms |

Contributors ✨

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:

• Pull Request Procedure
• Contributor Policy

Want to help but can't write code?

• Review active questions by our community and answer the ones you know.

!Alt

The following people have helped get this project going:

[![Contributors][contribs-all-img]](#contributors-)

Aetherinox 💻 📆

[plugin-prompts-npm-version-img]: https://img.shields.io/npm/v/electron-plugin-prompts?logo=npm&label=Version&color=ba5225 [plugin-prompts-npm-version-uri]: https://npmjs.com/package/electron-plugin-prompts

[toasted-notifier-npm-version-img]: https://img.shields.io/npm/v/toasted-notifier?logo=npm&label=Version&color=ba5225 [toasted-notifier-npm-version-uri]: https://npmjs.com/package/toasted-notifier

[ntfy-toast-github-version-img]: https://img.shields.io/github/v/tag/aetherinox/ntfy-toast?logo=GitHub&label=Version&color=ba5225 [ntfy-toast-github-version-uri]: https://github.com/aetherinox/ntfy-toast/releases

[general-npmjs-uri]: https://npmjs.com [general-nodejs-uri]: https://nodejs.org [general-npmtrends-uri]: http://npmtrends.com/ntfy-desktop

[github-version-img]: https://img.shields.io/github/v/tag/aetherinox/ntfy-desktop?logo=GitHub&label=Version&color=ba5225 [github-version-uri]: https://github.com/aetherinox/ntfy-desktop/releases

[npm-version-img]: https://img.shields.io/npm/v/ntfy-desktop?logo=npm&label=Version&color=ba5225 [npm-version-uri]: https://npmjs.com/package/ntfy-desktop

[pypi-version-img]: https://img.shields.io/pypi/v/ntfy-desktop [pypi-version-uri]: https://pypi.org/project/ntfy-desktop/

[license-mit-img]: https://img.shields.io/badge/MIT-FFF?logo=creativecommons&logoColor=FFFFFF&label=License&color=9d29a0 [license-mit-uri]: https://github.com/aetherinox/ntfy-desktop/blob/main/LICENSE

[github-downloads-img]: https://img.shields.io/github/downloads/aetherinox/ntfy-desktop/total?logo=github&logoColor=FFFFFF&label=Downloads&color=376892 [github-downloads-uri]: https://github.com/aetherinox/ntfy-desktop/releases

[npmjs-downloads-img]: https://img.shields.io/npm/dw/%40aetherinox%2Fntfy-desktop?logo=npm&&label=Downloads&color=376892 [npmjs-downloads-uri]: https://npmjs.com/package/ntfy-desktop

[github-size-img]: https://img.shields.io/github/repo-size/aetherinox/ntfy-desktop?logo=github&label=Size&color=59702a [github-size-uri]: https://github.com/aetherinox/ntfy-desktop/releases

[npmjs-size-img]: https://img.shields.io/npm/unpacked-size/ntfy-desktop/latest?logo=npm&label=Size&color=59702a [npmjs-size-uri]: https://npmjs.com/package/ntfy-desktop

[codecov-coverage-img]: https://img.shields.io/codecov/c/github/aetherinox/ntfy-desktop?token=MPAVASGIOG&logo=codecov&logoColor=FFFFFF&label=Coverage&color=354b9e [codecov-coverage-uri]: https://codecov.io/github/aetherinox/ntfy-desktop

[contribs-all-img]: https://img.shields.io/github/all-contributors/aetherinox/ntfy-desktop?logo=contributorcovenant&color=de1f6f&label=contributors [contribs-all-uri]: https://github.com/all-contributors/all-contributors

[github-build-img]: https://img.shields.io/github/actions/workflow/status/aetherinox/ntfy-desktop/npm-build.yml?logo=github&logoColor=FFFFFF&label=Build&color=%23278b30 [github-build-uri]: https://github.com/aetherinox/ntfy-desktop/actions/workflows/npm-build.yml

[github-build-pypi-img]: https://img.shields.io/github/actions/workflow/status/aetherinox/ntfy-desktop/app-pypi.yml?logo=github&logoColor=FFFFFF&label=Build&color=%23278b30 [github-build-pypi-uri]: https://github.com/aetherinox/ntfy-desktop/actions/workflows/app-pypi.yml

[github-tests-img]: https://img.shields.io/github/actions/workflow/status/aetherinox/ntfy-desktop/npm-tests.yml?logo=github&label=Tests&color=2c6488 [github-tests-uri]: https://github.com/aetherinox/ntfy-desktop/actions/workflows/npm-tests.yml?logo=github&label=Tests&color=2c6488 [github-tests-uri]: https://github.com/aetherinox/ntfy-desktop/actions/workflows/app-tests.yml.yml

[github-commit-img]: https://img.shields.io/github/last-commit/aetherinox/ntfy-desktop?logo=conventionalcommits&logoColor=FFFFFF&label=Last%20Commit&color=313131 [github-commit-uri]: https://github.com/aetherinox/ntfy-desktop/commits/main/