How v2rayN Implements TUN Mode for Xray and sing-box Cores

v2rayN implements TUN mode by forcing a switch to the sing-box core when enabled, injecting TUN parameters into the inbound configuration, while falling back to WireGuard-style MTU handling for the legacy Xray core.

The open-source proxy client v2rayN (2dust/v2rayN) provides transparent proxying through TUN mode, but its implementation differs significantly depending on whether the active core is the modern sing-box or the legacy Xray (V2Ray-compatible) core. This article examines the architecture, configuration flow, and core-specific code paths that enable v2rayN TUN mode functionality.

Configuration Architecture

v2rayN separates TUN settings into a dedicated configuration model, ensuring consistent state across the UI and core generation layers.

TunModeItem Model

All TUN-related settings are encapsulated in the TunModeItem class defined in ConfigItems.cs. This model includes:

• EnableTun: The master boolean switch that triggers core selection
• AutoRoute: Controls whether to add a default route forwarding all traffic
• StrictRoute: Restricts routing to specific IP ranges defined in sing-box rules
• Stack: Network stack implementation (system, gvisor, or mixed)
• Mtu: Maximum transmission unit size for the virtual interface
• EnableIPv6Address: Boolean to assign an IPv6 address to the TUN interface

Source: v2rayN/ServiceLib/Models/ConfigItems.cs lines 140+【/v2rayN/ServiceLib/Models/ConfigItems.cs#L140】

UI and ViewModel Layer

The OptionSettingViewModel.cs handles persistence of TUN settings between the UI and the configuration model. It loads values from _config.TunModeItem during initialization (lines 218-222) and writes them back on save (lines 377-381).

For quick toggling, StatusBarViewModel.cs exposes the DoEnableTun(bool c) method (lines 467-479), which updates the configuration and validates administrator rights when the user clicks the "Enable TUN" checkbox in the status bar (lines 104-112).

Core Selection Logic

v2rayN uses the TUN enable flag to determine which core binary to launch, as only sing-box provides native TUN support.

When the configuration loads, ConfigHandler.cs evaluates the flag:

var preCoreType = AppManager.Instance.RunningCoreType =
    config.TunModeItem.EnableTun ? ECoreType.sing_box : ECoreType.Xray;

Source: ConfigHandler.cs lines 1243-1245【/v2rayN/ServiceLib/Handler/ConfigHandler.cs#L1243-L1245】

The CoreManager.cs subsequently checks this flag before launching the core process (lines 92-95), ensuring that attempting to enable TUN without sing-box selected will automatically switch the active core.

Implementation by Core Type

sing-box Native TUN Support

When sing-box is selected, v2rayN injects a tun inbound configuration via SingboxInboundService.cs. The service maps the TunModeItem properties directly to sing-box's JSON schema:

tunInbound.mtu = _config.TunModeItem.Mtu;
tunInbound.auto_route = _config.TunModeItem.AutoRoute;
tunInbound.strict_route = _config.TunModeItem.StrictRoute;
tunInbound.stack = _config.TunModeItem.Stack;
if (_config.TunModeItem.EnableIPv6Address == false) { 
    // Disable IPv6 addressing 
}

Source: SingboxInboundService.cs lines 55-70【/v2rayN/ServiceLib/Services/CoreConfig/Singbox/SingboxInboundService.cs#L55-L70】

For outbound WireGuard connections when sing-box is active, SingboxOutboundService.cs applies the MTU setting from the global configuration (lines 314-315).

Xray Fallback Handling

The legacy Xray core lacks native TUN capabilities. When TUN mode is disabled (and Xray is selected), v2rayN falls back to WireGuard-style tunneling with basic MTU handling in V2rayOutboundService.cs:

mtu = protocolExtra.WgMtu > 0 ? protocolExtra.WgMtu : Global.TunMtus.First();

Source: V2rayOutboundService.cs lines 294-295【/v2rayN/ServiceLib/Services/CoreConfig/V2ray/V2rayOutboundService.cs#L294-L295】

Additional V2Ray-specific logic checks IsTunEnabled in CoreConfigV2rayService.cs (line 18) to apply route adjustments, but true transparent proxying requires switching to sing-box.

End-to-End Workflow

1. Configuration: User sets MTU, stack, and routing preferences in the TUN Mode tab, persisted via OptionSettingViewModel
2. Activation: User toggles "Enable TUN" in the status bar, triggering StatusBarViewModel.DoEnableTun
3. Core Selection: ConfigHandler forces ECoreType.sing_box when EnableTun is true
4. Process Launch: CoreManager starts the sing-box binary with the TUN flag validated
5. Config Generation: SingboxInboundService injects the tun inbound with user-specified parameters
6. Interface Creation: sing-box creates the virtual network interface, applying auto-route or strict-route rules as configured

Summary

• v2rayN implements TUN mode through a unified configuration model (TunModeItem) that persists settings across the application lifecycle
• Core selection is automatic: enabling TUN forces the application to use sing-box instead of Xray, as only sing-box provides native TUN inbound support
• For sing-box, v2rayN generates a complete tun inbound configuration with MTU, stack type, and routing rules via SingboxInboundService
• For Xray, TUN functionality is unavailable; the core only receives basic WireGuard MTU fallback handling when TUN mode is disabled
• The implementation spans the Model-View-ViewModel pattern, with clear separation between UI (StatusBarViewModel, OptionSettingViewModel), business logic (ConfigHandler), and core-specific services

Frequently Asked Questions

What is TUN mode in v2rayN?

TUN mode in v2rayN creates a virtual network interface that captures all system traffic (Layer 3/IP layer) and routes it through the proxy, enabling transparent proxying for applications that don't support SOCKS or HTTP proxies. When enabled, v2rayN automatically switches to the sing-box core to provide this functionality.

Why does v2rayN switch to sing-box when TUN mode is enabled?

v2rayN switches to sing-box because Xray does not implement native TUN support. The sing-box core includes a built-in tun inbound that can create and manage virtual network interfaces across Windows, Linux, and macOS. The core selection logic in ConfigHandler.cs explicitly forces ECoreType.sing_box when EnableTun is true to ensure compatibility.

How do I configure TUN mode settings in v2rayN?

Configure TUN settings through Options → TUN Mode Settings, where you can adjust the MTU size, select the network stack (system, gvisor, or mixed), enable auto-route or strict-route, and toggle IPv6 addressing. These values are stored in the TunModeItem configuration model and injected into the sing-box configuration when the core starts.

Can I use TUN mode with the Xray core?

No, TUN mode requires the sing-box core. If you attempt to enable TUN while using Xray, v2rayN automatically switches the active core to sing-box. The Xray core only supports traditional proxy protocols (SOCKS, HTTP, VMess, etc.) and lacks the virtual network interface capabilities required for transparent proxying at the IP layer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}