The Complete v2rayN Guide

1. Core Concepts: Clients, Cores, and Connection Paths

Separate the interface from the engine

v2rayN is a graphical client that stores server settings, organizes subscription groups, configures the proxy entry point, and launches the core. The core establishes connections, interprets routing rules, and handles protocols and transports. A working interface does not mean the core has started; a running core does not mean the browser is sending requests through it. Understanding these two layers helps break “can't connect” into specific, testable steps instead of repeatedly reinstalling the entire client.

Project V provides the ecosystem behind related proxy technologies. V2Fly and Xray are related but independently developed core projects. Their supported fields, transport combinations, and extensions are not identical. A protocol option in the client only means there is a configuration entry for it; whether it works depends on the selected core, server settings, and current build. When something is incompatible, check these factors first rather than comparing protocol names alone.

Follow the request path to understand the settings

A typical desktop connection passes through an application, the system proxy or the application's own proxy, a local listening endpoint, routing rules, an outbound, and a remote server. The entry point is usually called an inbound; it determines how the core receives traffic. The outbound determines how a connection leaves the core. Common outbounds include a proxy server, direct connection, and blocking. Subscriptions provide server details; routing rules determine which outbounds requests use. They solve different problems.

A node is not just an address-book entry with fields you can swap at will. The server address, port, user ID, protocol, transport, and TLS settings together define the connection. A domain can be used to locate a server or to verify its TLS service name, and those names may differ. The transport path, hostname, and service name may also be used to match the server. A server address alone is rarely enough to determine the other settings.

Understand the roles of protocols, transports, and encryption

VMess, VLESS, and Trojan differ in authentication and protocol behavior; TCP, WebSocket, and gRPC are transport choices at a different layer. TLS provides encryption and identity verification for applicable connections, while REALITY has its own parameter requirements. A connection can still fail when the protocol name matches but the transport or security settings do not. Check subscription entries layer by layer rather than assuming a protocol always implies a particular encryption or transport setup.

DNS resolves names to addresses, but where resolution happens can affect routing. If an application resolves a name before connecting, the core may see only the destination IP. If the application passes the domain name, the core may be able to apply domain-based rules. System proxy settings generally rely on applications honoring them; TUN receives matching traffic through a virtual network interface. These entry points cover different traffic, but may still use the same routing rules and outbounds, so the entry point alone does not tell you the final connection path.

Before moving on, be able to distinguish three outcomes: the client saved the settings, the core accepted them, and the application request actually used them. Confirm the first in the interface, the second in startup output, and the third by cross-checking runtime logs with an application test. Look up unfamiliar terms in the glossary, but you do not need to learn every protocol detail before your first connection. Establishing the full path matters more than memorizing every field.

2. Choose a Client: Platform, Core, and Use Case

Start with v2rayN on desktop

For Windows, macOS, and Linux desktops, start with v2rayN. Using the same client helps keep subscription groups and troubleshooting habits consistent, but it does not mean the menus, permissions, or traffic-capture methods are identical across operating systems. Follow the labels shown in your current interface. If you cannot find a setting, check the platform and interface first rather than copying another system's configuration paths or permission steps.

The Windows download page offers a desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface and suits users who want a similar workflow across desktop systems. The classic WPF edition keeps the traditional window layout and may suit existing users. You do not need to install both. Choose one for the initial setup, test the connection, then decide whether to migrate. This avoids two instances competing for a listening port or repeatedly overwriting the system proxy.

Choose an Android core based on your needs

For Android, start with v2rayNG, which commonly uses the Xray core; v2flyNG is an alternative based on the V2Fly core. Choose based on your server settings and the features you need, not on similar names. If a configuration depends on a specific core feature, confirm that the other client supports it before switching. A successful import only means the entry was parsed and saved; it does not guarantee that the core will use every extension field.

Match the installation package to your device's architecture. Most recent Android devices use arm64, but consider both the processor and the actual system environment. If unsure, check the system information or choose the universal build offered on the download page. Desktops may also require a choice between x64 and arm64; for macOS, choose Apple Silicon or Intel. A mismatched architecture usually causes installation to fail or the app not to launch—not a subscription or network problem.

Factor migration effort into your choice

