🛡️ VPeeN

The free VeePN browser-extension network — for your entire operating system.

شبکه رایگان افزونه VeePN — این بار برای کل سیستم‌عامل تو.

No login · No subscription · No browser needed · Pure-Python core

Quick start · Tunnel mode & kill switch · FAQ · Version history · 🇮🇷 راهنمای فارسی

💡 Why VPeeN?

The VeePN Chrome extension is free, needs no account, and tunnels browser traffic through a global proxy network. VPeeN speaks the same protocol natively and brings those tunnels to every app on your machine — wrapped in a product-grade desktop interface.

• 🖥️ System-wide — browsers, games, download managers, CLIs: everything is covered
• 🙈 Anonymous — guest tokens only, nothing to sign up for
• 🚪 Browser-free — Chrome can stay closed; VPeeN talks to the network directly
• 🧩 Standard interfaces — plain SOCKS5 and HTTP proxies on localhost
• 🪟 A real Windows installer (v4.9) — VPeeN-Setup-x.y.z.exe: Start Menu, uninstaller, zero UAC
• 🧱 Leak-proof by design (v4.9) — a firewall-grade kill switch, a one-click self-check, split tunneling and a Persian (RTL) UI on top of the v4.8 auto-updater
• ⚡ Fast by construction (v4.5–v4.7) — pre-warmed TLS connections, hedged connects and throughput-ranked servers: every proxied connection costs ~1 round-trip, a stalled server costs 0.35 s instead of 8 s, and repeated DNS lookups are answered from a local cache
• 🎨 “Aurora” GUI (v4.4) — an animated power orb, drifting aurora gradients, live latency bars and realtime traffic stats — a local web app in a native window (pywebview) or your browser. No Tk, no Electron, no heavy frameworks
• 🆓 Free-tier honest — the list shows the 7 locations the free network actually serves, with real measured latency; the 178 premium ones are hidden instead of failing

flowchart LR
    A["🖥️ Your apps"] -->|"SOCKS5 / HTTP on 127.0.0.1"| B["VPeeN"]
    B -->|"encrypted tunnel"| C["🌍 VeePN free network"]
    C --> D["Internet"]
    style B fill:#0f766e,color:#d7fbee,stroke:#2de3a7
    style A fill:#0e1526,color:#eaf1fb,stroke:#22304d
    style C fill:#0e1526,color:#eaf1fb,stroke:#22304d
    style D fill:#0e1526,color:#eaf1fb,stroke:#22304d

✨ Features

🚀 Quick Start

Option 1 — Ready-made binaries

Download from Releases:

🪟 Windows: grab the Setup exe — a real installer (Start Menu shortcuts, an optional desktop icon and an Apps & Features entry with an uninstaller) that installs per-user into %LOCALAPPDATA%\Programs\VPeeN, so no UAC / admin rights are needed. The zip stays for portable use (USB stick, restricted machines); both get the same automatic in-app updates.

Windows/macOS open the UI in a native desktop window (pywebview); Linux (and any machine without a webview backend) opens it in your default browser — same UI, same features.

🍏 macOS first launch (Gatekeeper)

VPeeN is free, open-source software — and not wrapped in a paid Apple Developer certificate. On modern macOS (Sequoia and Tahoe 26) Gatekeeper answers that with “Apple could not verify ‘VPeeN’ is free of malware…” and no visible Open button. It is a warning, not a defect — the binary is ad-hoc code-signed since v4.6.0. Two ways past it:

1. The two-click way — try to open the app once, then System Settings → Privacy & Security → scroll to the bottom → “Open Anyway”. macOS asks once; after that it opens normally forever.
2. The one-line way — Terminal:

   xattr -cr /Applications/VPeeN.app     # (or the path where you unzipped it)
   

   This removes the quarantine flag Apple put on the download.

🧩 Chrome extension — VPeeN Bridge

Want only the browser on the VPN while the rest of the system stays direct — or the one-click switch while VPeeN runs? VPeeN Bridge (ships as VPeeN-Chrome-Extension.zip on every release, source in extension/):

1. Unzip it anywhere permanent.
2. chrome://extensions → enable Developer mode → Load unpacked → pick the folder.
3. Click the VPeeN icon → flip “Route Chrome through VPeeN”.

Two permissions only (proxy, storage), remote DNS through the tunnel, and the same localhost/LAN bypass list as the desktop app. Flip it off and Chrome is instantly direct again.

