TunTop

Topics

windows · vpn · proxy · socks5 · tun2socks · wintun · full-tunnel · v2rayn · xray · sing-box · clash · vless · vmess · trojan · shadowsocks · geoip · dns-leak-protection · tui · dashboard · network-monitor · routing · privacy · censorship-circumvention · python

A Windows full-tunnel for any SOCKS5 proxy.

v2rayN, Xray, sing-box, Clash Meta — any proxy client with a local SOCKS5 inbound works. TunTop gives you system-wide routing.

Features

• IPv4 and IPv6 full-tunnel routing via Wintun + tun2socks
• DNS resolution fallback (UDP/53 + DoH) with active leak detection — and an optional --dns-policy strict that refuses to resolve outside a live tunnel instead of falling back
• Kill-safe cleanup — verified teardown on every exit
• Live bypass add/remove without restarting the tunnel
• Geo-IP country routing from geoip.dat
• Health monitoring with 42+ live checks (route, DNS, leak, proxy, geo)
• Self-healing — auto-restarts on tunnel failure
• btop-style dashboard with throughput graphs, 7 color themes
• Leak test, diagnostics export, profiles
• Protocol-agnostic — VLESS, VMess, Trojan, Shadowsocks, anything your client speaks; TunTop only needs its local SOCKS5 inbound
• Zero pip dependencies

Why do I need this?

Most proxy setups only cover the browser. TunTop routes every app on your PC through your proxy — system-wide — and shows you exactly what's happening in a live dashboard. A dead tunnel is obvious at a glance instead of discovered mid-download.

Quick start (30 seconds)

1. Clone

git clone https://github.com/kooshaZP/TunTop.git
cd TunTop

2. Set up a proxy client

Install any SOCKS5-capable proxy client — e.g. v2rayN, Xray, sing-box, or Clash Meta — and enable its local SOCKS inbound (default 127.0.0.1:10808).

3. Set the server (the proxy origin)

TunTop also needs the address of your proxy's origin server — the remote server your local proxy client (v2rayN, Xray, sing-box, ...) connects to.

The protocol does not matter. VLESS, VMess, Trojan, Shadowsocks, naive, Reality, WS/gRPC transports — TunTop never talks to that server and never sees your client's config. The only thing it consumes is the local SOCKS5 inbound your client exposes; the origin address is needed for exactly one purpose: it is the one address that must NOT go through the tunnel itself. TunTop routes it around the TUN automatically, but you have to tell it where the origin is. Pick one of these ways:

• Edit Run_Helper.ps1 — set the $Servers line near the top:

  $Servers = @('203.0.113.10')                    # a bare IP
  # $Servers = @('example.com')                   # or a hostname
  # $Servers = @('a.example.com', 'b.example.com') # multiple are fine

• Command line — --server is repeatable:

  python tuntop/ui/dashboard.py --server 203.0.113.10 --server example.com

• Live in the dashboard — press [U] (Servers) and type the address(es), comma or space separated — or ADD them to the existing list. A full share link works too: pasting something like vless://uuid@203.0.113.10:443?type=ws..., trojan://..., ss://... or https://example.com/... is fine — TunTop strips the scheme, UUID/userinfo, port and path and keeps only the host, whatever the protocol. Changes made with [U] are resolved immediately and take effect on the next tunnel start ([S]).

Why the origin never goes through the TUN: for every address you list, TunTop resolves it (both IPv4 and IPv6) and installs explicit host routes (/32 for IPv4, /128 for IPv6) through the physical NIC. The tunnel's own connection to the origin therefore always rides the real network and never enters the TUN — otherwise the tunnel would try to reach its server through itself (a routing loop) and nothing would connect. You can verify this in the [2] panel: SERVER / RESOLVED on the TUNNEL side, and the same addresses listed under DIRECT (what is routed around the tunnel).

If your origin sits behind a CDN or reaches other domains, bypass those too: --bypass-ip cdn.example.com (repeatable) or press [A] in the dashboard and choose direct — same bypass mechanism, for any extra host.