Subscription URLs may work across clients, but local settings usually cannot be transferred directly. System proxy settings, application routing, routing templates, DNS, and TUN options may use client-specific formats. When migrating, import the server details first, then recreate behavior settings one by one. Copying an entire data directory can bring incompatible fields, old paths, or local ports along with it, making problems in the new setup harder to diagnose.

Also consider whether the device is managed by an organization, whether virtual network interfaces can be installed, and whether other network tools are already running. If system permissions are restricted, start with the application's own proxy or a standard system proxy; TUN is not required for a successful installation. If the device already has a working network setup, note its original proxy and DNS settings. Client choice cannot bypass system policy, and layering multiple tools makes it harder to tell which one is active.

By the end of this chapter, choose one client, one installation source, and one initial connection method. On desktop, start by testing a standard proxy; on Android, follow the system prompts to grant network access. Choose a package for your platform on the client download page; do not keep trying packages for different architectures. Record why you chose it so you can later distinguish platform limits, interface differences, and core capabilities.

3. Install and Launch: Set Up a Recoverable Baseline

Record your network baseline before installing

Before installing, check the device's network state with the client turned off. Note whether a system proxy address is already set, whether an automatic configuration script is in use, whether DNS is assigned by the network, and whether any other virtual network connections are active. Test a site that already works to establish a baseline for later recovery checks. If the underlying network is already failing, resolve the connection, authentication, or system clock issue first; otherwise, client tests will include unrelated problems.

Install the software for your platform as described on the download page. On Windows, choose one of the two editions. On macOS, select the installer for your chip and follow the system prompts. On Linux, choose deb or rpm based on your distribution, and check the processor architecture. If the system reports a missing runtime, address the specific error. Repeatedly switching servers will not fix an app that has not started correctly, and disabling all system protections is not a sound way to troubleshoot.

On first launch, check the core status

After launching the app, find the runtime log or startup output. Confirm that the core starts, and look for missing files, configuration parse errors, or address conflicts. Component layouts and runtime requirements vary between builds, so an open main window does not prove that all dependencies are in place. If the core exits immediately, keep the earliest error line. Later retries and connection failures are often knock-on effects, so address the first clear error first.

Read the local listening address and port from the current settings. Do not assume a commonly used number in a tutorial is the fixed default, and do not enter an unconfirmed port in another program. If two clients use the same address and port, the one started later may fail to listen. Exit any extra instances and check the startup output. If you need to change the port, update both the client and the application that uses it, and note the new mapping.

Directories, permissions, and background behavior

The configuration directory may vary by platform, installation method, and build. Locate it through the app's settings or its open-directory option instead of assuming a path from another device applies everywhere. If settings remain available after saving and restarting the app, the current account has the required write access. If configuration disappears after exit, check whether you launched a second copy of the app or are using a different account or data directory.

Standard system proxy and TUN have different permission requirements. During the initial installation, establish only the minimum working setup; do not immediately enable startup launch, automatic subscription updates, and every traffic-capture option. Android requires network access approval through a system dialog; desktop TUN may need additional permissions or components. Permission prompts should correspond to the action you just initiated. If the source of a prompt is unclear, cancel it and check the client and its logs.

Finally, verify the normal shutdown process. Turn off traffic capture, exit the client, check that the system proxy has returned to the expected state, and retest the site used for the pre-install baseline. If an application still points to a stopped local port, clear the settings left by this session in the system network settings, while preserving any original organization-managed settings. The base setup is ready only when the client can start, save settings, and restore the network on exit. Subscription issues can then be investigated separately.

If startup is still failing, see Core Startup Failures and Port Conflicts. There is no need to import a large number of servers or switch installation methods at the same time. A clear error record and the current installation location are more useful than accumulating multiple copies on one device.

4. Import Subscriptions and Organize Groups

Handle subscription URLs and node links separately

A subscription URL retrieves server details; an individual node link describes one connection entry. Both can be copied as text, but they may require different import options. In v2rayN, find the subscription group settings, add a clearly named group, enter the subscription URL provided by the source, and save it. Then update that group. Menu labels may change; the important steps are to create a group first, then let the client retrieve and parse its contents.

