Linux VPN / proxy client

VoidTunnel

A PyQt6 desktop client for managing VMess, VLESS, Trojan, and Shadowsocks connections through Xray-core or native sing-box TUN routing.

Download Compare modes GitHub

Version: 1.1
Platform: Linux
Ports: 10808 / 10809

Xray-core proxy engine sing-box native TUN GNOME and KDE proxy setup Payload and header tools

Start here

What VoidTunnel does

VoidTunnel gives Linux users a clean desktop workflow for importing proxy profiles, connecting through Xray-core, or routing the whole machine through sing-box TUN mode.

Core workflow

Install Python dependencies and launch the PyQt6 app.
Import a server URL or subscription into the Servers tab.
Select Proxy mode or TUN mode from Settings.
Connect, watch live stats, and inspect logs when needed.

VoidTunnel connected dashboard screenshot — Connected dashboard with latency, traffic totals, proxy IP, and session stats.

Protocols

VMess, VLESS, Trojan, Shadowsocks

Profiles are converted into Xray or sing-box outbound configs.

Profiles

Import, search, ping, duplicate

Use single URLs, multiple URLs, subscriptions, QR export, and latency checks.

Routing

Proxy mode or TUN mode

Choose browser and proxy-aware apps, or route all system traffic.

Download

Get VoidTunnel from GitHub

The current project is source-based. Clone it with Git, or download the ZIP from GitHub and run it with Python.

Clone the repository

git clone https://github.com/klsdfernando/VoidTunnel.git
cd VoidTunnel

Option A: Git clone

Best for developers and users who want to update with git pull.

Option B: GitHub ZIP

Open the repository, choose Code, then Download ZIP. Extract it and open a terminal inside the folder.

Setup

Install requirements and run

VoidTunnel needs Linux, Python 3.10 or newer, PyQt6 dependencies, and optional polkit support for sing-box TUN authentication.

Runtime Python 3.10+, pip, venv

Desktop Linux with a graphical session

TUN mode pkexec from polkit

Core download Xray-core on first run, sing-box when TUN mode is used

Create environment and launch

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python src/main.py

Ubuntu / Debian

sudo apt update
sudo apt install python3 python3-venv python3-pip policykit-1

Fedora

sudo dnf install python3 python3-pip polkit

Arch

sudo pacman -S python python-pip polkit

Servers

Add profiles and subscriptions

Profiles can be added one at a time, pasted in bulk, imported from a subscription URL, copied back to a share URL, or shown as a QR code.

Supported import formats

vmess://... for VMess profiles
vless://... for VLESS profiles
trojan://... for Trojan profiles
ss://... for Shadowsocks profiles
ssh://... can be parsed, but connection support is currently basic and limited

Fast profile flow

Open Servers, click Import, paste a subscription URL or one URL per line, then double-click a profile to select it for the Connect page.

Modes

Proxy mode vs sing-box TUN mode

VoidTunnel has two practical routing styles. Proxy mode is lighter and app-aware. TUN mode behaves more like a full VPN.

Proxy mode: Xray-core plus system proxy

Use this when you want browsers and proxy-aware applications to use VoidTunnel while the rest of your system remains direct.

Open Settings, then the Proxy tab.
Set Connection Mode to System Proxy.
Keep Enable system proxy when connected on for automatic GNOME/KDE configuration.
Select a server and press Connect.

SOCKS5: 127.0.0.1:10808 HTTP: 127.0.0.1:10809

Choose the right mode

Need	Use	Why
Browser tunneling	Proxy mode	Lower privilege, simple local HTTP/SOCKS ports.
All app traffic	sing-box TUN	Routes through `tun0` with native sing-box routing.
No root prompt	Proxy mode	System proxy settings do not need TUN device creation.
Apps ignore proxies	sing-box TUN	Traffic is captured below the application layer.

Feature guide

Use the main tools

VoidTunnel is built around four pages: Connect, Servers, Logs, and Payload. Settings controls startup, proxy ports, DNS servers, and connection mode.

Connect

Live connection dashboard

Shows selected profile, connect state, latency, upload, download, session totals, real IP, and proxy IP.

Servers

Profile management

Add URLs, import subscriptions, search profiles, ping latency, duplicate, edit, copy URL, show QR, or delete.

Logs

Xray and sing-box output

Use logs to spot config errors, authentication cancellation, failed downloads, or engine startup failures.

Payload

Header and host tuning

Set method, host, path, and custom headers for profiles that need WebSocket or HTTP transport changes.

Payload notes

Payload settings are saved per profile. They update WebSocket host/path and custom transport headers used by generated Xray and sing-box configs, so test with providers that explicitly require those values.

Configuration

Important files and defaults

VoidTunnel stores runtime settings in your user config folder and writes engine configs when you connect.

Path	Purpose
`~/.config/voidtunnel/settings.json`	App settings, DNS servers, proxy ports, startup behavior.
`~/.config/voidtunnel/profiles/`	Saved server profile database.
`~/.config/voidtunnel/config.json`	Generated Xray-core config for proxy mode.
`~/.config/voidtunnel/singbox_config.json`	Generated sing-box config for TUN mode.
`~/.config/voidtunnel/proxy.env`	Fallback environment proxy exports when desktop proxy APIs are unavailable.

Troubleshooting

Common fixes

Most problems are either missing engine binaries, desktop proxy settings, profile format mismatches, or missing polkit for TUN mode.

Xray-core is missing

On first launch, VoidTunnel prompts to download Xray-core v1.8.7. Accept the prompt, then retry Connect. If download fails, check network access and file permissions inside src/resources/xray/.

sing-box TUN mode asks for a password

This is expected. TUN mode needs root permission through pkexec to create and manage tun0. Install polkit if pkexec is not found.

Proxy mode connects but browser does not change IP

Confirm system proxy is enabled, then manually set HTTP proxy to 127.0.0.1:10809 or SOCKS5 proxy to 127.0.0.1:10808 in the browser.

SSH profile imports but does not connect

The parser recognizes ssh:// URLs, but the current Xray and sing-box outbound generators are focused on VMess, VLESS, Trojan, and Shadowsocks.

Need to reset settings

Close VoidTunnel, back up ~/.config/voidtunnel/, then remove the setting or generated config file you want to recreate.