Option 2 — Run from source

git clone https://github.com/SirBNL/VPeeN.git
cd VPeeN
pip install -r requirements.txt     # optional: native window (pywebview)
python main.py

The app starts, shows your real IP, fetches free locations with live latency — press the power orb.

Option 3 — Headless CLI

No GUI needed (servers, routers, scripts):

python -m vpeen.cli list                 # list free locations + latency
python -m vpeen.cli test nl              # full chain test: token → server → exit IP
python -m vpeen.cli run --region us-va   # SOCKS5 :1080 + HTTP :8080
python -m vpeen.cli run --best           # auto-pick the optimal region
python -m vpeen.cli export nl            # print the raw upstream config

Then point any app at:

SOCKS5 :  socks5://127.0.0.1:1080
HTTP   :  http://127.0.0.1:8080

⚙️ How it works

VPeeN reproduces what the free VeePN extension does inside the browser — but for the whole OS:

1. Anonymous session — VPeeN obtains a guest access token, exactly like the extension. No account is ever created.
2. Locations & servers — the free location list and per-session credentials are fetched from VeePN's live infrastructure, so the app keeps working as endpoints evolve.
3. Local proxy — VPeeN listens as a standard SOCKS5 + HTTP proxy on 127.0.0.1 (a non-loopback bind without credentials is refused outright).
4. Tunneling — every connection is relayed through an encrypted tunnel to the selected region.
5. System switch — optionally flips the OS proxy on (Windows / macOS / GNOME) and restores the previous state on exit.

The GUI itself is a tiny loopback-only web app: a stdlib HTTP server runs the proxy core and streams events to the UI over a long-poll /api/poll endpoint — the interface reacts in under a second with zero third-party JavaScript.

🔒 Tunnel Mode — a real VPN, the Hiddify way

Flip the VPN Tunnel switch and VPeeN stops being “just a proxy” and becomes a system-wide VPN: a virtual network adapter takes over all of your traffic — not just the apps that know about proxies.

flowchart LR
    A["🖥️ ALL apps + DNS"] --> B["🔌 VPeeN TUN adapter"]
    B --> C["tun2socks userspace TCP/IP stack"]
    C -->|"socks5 over loopback"| D["VPeeN core"]
    D -->|"encrypted tunnel"| E["🌍 VeePN network"]
    E --> F["Internet"]
    style D fill:#0f766e,color:#d7fbee,stroke:#2de3a7
    style A fill:#0e1526,color:#eaf1fb,stroke:#22304d
    style B fill:#0e1526,color:#eaf1fb,stroke:#22304d
    style C fill:#0e1526,color:#eaf1fb,stroke:#22304d
    style E fill:#0e1526,color:#eaf1fb,stroke:#22304d
    style F fill:#0e1526,color:#eaf1fb,stroke:#22304d

Under the hood this is the same architecture Hiddify / sing-box use: a TUN device (wintun on Windows, utun on macOS, tun on Linux) driven by the open-source tun2socks engine (MIT), which VPeeN launches as a properly elevated helper and points at its own local SOCKS5.

Built to never break your internet

ℹ️ Tunnel mode needs administrator rights once per connect (UAC prompt on Windows, pkexec / osascript on Linux / macOS) — that is how real VPN apps create a network device. Everything else (proxy mode) works without elevation.

🧱 Kill switch — blocked, never leaked (v4.9)

When tun2socks dies mid-session, the TUN adapter — and with it the hijack routes — dies too. Without a kill switch every packet then silently leaves through your real gateway while the UI still says Protected. v4.9 closes that hole:

1. Detect — the elevated worker polls tun2socks every second.
2. Contain — tagged firewall rules (VPeeN-KS) drop all non-loopback outbound traffic: netsh on Windows, iptables/ip6tables on Linux. (macOS: detection + repair, no firewall primitive — documented limitation.)
3. Repair — tun2socks is respawned, the hijack routes re-bound to the new adapter, the DNS relay restarted — and only once the tunnel is proven back does the containment lift. The repair path has no leak window.
4. Lockdown — if repair fails 3×, the containment stays: a red Kill Switch ON state; one click disconnects (full restore) or retries.

