DNSCrypt Proxy GUI 🛡️

A powerful, cross-platform GUI wrapper for the official dnscrypt-proxy.

dnscrypt-proxy is a fantastic tool for securing DNS communications, but its power can be daunting for users who prefer a graphical interface. This project provides a user-friendly, cross-platform client that acts as a complete visual controller for the dnscrypt-proxy executable.

It allows you to fetch the latest public resolver lists, select one or more servers, and instantly activate them. It handles everything from generating the configuration file to modifying your system's DNS settings and running the proxy in the background.

✨ Features

• Browse & Sort Servers: Fetches the latest public DNSCrypt resolver list and displays it in an easy-to-sort table.
• Multi-Server Activation: Select and activate multiple servers simultaneously for enhanced reliability and speed.
• Anonymizing Relays: Apply anonymizing relays to DNSCrypt servers for an extra layer of privacy.
• Live Status Indicator: A clear visual indicator shows whether the service is ACTIVE or INACTIVE.
• Exact DNS Backup & Restore: Before any change, your current DNS settings are captured and restored verbatim on deactivation or exit. If a crashed session ever left settings behind, the next launch repairs them automatically.
• System Tray Integration: Hides the main window to a tray icon, allowing the client to run unobtrusively in the background.
• Run at Startup: A simple checkbox lets you configure the client to launch automatically when you log in.
• Comprehensive Configuration: A dedicated tab to visually manage the dnscrypt-proxy.toml settings.
• Server Requirements: Enforce DNSSEC, no-log, and no-filter policies.
• Network Behavior: Block IPv6 requests with a single click.
• Cache Settings: Fine-tune the cache size and TTL values.
• Instant Apply: Configuration changes are applied immediately to the running service with a seamless restart.
• Session Persistence: Remembers your last active servers and settings, and can automatically reactivate them on the next launch.
• Automatic Privilege Elevation: Intelligently requests administrator/sudo privileges on launch, as they are required for managing network settings.

---

🚀 Getting Started

You can either download the pre-compiled standalone executables (Recommended) or run the Python script directly.

📥 Option 1: Download Standalone Release (Recommended)

We provide high-quality, pre-built executables for Windows (x64 + ARM), macOS (ARM64), and Linux (x86_64 + ARM64). No Python installation required!

1. Go to the Releases page and download the archive matching your OS and version - e.g. dnscrypt-proxy-gui-1.2.1-Windows-x64.zip.
2. Extract it into its own dedicated folder (e.g. C:\Program Files\dnscrypt-proxy-gui\, ~/Applications/dnscrypt-proxy-gui/, or ~/dnscrypt-proxy-gui/). Never extract the contents loose into Program Files itself - the folder contains the app plus its runtime libraries.
3. macOS users: the app is not codesigned, so on first launch right-click the app and choose Open (or allow it in System Settings → Privacy & Security).
4. Run the GUI executable. (It will automatically request administrator/sudo privileges).

The release archive ships a bundled, latest-stable dnscrypt-proxy engine inside the app folder (or .app/Contents/Resources on macOS), so you can activate encrypted DNS the very first time the GUI starts — no separate download, no extra setup. The GUI discovers engines in this order: 1. your custom path (if set in Configuration), 2. a system install found on PATH, 3. the bundled copy. Your existing install is always respected; the bundled engine is the safety net. Both the GUI version and the engine version are displayed in the Updates section on the Configuration tab, alongside an update check button. Available updates for either component are highlighted in blue. The build system also records the engine version in ENGINE_VERSION.txt inside the archive for reference.

---

💻 Option 2: Run from Source

If you prefer to run the Python script directly, follow these steps:

1. Prerequisites

• Python 3.11+: Ensure you have Python installed. You can download it from python.org.
  • Debian/Ubuntu: also install the GUI toolkit with sudo apt install python3-tk
  • Fedora: sudo dnf install python3-tkinter
  • Arch: tk is bundled with the tk package (sudo pacman -S tk)