v2rayNG and v2flyNG usually manage sources through subscription settings or an add-configuration option. First check whether you are importing a subscription or a single configuration, then choose the matching action. Extra text, line breaks, full-width punctuation, or chat-app formatting in the clipboard can prevent a URL from parsing. Query parameters at the end of a URL may be needed for authorization, so do not remove them to shorten it. Teaching examples should use an obvious sample such as https://example.com/sub?token=xxxx.

Use groups to protect local changes

Name groups by source and purpose. Do not include access credentials or rely on promotional names that may change. Keep work tests, everyday use, and manual entries in separate groups if useful. A subscription update may rebuild the entries in a group; whether manual aliases or settings survive depends on the client. Keep custom entries that must persist in a separate group, and note which fields are maintained by the source and which locally.

Updating an existing group is not the same as adding a duplicate group. Updating refreshes the entries from that source; adding another group can create duplicates and make later selection and testing ambiguous. After an update, check for parse errors, confirm the entries are in the expected group, and see whether the previously selected server is still there. If the source removed or renamed it, you may need to confirm the current selection again. An old name still in the list does not prove the remote service is unchanged.

Pinpoint subscription update failures by stage

When an update fails, first distinguish between failure to retrieve the URL and failure to parse its contents. Connection timeouts and DNS errors usually happen during retrieval; a login page, error message, or incompatible content may indicate a parsing issue. Keep the error type when sharing details, but do not reveal the full subscription URL. A page loading in a browser does not mean the client received a usable subscription; confirm that the returned content matches the purpose and import method.

In some environments, subscription updates need a working proxy. If the client offers both direct updates and updates through a proxy, choose based on the current connection state. An update that depends on a proxy can create a loop before any proxy is available: you need a server to update, but need an update to get a server. In that case, use an appropriate import method provided by the source or check the underlying network rather than blindly changing all DNS and TUN settings.

Subscription conversion adds another party that can access the original details, and may discard extension fields the target client does not recognize. Consider conversion only when the source format cannot be imported directly and you understand the processor and output format. Do not treat conversion as the default fix for connection problems. After your first successful setup, record the group name, update method, and test entry. If a later update fails, you can then compare whether the source, retrieval path, or local settings changed.

When moving to another device, recreate the subscription group rather than sharing its URL in a public screenshot. For help with imports, browse the setup and installation section of the FAQ and include the client name, import method, and failure stage. Removing private details from logs usually leaves enough information to diagnose the issue.

5. Proxy Modes: System Proxy, App Proxy, and Global Routing

Decide how applications enter the proxy first

For a first desktop connection, select one server and then enable the system proxy. A common v2rayN setting is “Set system proxy automatically,” which points the system proxy settings supported by the OS to the client's local endpoint. It does not force every network connection through a tunnel. Whether an application uses these settings depends on its own behavior, network library, and any extensions or separate proxy options. A successful setting and coverage of all traffic are two different things.

A browser is usually a good first test, but extensions, separate proxy settings, and automatic configuration scripts can change the path. Reduce these variables and use one clearly defined entry method. Make a fresh request and check whether the corresponding connection appears in the client logs. A page showing old content may simply be cached; a page loading in the browser alone does not prove the request used the proxy. Check the interface result and runtime logs together.

“Global proxy” can refer to different layers

“Global” may mean the system proxy switch, a routing mode that sends all traffic already in the core through a proxy, or TUN capturing a wider range of traffic. These are not interchangeable. The system proxy determines how some applications connect; global routing determines which outbound handles traffic that has entered the core; TUN determines which additional connections are captured. Even if routing is set to proxy everything, an application that ignores the system proxy may never reach the core and may continue using its original network path.

If an application supports HTTP or SOCKS proxies, you can enter the address and port the client is currently listening on. The proxy type must match the listening endpoint; matching port numbers alone do not mean the protocols are the same. If the proxy is only for local use, keep its listening scope limited to your needs rather than enabling LAN access. Allowing other devices to connect changes the exposure, so consider the firewall, access controls, and network you're on.

Test terminal and background apps separately

Terminal programs do not necessarily use the desktop system proxy. Some read process environment variables; others need their own arguments. Do not assume a terminal is configured just because the browser works. The reverse is also true: a working terminal process does not prove that the whole system is covered. Environment variables are usually inherited by a process, so an already-running program may keep old values. Test in a new process and remove temporary settings after testing.

