nextdns-linux-trayicon/README.md

NextDNS Linux Trayicon

This small Python script and .desktop file add a quick toggle to the desktop environment's system tray.

Prerequisites

1. NextDNS CLI: The script controls the nextdns service. If you haven't installed it yet:

   sh -c 'curl -sL https://nextdns.io/install | sh'
   

2. Python 3 & PyQt6: The interface is built using Python 3 and the Qt6 toolkit. (This is installed by default on (K)ubuntu.)

   sudo apt update
   sudo apt install python3 python3-pyqt6
   

3. Polkit Agent: The script uses pkexec to handle start/stop commands safely. Most desktop environments (KDE, GNOME, XFCE) come with this pre-installed.

Installation

Preferred (single command):

./install.sh

Enable autostart during install:

./install.sh --autostart

Uninstall

./uninstall.sh

Preview what would be removed:

./uninstall.sh --dry-run

1. Copy the files to your home directory:

   # Create directories if they don't exist
   mkdir -p ~/.local/bin ~/.local/share/applications ~/.local/share/icons
   # Copy the specific files
   cp home/.local/bin/nextdns-tray ~/.local/bin/
   cp home/.local/share/applications/nextdns-tray.desktop ~/.local/share/applications/
   cp home/.local/share/icons/nextdns.png ~/.local/share/icons/
   

2. Make the script executable

   chmod +x ~/.local/bin/nextdns-tray
   

   The bundled nextdns-tray.desktop launcher runs nextdns-tray directly (via PATH) so it is not tied to any repository location. If your desktop session does not include ~/.local/bin in PATH, use an absolute path in ~/.local/share/applications/nextdns-tray.desktop.

3. (Optional) Add to Autostart: If you want the tray to start automatically when you log in:

   mkdir -p ~/.config/autostart
   cp ~/.local/share/applications/nextdns-tray.desktop ~/.config/autostart/
   

Manual Installation (equivalent)

sh -c 'curl -sL https://nextdns.io/install | sh'
sudo apt update
sudo apt install python3 python3-pyqt6

mkdir -p ~/.local/bin ~/.local/share/applications ~/.local/share/icons
cp home/.local/bin/nextdns-tray ~/.local/bin/
cp home/.local/share/applications/nextdns-tray.desktop ~/.local/share/applications/
cp home/.local/share/icons/nextdns.png ~/.local/share/icons/
chmod +x ~/.local/bin/nextdns-tray
mkdir -p ~/.config/autostart
cp ~/.local/share/applications/nextdns-tray.desktop ~/.config/autostart/

Status Detection

The tray distinguishes between service state and real DNS usage.

• Stopped: NextDNS service is not running.
• Running / Not In Use: service is running, but resolver settings do not point to NextDNS.
• Running / Usage Unknown: service is running and resolver looks correct, but live verification is temporarily unavailable.
• Running / In Use: service is running and usage is verified.

Verification model:

• Fast local checks run on each refresh cycle.
• End-to-end validation uses https://test.nextdns.io and is cached for 30 seconds.
• A start/restart action forces an immediate end-to-end re-check.

Notes:

• This validates host DNS routing; application-specific DoH settings may bypass host resolver behavior.
• curl is used for the end-to-end check. If unavailable, status may appear as Usage Unknown.