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

> Discover how v2rayN implements TUN mode using sing-box and Xray cores. Learn about parameter injection and MTU handling for enhanced network control.

- Repository: [2dust/v2rayN](https://github.com/2dust/v2rayN)
- Tags: internals
- Published: 2026-02-27

---

**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`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/v2rayN/ServiceLib/Models/ConfigItems.cs) lines 140+【/v2rayN/ServiceLib/Models/ConfigItems.cs#L140】

### UI and ViewModel Layer

The [`OptionSettingViewModel.cs`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/ConfigHandler.cs) evaluates the flag:

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

```

*Source*: [`ConfigHandler.cs`](https://github.com/2dust/v2rayN/blob/main/ConfigHandler.cs) lines 1243-1245【/v2rayN/ServiceLib/Handler/ConfigHandler.cs#L1243-L1245】

The [`CoreManager.cs`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/SingboxInboundService.cs). The service maps the `TunModeItem` properties directly to sing-box's JSON schema:

```csharp
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`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/V2rayOutboundService.cs):

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

```

*Source*: [`V2rayOutboundService.cs`](https://github.com/2dust/v2rayN/blob/main/V2rayOutboundService.cs) lines 294-295【/v2rayN/ServiceLib/Services/CoreConfig/V2ray/V2rayOutboundService.cs#L294-L295】

Additional V2Ray-specific logic checks `IsTunEnabled` in [`CoreConfigV2rayService.cs`](https://github.com/2dust/v2rayN/blob/main/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`](https://github.com/2dust/v2rayN/blob/main/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.