4. Run

Easiest — double-click Start_TunTop.bat. It fixes the two classic "downloaded from GitHub and it won't run" problems automatically (strips the Mark-of-the-Web with Unblock-File, runs with -ExecutionPolicy Bypass), styles the console (title, UTF-8, 120×36, TrueType font so the box glyphs render), and starts Run_Helper.ps1.

⚠️ Windows blocks .ps1 scripts by default. PowerShell's default execution policy is Restricted, and files downloaded from GitHub carry the Mark-of-the-Web, so double-clicking Run_Helper.ps1 does nothing (or opens it in Notepad). Use one of these:

• Start_TunTop.bat (recommended — fixes both blockers + styling)
• From a terminal (also bypasses the policy):

  powershell -ExecutionPolicy Bypass -File Run_Helper.ps1

• From Explorer: right-click Run_Helper.ps1 → Run with PowerShell → confirm the UAC prompt. (The script also unblocks itself and, if the policy is Restricted, relaunches under Bypass on its own.)

Right-click Run_Helper.ps1 → Run with PowerShell → confirm the UAC prompt. First run auto-downloads tun2socks.exe and wintun.dll if they're missing.

Press [S] to start the tunnel, [C] to run a health scan, [L] for a leak test.

Running the standalone TunTop.exe (no Python needed)

1. Download TunTop.exe (and checksums.txt) from the latest release into any folder — Desktop\TunTop\ for example. The exe already contains tun2socks and wintun.dll; nothing else is bundled, and Python is not required.
2. (Optional) verify it: certutil -hashfile TunTop.exe SHA256 and compare with checksums.txt.
3. Run it: double-click TunTop.exe → confirm the UAC prompt (the dashboard manages routes and a TUN adapter, so admin is mandatory). A btop-style dashboard opens. Missing files are fetched automatically on first start (tun2socks / wintun if somehow absent, and the geoip database in the background — progress shows in the event log).
4. Point it at your proxy — the dashboard asks for a SOCKS5 inbound at 127.0.0.1:10808 (the v2rayN default). Start that proxy client first.
5. Press [S] — the tunnel comes up: Wintun adapter, routes, DNS. The header badge flips to RUNNING. Press [C] for a health scan and [L] for a leak test.

Changing servers and settings live (no restart)

The dashboard edits a RUNNING tunnel in place:

• [U] Servers — switch/add the proxy origin server live: pick from the list (arrow keys / mouse, Enter to apply), or replace / add addresses. The origin's protocol is irrelevant — only its host/IP is used.
• [E] Endpoint — change the endpoint port (e.g. 443) live.
• [P] Port — change the local SOCKS5 port live.
• [N] DNS — change the tunnel DNS servers live.
• [A] / [X] — add / remove a bypass IP instantly (route a site or server DIRECT, outside the tunnel) and choose the target: direct / proxy2 / VPN.
• [F] Geo Manager — country-level bypass: press [W] inside it to download/update the geoip database, then apply a country code (e.g. cn) so those sites route DIRECT while everything else stays in the tunnel.
• [Z] Proxies — add/change/remove a second proxy hop (proxy2) at runtime.
• [V] / [Y] — ride-another-VPN mode and its bypass list.
• [O] / [I] — save the whole setup to a profile / load it back.

Everything you change is logged in the event log panel (bottom). Press [T] to stop the tunnel (routes are swept and verified), [Q] to quit.

The exe requests the Cascadia Mono SemiLight font at startup so the box-drawing glyphs render. If your console ignores it and you see ???????????, see Troubleshooting for the right-click → Properties → Font fix.

How it works

