How v2rayN Manages Multiple Core Types: Xray, sing-box, v2fly, mihomo, and hysteria

v2rayN decouples core selection from the UI by using an enum-based registry (ECoreType), a metadata manager (CoreInfoManager), and runtime resolution logic (AppManager) to dynamically launch the correct proxy binary with platform-specific arguments.

v2rayN is a cross-platform GUI client for V2Ray and related proxy cores. Unlike single-core clients, v2rayN manages multiple core types—including Xray, sing-box, v2fly, mihomo, and hysteria—through a modular architecture that separates core metadata from execution logic. This design allows users to switch between proxy engines without recreating server profiles.

The Core Type Registry Architecture

Defining Supported Cores with ECoreType

The foundation of v2rayN’s multi-core support is the ECoreType enumeration located in v2rayN/ServiceLib/Enums/ECoreType.cs. This enum assigns a distinct integer value to every supported core binary, enabling type-safe identification throughout the application:

public enum ECoreType
{
    Xray = 0,
    v2fly = 1,
    v2fly_v5 = 2,
    sing_box = 3,
    mihomo = 4,
    hysteria = 5,
    // ... additional cores
}

Centralizing Core Metadata in CoreInfoManager

Core-specific metadata—including executable names, download URLs, command-line arguments, and environment variables—is centralized in v2rayN/ServiceLib/Manager/CoreInfoManager.cs. The InitCoreInfo() method lazily populates a private _coreInfo list with CoreInfo objects containing platform-specific details:

private void InitCoreInfo()
{
    _coreInfo = [
        new CoreInfo {
            CoreType = ECoreType.Xray,
            CoreExes = ["xray", "xray.exe"],
            Arguments = "run -c {0}",
            Url = urlXray,
            ReleaseApiUrl = urlXray.Replace(Global.GithubUrl, Global.GithubApiUrl),
            DownloadUrlWin64 = urlXray + "/download/{0}/Xray-windows-64.zip",
            Match = "Xray",
            VersionArg = "--version",
        },
        // ... sing-box, mihomo, hysteria entries
    ];
}

Key methods include:

• GetCoreInfo(ECoreType coreType) – Retrieves metadata for a specific core.
• GetCoreExecFile(CoreInfo coreInfo, out string error) – Resolves the absolute path to the core binary.

Exposing Cores to the UI via Global.CoreTypes

To populate dropdown menus in the user interface, v2rayN maintains Global.CoreTypes in v2rayN/ServiceLib/Global.cs (lines 301-307). This list provides the binding source for "Core type" selectors in OptionSettingWindow and AddServerWindow:

public static List<string> CoreTypes { get; set; } = new List<string> {
    "Xray",
    "sing-box",
    "v2fly",
    "mihomo",
    "hysteria"
};

Runtime Core Selection and Compatibility

Profile-Level Core Assignment Logic

When a user launches a connection, v2rayN determines which binary to execute using AppManager.GetCoreType() in v2rayN/ServiceLib/Manager/AppManager.cs (lines 504-512). The method implements a two-tier fallback strategy:

1. Explicit Profile Setting – Checks profile.CoreType field stored in the database.
2. Global Default – Falls back to the global mapping _config.CoreTypeItem if no profile-specific core is set.

public ECoreType GetCoreType(ProfileItem profile, EConfigType configType)
{
    // Check profile-specific override
    if (!Utils.IsNullOrEmpty(profile.CoreType))
    {
        return Utils.GetCoreType(profile.CoreType);
    }
    
    // Fall back to global configuration
    return Utils.GetCoreType(_config.CoreTypeItem);
}

Cross-Core Compatibility Mapping

v2rayN allows certain cores to handle configurations from other compatible engines. The AppManager.IsRunningCore() method (lines 38-48) implements these compatibility rules:

• Xray can execute v2fly and v2fly_v5 configurations.
• sing-box can execute mihomo configurations.

This enables the UI to show core-specific options (e.g., mihomo-only DNS settings) while maintaining backward compatibility.

Executing and Configuring Selected Cores

Process Management in CoreManager

The CoreManager class in v2rayN/ServiceLib/Manager/CoreManager.cs handles the actual process lifecycle. The CoreStart() method (lines 78-89) orchestrates the launch sequence:

1. Retrieves core metadata via CoreInfoManager.Instance.GetCoreInfo(coreType).
2. Resolves the executable path using GetCoreExecFile().
3. Formats command-line arguments (e.g., "run -c {0}" becomes "run -c config.json").
4. Handles sudo elevation on Linux/macOS when required.

public async Task CoreStart(ProfileItem profile)
{
    ECoreType coreType = AppManager.Instance.GetCoreType(profile, profile.ConfigType);
    CoreInfo? coreInfo = CoreInfoManager.Instance.GetCoreInfo(coreType);
    
    string exePath = CoreInfoManager.Instance.GetCoreExecFile(coreInfo, out string error);
    string args = string.Format(coreInfo.Arguments, configFilePath);
    
    await RunProcess(exePath, args, coreInfo.EnvironmentVariables);
}

Configuration File Generation

Different cores require different configuration formats. The CoreConfigHandler in v2rayN/ServiceLib/Handler/CoreConfigHandler.cs generates the appropriate syntax:

• JSON format for Xray, v2fly, and v2fly_v5.
• YAML format for sing-box, mihomo, and hysteria.

The handler adapts profile settings (server addresses, encryption methods, routing rules) to each core's specific schema requirements before CoreManager launches the process.

Extending v2rayN with New Core Types

To add support for a hypothetical "mycore" binary, you must modify three key files:

// 1. v2rayN/ServiceLib/Enums/ECoreType.cs
public enum ECoreType
{
    // ... existing values ...
    mycore = 31,
}

// 2. v2rayN/ServiceLib/Manager/CoreInfoManager.cs
private void InitCoreInfo()
{
    _coreInfo = [
        // ... existing entries ...
        new CoreInfo {
            CoreType = ECoreType.mycore,
            CoreExes = ["mycore", "mycore.exe"],
            Arguments = "run -c {0}",
            Url = urlMycore,
            ReleaseApiUrl = urlMycore.Replace(Global.GithubUrl, Global.GithubApiUrl),
            DownloadUrlWin64 = urlMycore + "/download/{0}/mycore-windows-64.zip",
            Match = "MyCore",
            VersionArg = "--version",
        },
    ];
}

// 3. v2rayN/ServiceLib/Global.cs
public static List<string> CoreTypes { get; set; } = new List<string> {
    "Xray",
    "sing-box",
    "v2fly",
    "mihomo",
    "hysteria",
    "mycore"
};

Summary

• ECoreType enum provides type-safe identification of each supported core binary in ECoreType.cs.
• CoreInfoManager centralizes metadata including download URLs, executable names, and launch arguments in CoreInfoManager.cs.
• Global.CoreTypes exposes available cores to UI dropdowns defined in Global.cs.
• AppManager.GetCoreType implements the selection logic that checks profile-specific settings before falling back to global defaults.
• CoreManager handles process execution, resolving binary paths via GetCoreExecFile and formatting command-line arguments.
• CoreConfigHandler generates core-specific configuration formats (JSON for Xray/v2fly, YAML for sing-box/mihomo).

Frequently Asked Questions

How does v2rayN decide which core to use for a specific server profile?

v2rayN uses the AppManager.GetCoreType() method in AppManager.cs (lines 504-512) to determine the active core. It first checks if the ProfileItem has an explicit CoreType value stored in the database. If the profile-specific field is empty, it falls back to the global default core configured in _config.CoreTypeItem.

Can v2rayN run configurations from one core type using a different core binary?

Yes, v2rayN implements compatibility mapping in AppManager.IsRunningCore() (lines 38-48). For example, the Xray core can execute configurations originally designed for v2fly or v2fly_v5, and sing-box can handle mihomo configurations. This allows users to switch cores without recreating their server profiles.

What files must be modified to add support for a new proxy core in v2rayN?

Adding a new core requires changes to three files: first, extend the ECoreType enum in ECoreType.cs with a new integer value; second, register the core's metadata (executable names, download URLs, arguments) in CoreInfoManager.cs within the InitCoreInfo() method; third, add the display name to Global.CoreTypes in Global.cs to expose it in the UI dropdowns.

How does v2rayN handle different configuration file formats for each core?

v2rayN uses the CoreConfigHandler class in CoreConfigHandler.cs to generate core-specific configuration syntax. It produces JSON configuration files for Xray, v2fly, and v2fly_v5 cores, while generating YAML files for sing-box, mihomo, and hysteria. The handler adapts profile settings to each core's specific schema requirements before the CoreManager launches the process.

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