TUN Mode Routing

Relevant source files

The following files were used as context for generating this wiki page:

• README_en.md
• FEATURES.md
• packages/shared/src/index.js
• apps/desktop/src/main.js
• apps/desktop/src/ui/ui-polish.test.js

TUN Mode Routing implements a system-level virtual network interface within Zephyr to capture and route all device traffic through the Mihomo proxy core. Unlike standard system proxies that rely on application-level settings, TUN mode operates at the network layer to ensure comprehensive coverage across all applications on Windows, macOS, and Linux. Sources: README_en.md, FEATURES.md

The system provides cross-platform virtual adapter management, automatic DNS hijacking to prevent leaks, and privileged execution handling for network interface modifications. It integrates with the Zephyr UI through real-time status indicators and persistent configuration locks to prevent state desynchronization during core failures or restarts. Sources: FEATURES.md, apps/desktop/src/ui/ui-polish.test.js

Architecture and Components

The TUN system uses a multi-layered architecture involving the native Rust backend for privileged operations and the JavaScript frontend for state management and user interaction.

Core Components

Component	Description
TunManager	Backend module in Rust that manages virtual interface lifecycle, privilege escalation, and cleanup.
Virtual Adapter	The OS-level network interface (TUN) that captures IP packets.
DNS Hijacker	Injects dns-hijack rules into the Mihomo configuration to capture and route DNS traffic.
Privilege Escalator	Handles platform-specific elevation (e.g., osascript on macOS, pkexec or setcap on Linux).
TUN UI Module	Manages the toggle states, status labels, and synchronization with the global application store.

Sources: FEATURES.md, apps/desktop/src/ui/ui-polish.test.js, packages/shared/src/index.js

Data and Control Flow

The following diagram illustrates the interaction between the user interface, the application store, and the backend commands when enabling TUN mode.

Platform Implementation Details

TUN mode requires different handling based on the host operating system to manage permissions and network stack optimizations.

Privileged Operations

The backend handles elevation automatically depending on the platform:

• macOS: Uses osascript for privileged core restarts when TUN is requested. Sources: FEATURES.md, apps/desktop/src/main.js:154-156
• Linux: Manages permissions via pkexec, setcap, or polkit. It also supports persistence for network optimizations in /etc/sysctl.d/. Sources: README_en.md, FEATURES.md
• Windows: Implements UWP loopback exemptions to allow Windows Store apps to access the local proxy. It also applies TCP optimizations like Fast Open and ECN. Sources: README_en.md, FEATURES.md

Error Recovery and Resilience

If a TUN start fails (specifically on macOS), the system attempts a retry without TUN to ensure the core remains functional.

1. The backend returns a tun_start_failed error.
2. The frontend records the failure and sets the TUN preference to false.
3. The system retries start_core with the non-TUN configuration path.
4. If the retry succeeds, the user receives a warning notification.

Sources: apps/desktop/src/main.js:154-180

Configuration and IPC Interface

The TUN system is controlled via a specific set of IPC commands defined in the shared package.

Command Constant	IPC Endpoint	Action
SET_TUN_ENABLED	set_tun_enabled	Toggles the virtual interface in the core.
RESTART_AS_ROOT	restart_core_as_root_cmd	Escalates privileges to start the core with TUN.
GRANT_LINUX_PERMISSION	grant_linux_tun_permission	Triggers Linux-specific permission granting.
APPLY_WINDOWS_TCP_OPTIMIZATIONS	apply_windows_tcp_optimizations	Tunes Windows network stack for TUN.
RECORD_TUN_ENABLED	record_tun_enabled	Persists the TUN preference without triggering a restart.

Sources: packages/shared/src/index.js:68-84

Security Design

TUN mode includes several "defense-in-depth" features to ensure network privacy:

• DNS Leak Prevention: The system automatically injects dns-hijack into the configuration to capture all DNS traffic and route it through Mihomo. Sources: README_en.md, FEATURES.md
• Atomic Locking: Uses atomic locks to prevent concurrent modification of the network interface. Sources: FEATURES.md
• Ownership Guard: Monitors the system proxy and network state, implementing tamper detection and auto-recovery on failure. Sources: FEATURES.md

UI Synchronization

The Zephyr UI uses a reactive binding system to ensure TUN status is accurately reflected across the Sidebar, Home Page, and System Tray.

Status labels are localized across 14 languages. The renderTunStatus function writes localized text and color classes (e.g., text-accent for active) to the DOM based on the current state. Sources: apps/desktop/src/ui/ui-polish.test.js:46-60

Summary

TUN Mode Routing provides Zephyr with a robust network-level proxy capability. By leveraging a virtual network adapter and platform-specific privileged execution, it captures traffic from all applications while preventing DNS leaks through automatic hijacking. The system includes built-in recovery logic to revert to standard proxy modes if the TUN interface fails to initialize, ensuring continuous connectivity. Sources: FEATURES.md, apps/desktop/src/main.js