flowchart LR
    A[Apps on Windows] --> B[Wintun TUN adapter]
    B --> C[tun2socks]
    C --> D["Local SOCKS5 proxy (127.0.0.1:10808)"]
    D --> E[Your proxy's upstream server]
    F[TunTop dashboard] -. builds and self-heals .-> B
    F -. live routes / bypass / geoip .-> G[Windows routing table]

Loading

TunTop builds a Wintun TUN adapter, feeds it through tun2socks into your proxy's local SOCKS5 inbound, and manages the Windows routing table to direct all traffic through it. The dashboard owns the tunnel for its entire lifetime — editing servers, bypass rules, or geo splits updates the routing table live.

Key reference

Key	Action
[S] [T] [Q]	Start / stop / quit (verifies cleanup)
[C]	Health scan
[A] [X]	Add/remove bypass instantly, with target choice: direct / proxy2 / vpn (no restart)
[L] [D]	Leak test / export diagnostics
[O] [I]	Save / load profile
[U] [V] [Y] [F]	Servers (live) / VPN mode / VPN bypass / geo manager (apply · change · remove, live)
[Z]	Add/change/remove the second proxy (proxy2) at runtime
[P] [N] [E]	SOCKS port / DNS (live, no restart) / endpoint port (live)
[R]	Re-apply geoip country bypass live
[G] [M] [H]	Graph mode / theme / help show-hide
1-6, 0	Hide/show panels
j/k / arrows / PgUp / wheel / ←→	Scroll: hovering a panel makes it the ACTIVE target for j/k, arrows, PgUp/PgDn, Home/End, ←/→ and the wheel

On short windows (16:9 screens) the panels shrink first — health-check rows, then the graph — and the help footer is only removed as the last resort.

Requirements

What	Why
Windows 10 1803+ / 11	Wintun adapter driver
Python 3.10+	stdlib only, no pip install
Administrator	route table management
A SOCKS5 proxy client (v2rayN, Xray, sing-box, Clash Meta, ...) running locally	provides the SOCKS5 inbound

Trust & packaging (the honest version)

TunTop is a single-maintainer project. Here is exactly what you are accepting when you run it, and what has / has not been verified:

• The exe is unsigned and self-extracting. It requires Administrator and rewrites the routing table — the same behavior profile AV/ML models flag. We make no claim that antivirus false positives are resolved; they may still occur. The TunTop-x64.zip / source route avoids self-extraction entirely: run from source with Python, or use the zip (verified below) instead of the bare onefile exe if your AV is aggressive.
• What you CAN verify: every published release ships checksums.txt; the CI workflow builds the exe from the tagged commit and the SHA-256 you compute locally (certutil -hashfile TunTop.exe SHA256) proves the bytes match what CI produced. That proves integrity (no tampering in transit), not safety — the difference matters.
• Auto-download trust model: the vendored tun2socks.exe / wintun.dll are checked against SHA-256 pins that live IN THE REPO (tuntop/core/integrity.py) — the expected hash does not come from the download channel, so a compromised mirror cannot swap the binary. The geoip.dat auto-update is weaker by design: its checksum comes from the same v2fly GitHub release as the file itself (trust-on-first-use). A hostile source could serve a wrong geo database — it could not achieve code execution, but it could route countries incorrectly; pin/ship your own geoip.dat if that threat matters to you.
• Battle-testing: the automation suite (see Tests) runs on every push, but real-world exposure is still low — few outside users, no broad hardware / network matrix coverage beyond the test matrix. If you rely on it, read the routing code (tuntop/network/routing.py, tuntop/core/cleanup_watchdog.py) — it is written to be auditable on purpose.
• Release hygiene: version metadata drift has happened before (1.0.14 shipped with exe properties saying 1.0.13 - fixed in 253f373, and the same class was caught AGAIN pre-release in 1.0.19). It is now enforced, not promised: tests/unit/test_release_hygiene.py fails the suite (and therefore CI) if tuntop_version_info.txt, tuntop/__init__.py and CHANGELOG.md disagree. Bug-class repeats are documented in the changelog rather than hidden.

Project layout

Run_Helper.ps1            <- launcher (PowerShell)
tuntop/
  core/                    <- tunnel orchestration (UI only talks to this)
    tunnel_manager.py      <- lifecycle facade (start/stop/recover)
    state.py               <- tunnel state machine
    recovery.py            <- backoff-based recovery engine
    routes_txn.py          <- transactional route management
    startup_recovery.py    <- crash detection + cleanup at launch
    integrity.py           <- binary SHA-256 verification
    events.py              <- structured logging
  network/                 <- routing / DNS / VPN (Windows edge)
    routing.py             <- netsh/PowerShell route engine
    dns.py                 <- DNS resolver with cache
    vpn.py                 <- VPN detection / coexistence
  tunnel/                  <- Wintun + tun2socks (Windows edge)
    helper.py              <- tunnel builder + self-heal monitor
    wintun.py              <- Wintun adapter management
    tun2socks.py           <- tun2socks process management
  monitor/                 <- health / traffic / leak / diagnostics
    health.py              <- visual health report
    traffic.py             <- live traffic stats
  config/                  <- profiles + models + defaults
    profiles.py            <- profile save/load + protected secrets
  geo/                     <- geoip.dat parser
    geoip.py
  ui/                      <- btop-style dashboard (owns the tunnel)
    dashboard.py
    themes.py              <- terminal text/layout primitives
tests/                     <- test suite across 5 tiers (count via: python -m unittest discover -s tests -t .)

tun2socks.exe and wintun.dll are auto-downloaded on first run and not in the repo.

Troubleshooting

• Dashboard won't start — TunTop needs Administrator rights. Right-click Run_Helper.ps1 → Run as Administrator.
• Page renders wrong — lots of ??????????? instead of the boxes/panels — the console font can't draw the Unicode glyphs. Fix: right-click the title bar at the top of the console window → Properties → Font tab, and switch the font to a TrueType mono font — Cascadia Mono, Cascadia Mono SemiLight (the default TunTop requests), Consolas, or Lucida Console. Raster fonts (the default on some systems) simply have no glyphs for those characters. Also make sure the codepage is UTF-8: chcp 65001. Then restart TunTop.
• Health scan fails — press [D] to export diagnostics (config, routes, logs, last scan) and attach it to an issue.
• Traffic leaks — run [L] to compare direct vs tunneled exit IP, and confirm v2rayN's SOCKS5 inbound is listening on the port TunTop uses ([P]).
• Tunnel starts but nothing connects — check the SERVER/RESOLVED rows in the [2] panel: the origin must resolve and be listed under DIRECT. See Set the server (the proxy origin) above; if the origin is behind a CDN, bypass that domain too ([A] → direct).
• Running alongside another VPN — use VPN mode ([V]) and VPN bypass ([Y]) so TunTop rides the existing VPN instead of fighting for the default route.
• Still stuck? Open an issue and attach the diagnostics file from [D]. See also FAQ.

Tests

Pure-stdlib test suite (350+ tests; exact count via the command below — it changes with every release), runnable on any OS with no admin rights (current count prints with the command below):

# Run the full suite (what CI runs)
python -m unittest discover -s tests -t . -v

# Including live-network tests (needs Internet)
TUNTOP_NET_TESTS=1 python -m unittest discover -s tests -t . -v

See tests/README.md for the tier layout (unit / routing / recovery / integration / network).

Contributing

See CONTRIBUTING.md. Short version:

• Standard library only — no new pip dependencies without discussing in an issue.
• The UI must never block — DNS, PowerShell, and route operations belong on background threads.
• Cleanup is sacred — anything that adds routes must be removable at exit.
• Run tests before committing. Include diagnostics ([D]) with bug reports.

Project docs & roadmap

• MILESTONE-v1.0.md — feature freeze, the definition of "stable", and the v1.0 criteria
• TEST-MATRIX.md — Windows 10/11 · Wi-Fi/Ethernet · VPN-active · IPv4/IPv6 · DNS-failure · sleep/wake test matrix
• KNOWN-ISSUES.md — known bugs and edge-case register
• CHANGELOG.md — release history
• FAQ.md — common questions and answers

Acknowledgments

TunTop builds on:

• v2rayN — proxy client with a local SOCKS5 inbound
• tun2socks — TUN-to-SOCKS translation
• Wintun — Windows TUN adapter driver
• btop — dashboard visual inspiration

License

MIT