WG Tunnel - Desktop

Table of Contents

• About
• Supported Platforms
• Features
• Deferred Endpoint Bootstrapping
• Installation
• Development
• Contributing

#Supported Platforms

• Windows
• Linux
• macOS - not yet supported, but planned for a future release.

#Features

This app shares its tunnel/DNS/recovery engine with the Android app, so most android feature apply here too:

• Auto-Tunneling: Automatically activate tunnels based on the machine's active network details.
• Deferred Endpoint Bootstrapping: Safely resolves endpoints and updates peers after the tunnel is up for better reliability and leak protection on startup.
• Handshake Monitoring: Real-time handshake monitoring for instant tunnel health feedback.
• AmneziaWG Support: Full support for AmneziaWG 2.0 through 3.1, providing robust censorship protection.
• Split & Encrypted DNS: Resolve DNS through the tunnel using plain DNS, DoT, or DoH, and optionally split by domain suffix (tunnel or system).
• Local Proxy Mode: Expose WireGuard tunnels over a local SOCKS5 or HTTP proxy to browsers or other apps.
• Kill switch: A system-wide, tunnel-independent, kill switch that blocks all traffic and is layerable on top of either mode.
• Dynamic DNS Handling: Automatically detect and update endpoints on server IP changes without requiring a restart.
• IPv6 Endpoints: Automatically upgrade to IPv6 endpoints or fall back to IPv4 based on network conditions without requiring a restart.

Desktop-specific:

• Native Application: Ships as a GraalVM native image (not a JVM/Electron style app) for fast startup and a low memory footprint.
• System Service Daemon: The tunnel runs as an independent system service, so it keeps running (and enables restore on boot features) even when the GUI is not.
• Kill switch & Tunnel Restoration on Boot: Reapplies the kill switch and reconnects the last active tunnel automatically after a reboot.
• Encrypted At Rest: Tunnel configs and other sensitive data are stored encrypted (AES-256-GCM) in the local database while the encryption key lives in the OS keychain/credential store.
• Tunnel Management: Import, export, editing, live statistics (including uptime and, in Local Proxy mode, the active proxy address/auth status), and sorting.
• System Tray Integration: Minimize to tray with a live status badge.
• App Updater: In-app updater and update notifications (only for .deb/.rpm and Windows installs).

#Deferred Endpoint Bootstrapping

Most WireGuard clients resolve peer endpoints before bringing the tunnel up. This has several drawbacks:

1. If resolution fails or is slow (a flaky network, a DNS hiccup, a blocked resolver) the tunnel simply doesn't come up, and there's no protection until it does.
2. During that resolution window, you're leaking until resolution completes successfully.

WG Tunnel splits these apart and removes peer resolution from the critical path. The TUN interface, routes, and firewall rules come up first, prioritizing user protection. Peer endpoint resolution then happens separately, in the background, retrying indefinitely until it succeeds.

This has significant benefits:

• Immediate protection: The user is protected the moment the tunnel is toggled on, regardless of whether or when endpoint resolution succeeds. This dramatically reduces a leak window that other clients suffer from.
• Reliability: The tunnel never fails to come up because of a flaky network or resolution failures. The tunnel is already up and blocking traffic while DNS keeps retrying in the background until it connects.

#Installation

#Windows

[!WARNING] Before installing v2.x.x and greater on Windows, it is required to uninstall the v1.x.x if you have it installed. The architecture of the app has changed significantly in the latest version and requires the old version to be removed.

[!NOTE] Requires Windows 10 version 1803 (build 17134) or later for UDS support. The installer checks this and will refuse to install on an older build.

1. Download the Windows installer (.exe) from the latest release.
2. Run the installer. Accept the Admin rights prompt (UAC) so the daemon can be installed as a system service.
3. Launch the app.

Also available on Chocolatey:

choco install wgtunnel

#Linux

[!NOTE] Only systemd-based Linux systems are currently supported. Also, the firewall must use nftables or iptables with the nft backend (iptables-nft).

[!Note] Direct installations from GitHub releases for .deb and .rpm packages can use the in-app updater while .pacman and tarball direct installs will require manual updates.

#Debian / Ubuntu

Preferred method - via our apt repository (for package manager updates):

curl -fsSL https://apt.wgtunnel.com/wgtunnel-archive-keyring.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/wgtunnel-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/wgtunnel-archive-keyring.gpg] https://apt.wgtunnel.com stable main" | \
  sudo tee /etc/apt/sources.list.d/wgtunnel.list
sudo apt update
sudo apt install wgtunnel

Or, download the .deb directly from the latest GitHub release:

sudo apt install ./wgtunnel*.deb

#Fedora / RHEL

Preferred method - via COPR (for package manager updates):

sudo dnf copr enable zaneschepke/wgtunnel
sudo dnf install wgtunnel

Or, download the .rpm directly from the latest GitHub release:

sudo rpm -Uvh wgtunnel*.rpm

#Arch Linux

Preferred method - via AUR (for package manager updates):

[!Note] Per Arch packaging guidelines, the installation does not enable or start the daemon for you. You will need to start the daemon yourself after install.

yay -S wgtunnel-bin

Or, download the .pacman directly from the latest GitHub release:

sudo pacman -U wgtunnel*.pacman

Then, enable and start the daemon:

sudo systemctl enable --now wgtunnel-daemon.service

#Other distros (.tar.gz)

Use this only if none of the formats above fit your distro. The tarball bundles its own install.sh / uninstall.sh (the same install location and systemd configuration the .deb/.rpm/ .pacman packages use under the hood). See packaging/linux/tar-install.sh in the source repo if you want to see the source script:

tar -xzf wgtunnel*-linux-x64.tar.gz
cd wgtunnel*-linux-x64/
sudo ./install.sh

To update, just run sudo ./install.sh again from a newer tarball. It copies over the existing install and restarts the daemon. To remove it entirely: sudo /opt/wgtunnel/uninstall.sh.

#Removing saved data

Uninstalling normally leaves your saved tunnels, settings, and logs in place, so a reinstall picks up where you left off. To wipe everything:

• Debian/Ubuntu: sudo apt purge wgtunnel
• Fedora/RHEL, Arch (GitHub release or AUR): there is no built-in purge so to remove after uninstalling:

  sudo rm -rf /var/lib/wgtunnel /etc/wgtunnel /var/log/wgtunnel
  rm -rf ~/.local/share/wgtunnel ~/.wgtunnel
  

• Tarball: sudo /opt/wgtunnel/uninstall.sh --purge

None of these clear the saved secret in your OS keyring (service wg_tunnel). You will need to remove that yourself with your keyring manager.

[!Note] Snap, Flatpak, and AppImages are not shipped and there is no plan currently to add them. They simply are not a good fit for the app due to their sandboxing limitations.

#Development

#Requirements

• Toolchains pinned in .mise.toml (JDK, Node, Go, .NET) - installed for you by mise install below.
• A C toolchain for the host platform.
• MinGW-w64 (x86_64-w64-mingw32-gcc)

#Run locally

# once per machine
curl https://mise.run | sh
mise trust
mise install

Start the daemon - it needs elevated privileges to manage routes/firewall, so use the dev script.

./scripts/dev-run-daemon-linux.sh

Then, in another terminal, run the GUI:

./gradlew :composeApp:run

#Contributing

Any contributions in the form of feedback, issues, code, or translations are welcome and much appreciated!

If your PR requires core changes, please link the associated PR.