The rules are journaled with the session (crash recovery removes them), engage is delete-then-add, release is idempotent, and the startup sweep removes stale rules even without a session file — no rule survives “start the app once.” With the kill switch on, a dead GUI leaves the blackhole in place (offline, not leaking) instead of silently restoring direct traffic. Toggle: Settings → VPN tunnel → Kill switch (default on, tunnel mode only).

🩺 Doctor — the one-click protection self-check (v4.9)

The shield button in the top bar runs 8 checks against your live connection — exit-IP leak detection, routing coverage, DNS privacy, kill-switch state, system proxy, QUIC/WebRTC side channels — without contacting any third-party “what is my IP” site. Results are sorted problems-first and localized.

🔀 Split tunneling (v4.9, proxy mode)

Settings → Local proxy → Bypass list: domains like *.ir or your bank's site connect DIRECT while the system proxy is on. The previous exception list is backed up and restored byte-for-byte on disconnect. CLI equivalent: python -m vpeen.cli run --region nl --set-system --bypass "*.ir". Tunnel mode ignores the list on purpose — a full tunnel is a full tunnel.

🏗️ Build from source

pip install pyinstaller
pyinstaller vpeen.spec --noconfirm

• Windows → dist/VPeeN.exe · macOS → dist/VPeeN.app · Linux → dist/VPeeN

Every push is built for all three platforms by GitHub Actions; version tags (v*) automatically produce a release with binaries — on Windows the Setup installer is compiled with Inno Setup from installer/vpeen.iss.

📁 Project structure

VPeeN/
├── main.py               # GUI launcher (+ tunnel-worker dispatch, crash log)
├── vpeen/
│   ├── gui.py            # desktop window launcher (pywebview → browser fallback)
│   ├── webui.py          # local web-UI server + core/tunnel bridge (loopback only)
│   ├── web/              # the "Aurora" GUI (index.html / style.css / app.js, EN+FA)
│   ├── core.py           # background proxy engine + GUI event bridge
│   ├── api.py            # VeePN network client (tokens, locations, servers)
│   ├── upstream.py       # encrypted upstream tunnels
│   ├── localproxy.py     # local SOCKS5 + HTTP servers
│   ├── tunnel.py         # VPN tunnel orchestration (elevated worker + controller)
│   ├── tunnel_platforms.py  # per-OS TUN routes / DNS / session journal
│   ├── killswitch.py     # firewall-grade kill switch (detect → contain → repair)
│   ├── doctor.py         # 8-check protection self-check (Doctor)
│   ├── dnsrelay.py       # DNS relay that tunnels DNS through VPeeN
│   ├── systemproxy.py    # OS proxy switch + bypass list (Win / macOS / GNOME)
│   ├── selfupdate.py     # one-click self-updater (+ installed-version sync)
│   ├── settings.py       # persistent app settings (atomic writes)
│   ├── cli.py            # headless command-line mode
│   └── utils.py          # shared helpers
├── installer/vpeen.iss   # Inno Setup script → VPeeN-Setup-x.y.z.exe (CI)
├── extension/            # "VPeeN Bridge" Chrome extension (MV3)
├── assets/               # icon, logo, banner, flags/ (92 circular flags)
├── scripts/              # fetch-binaries + 11 verification suites + release canary/tools
├── docs/                 # screenshots + demo GIF
└── .github/workflows/    # multi-OS build + release pipeline (test gate + release canary)

🧾 Third-party components

📜 Version history

❓ FAQ

⚠️ Disclaimer

This project is published for educational and research purposes — it demonstrates how a browser-extension proxy client works. Using the free extension network outside the browser may conflict with VeePN's Terms of Service; you are responsible for how you use this software. Respect the laws of your country and the networks you connect to.

git clone https://github.com/SirBNL/VPeeN.git
cd VPeeN
pip install -r requirements.txt
python main.py

python -m vpeen.cli list                  # لیست لوکیشن‌های رایگان + پینگ
python -m vpeen.cli test nl               # تست کامل زنجیره
python -m vpeen.cli run --region us-va    # SOCKS5 :1080 + HTTP :8080
python -m vpeen.cli export nl             # نمایش کانفیگ خام آپ‌استریم

SOCKS5 :  socks5://127.0.0.1:1080
HTTP   :  http://127.0.0.1:8080

⭐ If VPeeN saved you some money, a star is the best thank-you.

_{v4.9.1 “Sangar” · pure-Python core · zero-dependency GUI}