• dnscrypt-proxy: The GUI auto-discovers it: 1) a system install found on PATH, 2) a binary placed next to the script, or 3) (if using a release build) the bundled copy. On Linux, install it from your distro repositories (sudo apt install dnscrypt-proxy) or download from the official releases page.

2. Get the Code

Clone this repository or download the source code:

git clone https://github.com/neohiro/dnscrypt-proxy-gui.git
cd dnscrypt-proxy-gui

3. Install Dependencies

Create a virtual environment and install the required libraries:

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt   # requests, pystray, Pillow

The system tray icon needs pystray + Pillow. Without them the GUI still works - closing the window minimises it to your taskbar instead of the tray.

4. Prepare the Directory

Extract the dnscrypt-proxy archive you downloaded earlier and place the executable inside the cloned repository. Your directory should look like this:

dnscrypt-proxy-gui/
├── dnscrypt-proxy-gui.PY    # The GUI script
└── dnscrypt-proxy.exe       # The official executable (or `dnscrypt-proxy` on Linux/macOS)

5. Run the Script

Windows:

python dnscrypt-proxy-gui.PY

Linux / macOS:

python3 dnscrypt-proxy-gui.PY

Do not run the script through the shell directly (e.g. ./dnscrypt-proxy-gui.PY) unless you have made it executable first (chmod +x). If you see errors like from: not found, your shell is trying to interpret Python as shell script - always launch it via python3.

Activating servers changes system DNS settings, which requires elevated privileges. On Linux/macOS either start the GUI with sudo (using the same virtual environment: sudo .venv/bin/python3 dnscrypt-proxy-gui.PY) or point the Configuration tab's System Paths at a proxy/config location your user can write.

---

System Paths (Linux / macOS)

The GUI auto-discovers the engine in this order:

1. Custom path — anything you set in Configuration → System Paths (persisted in settings.json).
2. System install — dnscrypt-proxy on $PATH (e.g. /usr/bin/dnscrypt-proxy on Linux, /usr/local/bin/dnscrypt-proxy on macOS). On Windows it must be reachable via PATH; if it isn't, set a custom path.
3. Bundled engine — the binary shipped with the release archive (next to the GUI on Linux/Windows, in .app/Contents/Resources on macOS).

What	Windows	Linux	macOS
dnscrypt-proxy executable (system)	on PATH	/usr/bin/dnscrypt-proxy or on $PATH	/usr/local/bin/dnscrypt-proxy or on $PATH
dnscrypt-proxy executable (bundled)	next to the GUI	next to the GUI	inside .app/Contents/Resources
Configuration folder (default)	next to the GUI	/etc/dnscrypt-proxy	/etc/dnscrypt-proxy (or /usr/local/etc/dnscrypt-proxy if installed via Homebrew)

Both locations are configurable in the Configuration → System Paths section - set them once and they persist in settings.json. The detected engine's version is shown on the same tab once the proxy becomes available.

---

🛠️ How to Use

1. Refresh List: Click "Refresh Server List" to fetch the latest resolvers.
2. Select Servers: Select one or more servers from the list.
3. Configure (Optional): Go to the Configuration tab to adjust settings like DNSSEC, Logging, and IPv6.
4. Activate: Click "Activate Selected Server(s)".
5. Success: Your DNS traffic is now encrypted! You can close the window to minimize it to the system tray.

Note: When you click Activate, the GUI dynamically generates a dnscrypt-proxy.toml file, launches the proxy in the background, and automatically configures your system's network adapter to route DNS queries through 127.0.0.1. Your previous DNS settings are snapshotted first (dns_backup.json) and restored exactly when you deactivate or exit. When you deactivate, it gracefully reverts your settings back to their original state.

Troubleshooting: The app writes a rotating log to %LOCALAPPDATA%\DNSCryptClientGUI\logs (Windows), ~/Library/Logs/DNSCryptClientGUI (macOS) or ~/.cache/dnscryptclientgui/logs (Linux). Include recent lines when reporting problems.

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the ISC License, in parallel with dnscrypt-proxy itself. See LICENSE for more information.

🙏 Acknowledgments

A huge thank you to the DNSCrypt team for creating and maintaining the incredible dnscrypt-proxy project.

---