If the browser works but another app does not, check that app's proxy source, bypass list, and request protocol before considering TUN. If the client logs show no matching connection, suspect that the request never reached the entry point. If a connection is logged but fails, check the server, routing, and DNS. See System Proxy Not Working: Browser and Terminal Troubleshooting for more detail. Do not skip the entry-point checks and jump straight to changing remote settings.

By the end of this chapter, keep one minimal working setup: one server, one test app, one entry method, and a clearly chosen routing mode. Turn off conflicting settings before switching modes, then make a fresh request and check the logs. Also test what happens when the client closes, especially to avoid apps continuing to connect to a stopped local port. This repeatable baseline is your control for adding more complex routing rules in the next chapter.

6. Routing: Rule Order, Domain Matching, and DNS

Outbound selection starts after traffic enters the core

Routing handles connections that have entered the core, selecting an outbound based on conditions such as domain, address, and port. Start with a built-in client routing template, such as “Bypass mainland China,” to establish behavior you can explain, then add custom rules. A template name is only a summary; the actual result depends on its rules, resource data, and order. If a destination uses the wrong outbound, check which condition matched instead of relying on the template name to predict every connection.

Rules are usually checked from top to bottom, and the first match determines the result, so specific exceptions generally belong near the top. Domain and IP conditions are not interchangeable: domains describe service names, while addresses describe network ranges. A domain can resolve to multiple addresses, and a shared address can host multiple services. Proxying a broad address range to fix one site can affect unrelated connections.

Read a V2Ray routing snippet

The example below is a routing snippet to merge into a compatible V2Ray configuration, not a complete startup configuration. It sends private addresses to a direct outbound, sends the specified ad category to a blocking outbound, and declares labels for both outbounds. You need the corresponding resource data, and should merge the labels with any existing outbounds of the same name rather than pasting duplicate top-level fields. A graphical client may regenerate the configuration, so prefer its routing editor to express the same intent.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["geosite:category-ads-all"],
        "outboundTag": "block"
      }
    ]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ]
}

outboundTag must refer to an existing outbound label. A label is just a name; it does not create a connection capability. geoip:private matches the relevant private-address category, while geosite:category-ads-all references domain-category data. Missing resources or categories can cause the configuration to fail to load. Check rule labels, fields, and resource files together; valid JSON syntax alone is not enough.

Domain strategy and where resolution happens

IPIfNonMatch means that if no domain rule matches, the target domain can be resolved so address rules can be checked next. It does not specify a DNS server or force every application to use the core's DNS. If an application has already submitted an IP address, routing may see something different from what you expect. When domain rules do not work, check whether the entry point received a domain or an IP and whether client features that affect destination detection are enabled.

V2Ray DNS settings require you to consider whether the resolver is reachable, which outbound handles the DNS query, and how the result is used for matching. Changing the resolver address will not automatically fix every connection problem, and existing cache entries may not refresh immediately. Record the original settings and compare DNS and connection logs for a single test destination. Encrypted DNS may also need its server name resolved first, so avoid making that prerequisite depend on a proxy path that is not yet available.

For custom domains, full: commonly means an exact match, while domain: covers a domain and its subdomains. Keyword and regular-expression matching have a wider reach and need extra checks for unintended matches. Add one specific rule, verify it, and only then expand its scope. See Custom Routing Syntax and Rule Priority. The goal is not to accumulate rules, but to explain why a destination matches a rule and to restore the original behavior by removing it.

7. TUN Mode: Traffic Capture, Permissions, and Conflicts

Enable it only after standard proxying works

TUN receives traffic that the system routes to a virtual network interface, making it useful for applications that a standard system proxy cannot cover. It changes how traffic enters the client; it cannot fix an unavailable server, and it does not mean every connection must use a proxy outbound. Confirm that standard proxying works first and keep that configuration available. Otherwise, server, interface, and DNS problems can occur at the same time, making it hard to identify what TUN changed.

A client's TUN switch may depend on specific components, permissions, and system capabilities. Implementations on different platforms are not directly comparable. v2rayN's desktop traffic-capture process differs from Android's system authorization for network connections. Follow the current client's prompts, then check the logs to confirm that an interface and routes were actually created. An enabled switch is only an interface state; if interface creation or route setup fails, requests may not follow the expected path.

