TUN Mode: The Technical Evolution of Seamless Network Support for AI Tools | TongBao VPN

1. Background: The Networking Dilemma of AI Development Tools

As AI coding assistants (Claude Code, GitHub Copilot, Cursor, etc.), AI conversation tools (ChatGPT, Claude), and package managers (npm, pip, cargo) increasingly become core components of developer workflows, a long-overlooked problem has emerged: system proxy settings cannot cover all application network traffic.

Under the traditional System Proxy mode:

Scenario	Automatically Routed Through Proxy?
Browser accessing ChatGPT	Yes
VS Code built-in browser	Yes
Terminal running npm install	No, requires manual HTTP_PROXY setup
Claude Code CLI	No, requires manual environment variable configuration
IDE built-in AI completion	Uncertain, depends on implementation
pip install / cargo build	No

Developers are forced to repeatedly configure HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and other environment variables, or even set up proxy parameters individually for each tool. This is not only tedious but also highly error-prone——forgetting to configure a single terminal window can lead to connection timeouts and dependency installation failures.

2. Core Advantages of TUN Mode

TUN (Tunnel) mode creates a virtual network adapter at the system level, intercepting all traffic at the lowest layer of the network stack, fundamentally solving the problems described above.

┌─────────────────────────────────────────────┐
│ Application Layer (Browser/Terminal/IDE/AI Tools) │
│ ChatGPT Claude Code npm pip Cursor │
└──────────────────┬──────────────────────────┘
│ All Traffic
▼
┌──────────────────────────────────────────────┐
│ TUN Virtual NIC (198.18.0.1) │
│ tun2socks → SOCKS5 Proxy │
└──────────────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Xray Proxy Core (Smart/Global Routing) │
└──────────────────────────────────────────────┘

With TUN mode enabled, terminals, IDEs, and AI tools require zero additional configuration to automatically route traffic through the proxy.

"Captures all network traffic — terminals, IDEs, and AI tools need no extra configuration"

3. Specific Benefits for AI Development Workflows

3.1 Claude Code / Cursor and Other AI CLI Tools: Zero-Config Ready

Previously, when using Claude Code, users had to:

# Before: Set up every time you open a terminal
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
claude  # Only then could it connect
​

With TUN mode:

# Now: Just use it, no extra steps needed
claude  # Automatically routed through proxy, instant connection
​

3.2 AI Model API Calls: Seamless Development and Testing

When developing applications with OpenAI, Anthropic, and other APIs, there is no longer any need to hardcode proxy configurations or inject proxy variables into the runtime environment. TUN mode automatically routes requests from fetch, axios, httpx, and other HTTP clients at the operating system level.

3.3 Package Managers and Dependency Downloads: No More Timeouts

npm install, pip install, cargo build, go get and other commands are all automatically routed through the proxy under TUN mode, eliminating dependency installation failures and prolonged wait times caused by network connectivity issues.

3.4 Git Operations: Push and Pull with Ease

git clone, git push, git pull and other SSH/HTTPS Git operations are fully covered by TUN, with no need to configure a proxy for Git separately.

4. Stability Safeguards

TUN mode deeply integrates with the system network stack. If handled improperly, it can cause a complete loss of internet connectivity. We ensure stability through the following mechanisms:

4.1 Anti-Routing Loop

Proxy server IP → Original gateway (bypasses TUN)
Direct-connect IPs → Original gateway (bypasses TUN)
0.0.0.0/1         → TUN (proxies all other traffic)
128.0.0.0/1       → TUN
​

The proxy server's own traffic is excluded from TUN, preventing a "proxy proxying itself" infinite loop.

4.2 Watchdog Process Guardian

The privileged helper process includes a built-in Watchdog mechanism that checks every 5 seconds whether the Electron main process is alive. If the main process crashes or is unexpectedly killed, the Watchdog automatically performs cleanup:

• Removes TUN routing rules
• Restores original DNS configuration
• Terminates the tun2socks process
• Restores the system network to its normal state

Even if the application crashes, the user's internet connectivity is never disrupted.

4.3 DNS Leak Protection

TUN mode forces DNS queries to route through 8.8.8.8 and 1.1.1.1, preventing DNS resolution pollution or leaks caused by local ISP routing, ensuring that AI tools can correctly resolve domains such as api.openai.com and api.anthropic.com.

4.4 Cross-Platform Privileged Helper Services

Platform	Implementation	IPC Channel
macOS	Privileged helper process (launchd)	Unix Socket (/var/run/sulian-helper.sock)
Windows	Windows Service (SulianHelper)	Named Pipe (\\.\pipe\sulian-helper)
Linux	pkexec privilege escalation	Direct process management

Each platform uses an independent privileged service to perform network operations. The main process itself does not require elevated privileges, adhering to the principle of least privilege.

4.5 Graceful Error Recovery

When TUN fails to start (e.g., Helper not installed), the system will:

• Automatically detect the error type ("helper service", "Access is denied", etc.)
• Trigger a Helper installation guidance dialog
• Guide the user through one-click privileged service installation
• Automatically retry the connection after installation completes

5. Smart Routing and Global Routing

TUN mode supports two routing strategies:

• Global Proxy: All traffic is routed through the proxy, ideal for scenarios requiring maximum AI service stability
• Smart Split Routing: Domestic domains/IPs connect directly while overseas traffic goes through the proxy——ensuring AI tool accessibility without affecting domestic service speeds

6. Technical Implementation Details

Startup Flow

1. Extract proxy server IP from Xray configuration
   ↓
2. Resolve domain to IP (prevent routing loops)
   ↓
3. Detect system default gateway and local NIC
   ↓
4. Initialize platform privileged service
   - macOS: Privileged helper / osascript fallback
   - Windows: Windows Service
   - Linux: tun2socks direct process management
   ↓
5. Create TUN virtual NIC (198.18.0.1)
   ↓
6. Configure split routing rules
   - Proxy server IP → Original gateway
   - Direct-connect IPs → Original gateway
   - 0.0.0.0/1 + 128.0.0.0/1 → TUN
   ↓
7. Configure DNS (8.8.8.8, 1.1.1.1)
   ↓
8. Start Watchdog process guardian
​

Key Components

Component	Purpose
tun2socks	Forwards TUN NIC traffic to SOCKS5 proxy
wintun.dll	Windows TUN driver (from WireGuard)
sulian-helper	Cross-platform privileged helper service (written in Go)
Xray	Proxy core with multi-protocol and smart routing support

7. Summary

Dimension	System Proxy Mode	TUN Mode
Browser	Automatic	Automatic
Terminal / CLI	Manual configuration required	Automatic
AI Tools (Claude Code, etc.)	Manual configuration required	Automatic
IDE AI Completion	Uncertain	Automatic
Package Managers	Manual configuration required	Automatic
Git SSH/HTTPS	Manual configuration required	Automatic
Network Recovery After Crash	N/A	Watchdog Auto-Recovery
DNS Leak Protection	None	Yes

The TUN mode transformation essentially pushes the burden of "proxy configuration" — a long-standing pain point for developers — from the application layer down to the operating system layer. For modern development workflows that increasingly rely on AI tools, TUN mode is not a nice-to-have; it is a true infrastructure-level improvement——freeing developers to focus on coding and creating, rather than endlessly troubleshooting "why can't I connect."