To the Max VPN!

A cross-platform VPN client built with Flutter, powered by VLESS + Reality protocol.

---

Features

• Two connection modes on Windows:
  • System Proxy — routes browser and most app traffic via HTTP proxy. No admin rights required.
  • TUN Tunnel — captures all OS-level traffic via a virtual network adapter (WinTUN). Requires administrator privileges.
• Android support — full device VPN via flutter_v2ray with TUN tunneling (all traffic routed through VPN)
• VLESS + Reality — TLS 1.3 encryption with uTLS fingerprint masquerading, practically undetectable by DPI
• Mux (multiplexing) — multiple logical streams over a single TCP connection, reduces handshakes and improves performance
• System tray integration (Windows) — minimize to tray, status icon updates in real time, exit cleanly
• Single instance — clicking the shortcut a second time brings the existing window to focus
• Live logs — real-time connection log with color coding, copyable to clipboard
• Ping display — measures TCP round-trip time to the server before connecting
• Secure config storage — invite link is stored via platform secure storage; legacy plain-text storage is migrated automatically
• Traffic & speed statistics — live upload, download and current speed in the main screen
• Auto-reconnect — reconnects an active session after a network change
• Windows fail-closed protection — if xray/tun2socks exits unexpectedly, the active proxy/TUN routes remain until manual disconnect

---

Architecture

lib/
├── main.dart                    # App entry, window_manager + tray init
├── screens/
│   ├── home_screen.dart         # Main UI — connect button, mode toggle, stats
│   └── config_screen.dart       # Invite link input + live logs
└── services/
    ├── vpn_backend.dart          # Abstract backend interface
    ├── vpn_service.dart          # Facade — picks backend by platform
    ├── windows_vpn_backend.dart  # Windows: xray.exe + system proxy / TUN
    ├── android_vpn_backend.dart  # Android: flutter_v2ray + tun2socks
    ├── tray_service.dart         # Windows tray icon + context menu
    └── vpn_traffic_stats.dart    # Traffic counters and speed model

Windows — System Proxy mode

Flutter UI
  └─ WindowsVpnBackend
        ├─ extracts bundled xray.exe to AppData
        ├─ writes VLESS config JSON (with Mux enabled)
        ├─ launches xray.exe (SOCKS5 :10808, HTTP :10809)
        └─ sets Windows registry proxy → 127.0.0.1:10809

Windows — TUN Tunnel mode

Flutter UI
  └─ WindowsVpnBackend
        ├─ launches xray.exe (SOCKS5 :10808, Mux enabled)
        ├─ extracts bundled tun2socks.exe + wintun.dll
        ├─ launches tun2socks → WinTUN adapter "tun0"
        ├─ assigns 10.0.0.1/30 to tun0
        ├─ adds bypass route: VPN server IP → real gateway
        └─ adds default route: 0.0.0.0/0 → tun0 (metric 1)

Android — VPN mode

Flutter UI
  └─ AndroidVpnBackend
        ├─ flutter_v2ray starts Xray core (SOCKS5 :1080)
        ├─ Android VpnService creates TUN interface
        ├─ libtun2socks.so bridges TUN → SOCKS5
        └─ all device traffic routed through VPN

Connection pipeline

App → xray (Mux) → 1 TCP conn → Server (Reality) → Internet
         └─ multiplexes all streams over a single encrypted connection

---

Getting Started

Prerequisites

• Flutter 3.x
• Windows: Windows 10/11 x64, Visual Studio 2022 with Desktop development with C++ workload
• Android: Android SDK, Android 5.0+ (API 21+), tested on Android 14

Bundled binaries (Windows only)

Place these files before building:

File	Path	Source
xray.exe	assets/xray/xray.exe	XTLS/Xray-core releases — Xray-windows-64.zip
tun2socks.exe	assets/tun2socks/tun2socks.exe	xjasonlyu/tun2socks releases — tun2socks-windows-amd64.exe
wintun.dll	assets/tun2socks/wintun.dll	wintun.net — amd64/wintun.dll
*.ico	assets/tray/	Tray icons (connected / connecting / disconnected)

Android uses flutter_v2ray which bundles Xray core and tun2socks natively — no extra binaries needed.

Build

Windows:

flutter pub get
flutter build windows

The output is at build\windows\x64\runner\Release\vpn_client.exe.

TUN mode requires Administrator rights. Start the app normally for Proxy mode, and run as Administrator only when you need TUN mode.

Android:

flutter pub get
flutter build apk

The APK is at build/app/outputs/flutter-apk/app-release.apk.

⚠️ AndroidManifest.xml already has android:extractNativeLibs="true" and build.gradle.kts has useLegacyPackaging = true. Keep both: otherwise libtun2socks.so stays inside the APK and can't be executed as a process.

Android release signing

For a distributable APK, create android/key.properties (it is gitignored) and point it to your keystore:

storePassword=YOUR_STORE_PASSWORD
keyPassword=YOUR_KEY_PASSWORD
keyAlias=upload
storeFile=C:/path/to/upload-keystore.jks

Without this file, local release builds deliberately fall back to the debug key. Do not publish that APK to an app store.

Run in development

Windows:

flutter run -d windows

For TUN mode, run the terminal as Administrator before launch.

Android:

flutter run -d <device_id>

---

Usage

1. Launch the app
2. Click the gear icon → paste your vless://... invite link → Save
3. Windows: choose mode with the toggle at the bottom:
   • System Proxy — browsers and most apps
   • TUN Tunnel — all OS traffic (full VPN)
4. Android: tap the shield button → accept VPN permission → connected
5. Closing the window on Windows minimizes to tray. Right-click the tray icon → Exit to quit

Server requirements

The client is designed for VLESS + Reality servers. Recommended setup:

• Panel: 3x-ui or similar
• Protocol: VLESS
• Network: TCP
• Security: Reality
• Flow: (leave empty — Mux is used instead of xtls-rprx-vision)
• uTLS fingerprint: chrome

⚠️ Important: Do not enable xtls-rprx-vision flow on the server — it is incompatible with Mux multiplexing.

⚠️ Reality target: choose a target with a compact TLS certificate chain. one.one.one.one:443 is a known-working option with xray 26.6.22; targets with very large chains can make the Reality handshake fail.

---

Roadmap

• Windows — System Proxy mode
• Windows — TUN Tunnel mode
• Android — full VPN mode
• System tray with live status
• VLESS + Reality support
• Mux multiplexing
• Auto-reconnect on network change
• Windows fail-closed protection for xray/tun2socks crashes (not a full OS-wide kill switch; IPv6 and apps that ignore the Windows system proxy are future work)
• Traffic / speed stats
• iOS support
• Multiple server profiles
• Split tunneling

---

Dependencies

Package	Purpose
window_manager	Window controls, prevent-close → minimize to tray
tray_manager	System tray icon and context menu
windows_single_instance	Single app instance enforcement
flutter_secure_storage	Encrypted platform storage for the invite link
shared_preferences	One-time migration from legacy config storage
connectivity_plus	Detect network changes for auto-reconnect
path_provider	AppData directory for extracted binaries
flutter_v2ray	Android VPN backend (Xray core + tun2socks)

---

License

GPL-3.0