Compare behavior before and after enabling TUN

Before testing, turn off other tools that may compete to capture traffic and note whether the system proxy is still enabled. Some combinations can coexist, but start with as few entry points as possible. Choose an app that does not follow the system proxy, enable TUN, make a new connection, and check the core logs. If the app already uses an explicit proxy, a successful result does not prove that TUN captured it. Choose test conditions that make the change in entry method observable.

Test access to the local network separately, including your router's admin page, LAN devices, and internal services that should connect directly. After TUN changes routing, these destinations may be sent to a remote outbound by mistake. Use the client's exclusion and routing options rather than repeatedly switching servers. A direct rule for private addresses often helps, but does not replace checking system routes and the device's actual address ranges; some networks use additional internal subnets.

DNS, loopback, and existing virtual interfaces

TUN and DNS are closely related because applications may keep sending queries to the original system resolver while the virtual interface changes the query path. Check whether DNS capture is needed and how queries are handled for your implementation and client. Do not paste DNS fields from a different core into the current configuration, and avoid enabling multiple resolver setups that override each other. After adding any DNS option, recheck both name resolution and the destination connection.

Another risk is that the proxy's own connections get captured again, creating a routing loop. Mature traffic-capture implementations usually handle their own traffic, but manual changes to routes, interfaces, or outbound binding can break that assumption. If the client suddenly cannot reach servers after TUN is enabled, turn TUN off and check whether standard proxying works again. If standard mode works but TUN does not, investigate local traffic capture first rather than immediately reimporting the subscription.

On mobile devices, also consider background restrictions, sleep, and network changes. If the connection works in the foreground but drops when the screen locks, system power-saving or background policies may be involved. If it fails when switching from Wi-Fi to mobile data, compare logs and authorization before and after the switch. Check the specific background options offered by the system rather than assuming the app must stay in the foreground or reinstalling it instead of observing its lifecycle behavior.

By the end of this chapter, you should be able to test standard proxying, TUN, and network restoration on exit separately. Record required permissions, retained exclusion rules, and whether the system proxy is also in use. Standard proxying is a complete setup for devices that do not need traffic capture; there is no need to add complexity just to enable more switches. TUN is useful for a specific traffic-entry problem, not as the only test of a correct client setup.

8. Maintenance: Updates, Logs, and Configuration Backups

Update one component at a time

The client app, runtime core, subscription data, and routing resources are separate things to maintain. App updates can change the interface and how configuration is generated; core updates can change protocol and field handling; subscription updates change server entries; resource updates affect category matching. If you update everything at once, it becomes difficult to identify what caused a problem. Update one component at a time, run a basic test before proceeding, and keep a record of the last working setup.

Before updating, save settings using the client's supported export or backup feature and check what it includes. Some exports contain only server details, not DNS, routing, or system behavior; others may include subscription credentials and user IDs and should be treated as sensitive. The goal is to be able to restore the configuration, not just to have a file. At minimum, record how to restore it, the client edition, where settings are stored, and which options must be recreated manually.

Use logs to identify the failing layer

When something fails, note when it happened, which app and destination you tested, and what you changed most recently. Then check the core's startup output and runtime errors. If it exits on startup, check the configuration and local files first; if there is no request in the logs, check the entry point; if a request appears but times out, check remote reachability and the outbound; if name resolution fails, trace the DNS path. Logs are evidence for diagnosis—not every line containing “error” has the same root cause.

Access logs show requests and their paths; error logs record exceptions and runtime problems, though some clients combine the two. Temporarily increasing log detail can help reproduce an issue. After testing, restore a level suitable for everyday use to avoid collecting excessive logs. Before sharing logs, remove subscription query parameters, user IDs, and private destinations, while retaining timestamps, error types, and relevant field names for diagnosis.

Reproduce and roll back one change at a time

Reproduce the issue with one server and one app, changing only one setting at a time. Make a new connection after each change; do not rely on an existing long-lived connection. Record what changed before and after, then add other apps and rules back after the test succeeds. If a change does not help, undo it before trying the next one. Otherwise, repeated experiments leave an unexplained combination—and even if the connection eventually works, you will not know which settings were necessary.

A latency or connection test in a subscription reflects only that particular test method, not the full experience of accessing a destination. If a test fails, find out whether it checks reachability, a handshake, or a specific request. Real applications may still be affected by DNS, routing, UDP, or server policy. Record which app worked over which path rather than just noting a test number, and do not use it to draw conclusions about overall network performance.

If problems appear after an upgrade, check whether the old configuration migrated, which copy of the app is running, and whether the system proxy points to the new listening endpoint. To roll back, use the saved settings and an appropriate installer; do not run old and new copies at the same time. If the cause is still unclear, return to the minimal working setup, then reintroduce routing and TUN one step at a time. This restores service while preserving a stable comparison point.

If log fields are unfamiliar, see V2Ray Log Message Reference. By the end of this chapter, you should have a restorable backup, a reproducible test path, and a sanitized failure report. Maintenance is not about constantly changing settings; it is about making every change explainable, testable, and reversible, so a temporary recovery is not mistaken for a confirmed diagnosis.

9. Advanced Setup: Protocol Boundaries and Configuration Validation

Establish who owns each part of the configuration

Before advanced setup, determine which settings the client generates and which ones you can maintain over time. Graphical clients usually generate the core's runtime configuration from their UI settings; editing a generated file directly may be undone when you switch servers or restart. Prefer custom routing, templates, or configuration options explicitly supported by the client. If you need a fully custom configuration, understand how it interacts with subscriptions, server selection, and interface switches. Avoid having two sources control the same field.

Keep a standard working configuration and create a separate one for experiments. Test the feature you want to study one change at a time, recording the expected result, how you will observe it, and how to restore the previous state. For example, when testing domain rules, keep the server, DNS, and entry method fixed and change only the matching condition. When testing TUN, keep the working routing and outbound settings fixed. The goal is not to collect more options, but to establish cause and effect so evidence can narrow down future problems.

Learn protocol settings layer by layer

Study protocols by separating authentication, transport, and security. VMess and VLESS differ in authentication and encryption responsibilities; changing the protocol name alone does not convert one to the other. Trojan has its own connection requirements. Match the WebSocket path and host, gRPC service name, TLS service name, and REALITY parameters to the server settings. Do not guess fields that the source has not provided. A successful import does not mean every combination will work at runtime.

Protocol compatibility also depends on the core used by the client and how it generates configuration. An online snippet may use fields from a different core. Even valid JSON can produce an unknown-field error or different behavior in your setup. Before testing a new feature, confirm which core it belongs to and whether the current client exposes the relevant settings. For a basic comparison, read VMess vs. VLESS: What's the Difference?, then check your actual configuration layer by layer.

Turn rule testing into maintainable configuration

Build complex rules around clear needs, such as sending a specific service through a fixed outbound, keeping LAN traffic direct, or blocking a particular category. Document each rule's purpose and expected matches, and remove exceptions that are no longer needed. Overlapping rules make ordering harder to reason about, and resource updates can change match results. If behavior is hard to explain, reduce the rules to a small, testable set rather than adding broader rules.

Advanced DNS tests also need a clearly defined point of observation. The name requested by an app, the query performed by the core, and the destination address used by routing may represent different stages. Record resolution failures, unexpected results, and unreachable connection addresses separately. After changing DNS strategy, old cache entries and long-lived connections may preserve previous behavior, so test with a new connection. A single page refresh is not enough to prove the entire resolution path has changed.

Finally, establish a fixed regression checklist: a normal browser request, an app that does not follow the system proxy, LAN access, subscription updates, and network restoration after exit. Testing only the new feature is not enough; a new rule can break an existing path, and a DNS change can affect subscription retrieval. Keep the checks simple but consistent, with clearly defined test targets and success criteria so you can compare results before and after a change.

You have mastered this guide when you can explain where a connection enters, which rules select its outbound, where names are resolved, and how to recover when something fails. For follow-up help, browse the FAQ by symptom or return to the quick-start tutorial to rebuild a minimal setup. Keep a working baseline and merge experiment results into everyday settings one at a time; a complex configuration with an unclear history is harder to maintain.