V2Ray Configuration Guide
From Core Concepts to TUN

Step 1 · Understand the Basics

Core Concepts and Traffic Flow

Know the Difference Between the Interface, Core, and Server

Before configuring anything, think of the client as two parts: the graphical interface stores servers, subscriptions, and rules; the proxy core reads the configuration, listens on local ports, handles connections, and selects outbound routes. An open window only confirms that the interface is running—it does not mean the core has started. To verify connectivity, check the runtime log, local listener, and actual access results rather than relying on the tray icon or toggle color.

V2Ray is part of the Project V proxy ecosystem. V2Fly continues development of a related core, while Xray follows a separate development path. v2rayN is a desktop GUI client that can use different cores depending on the version; v2rayNG primarily uses the Xray core, while v2flyNG uses the V2Fly core. Client names and protocol names are not interchangeable, and a configuration that works with one core may not work with another.

Follow a Request to Find Where Each Setting Applies

A typical request flows from an app to a local entry point, where the system proxy or a virtual network interface passes it to the core. The core applies routing rules to send it direct, through a proxy, or block it; the selected outbound then handles the connection. The remote server provides the server-side proxy service. Installing a client does not provide a remote service. Users must obtain subscription links, server details, and access rights through legitimate means; this site’s download page provides client downloads.

In GUI clients, a “node” usually means a set of server connection parameters, including the address, port, protocol, authentication, and transport security settings. VMess, VLESS, Trojan, and Shadowsocks are protocol names; WebSocket and gRPC are transport methods; TLS and REALITY relate to transport security. Parameters must match the server configuration as a set. Two nodes using VLESS are not necessarily interchangeable if their security settings differ.

Build a Minimal, Verifiable Connection

For your first test, focus on one clear goal: send a request from one app through one selected server. Close other proxy tools, check that the device clock is correct, select a server, and enable the system proxy. For now, leave DNS, routing templates, and TUN unchanged. Once this basic path works, you’ll have a reliable baseline for testing additional settings. Otherwise, when several things change at once, it’s hard to tell which layer caused the problem.

Distinguish among three outcomes. If the core won’t start, check the local configuration, permissions, and ports first. If it starts but the proxy connection fails, check server parameters, subscription status, and network reachability. If only some apps fail, check whether they use the system proxy and which routing rules they match. A latency test in the interface only tells you whether a particular test path succeeded. It does not verify real-world access or directly indicate download speed.

Step 2 · Choose Your Tools

Choose a Client and Installer

Start with v2rayN on Desktop

For Windows, macOS, and Linux, start with v2rayN. Its consistent approach to managing subscriptions, servers, and routing makes everyday use straightforward. Choose an installer by checking your operating system first, then your processor architecture, and finally the package format. A shorter filename or smaller download does not mean a package is a better fit. An architecture or runtime mismatch will usually cause problems during installation, startup, or core launch.

The Windows downloads include Desktop and the classic WPF version. Desktop uses a cross-platform interface, which suits users who want a similar workflow across desktop operating systems. WPF retains the classic Windows desktop interface and may be a better fit if you’re used to its existing workflow. Menus and dependencies can differ, so screenshots for one version may not match another.

If you don’t need to keep an existing setup, start with Desktop and install any runtime dependencies listed for that package. If WPF is working well for you, there’s no need to switch just for a different interface. Before changing versions, export the information you need and note your current settings. Keep each version in a separate directory to avoid having both write to the same configuration, and don’t run both cores on the same listening ports.

Choose an Android Client and Package by Core and Architecture

For Android, start with v2rayNG, which uses the Xray core. Consider v2flyNG if you need to test V2Fly behavior or already have a compatible configuration. The two clients can serve as separate test environments, but don’t run them at the same time. Android generally allows only one app at a time to use the VPN tunnel in the current user session. Starting another client may replace the existing connection, even if the previous app’s toggle still appears enabled.

Most newer Android phones use ARM64. If your device supports it, choose the arm64 package. If you’re unsure of the architecture, try the universal package, then check the installation result and device details. Successful installation doesn’t guarantee support for every protocol setting in your subscription: the client, core, and server must all be compatible. If a setting isn’t supported, check the feature requirements first instead of repeatedly switching universal packages.

Separate OS Compatibility from Configuration Compatibility

On macOS, Apple Silicon uses ARM64 and Intel processors use x64. On Linux, deb packages are for compatible Debian-based package management systems, while rpm packages are for compatible RPM-based systems. An ARM64 Linux package also requires an ARM64 system; matching the distribution name alone doesn’t make an x64 package suitable. System libraries, desktop environments, and permissions can also affect startup. Choosing the right package format is only the first step.

After choosing a client, note the operating system, architecture, interface version, and core type. You’ll need these details when troubleshooting. Get downloads from the Download Center, and avoid mixing instructions from different sources. If you’re unsure what your subscription requires, ask its provider about the protocol and transport settings. This section helps you choose based on compatibility and workflow—not server quality inferred from a client’s name.

Step 3 · Prepare the Runtime Environment

Installation, Permissions, and Local Listening

Get the App and Core Running Reliably

On Windows, move the installer or extracted program to a permanent directory before launching the client. If it comes as an archive, extract all files before running it; don’t launch the main program from the archive preview. Configuration, logs, and core files may rely on relative paths, so temporary extraction locations can lead to lost settings or missing files. Use a simple directory path and avoid locations that require special write permissions.

If the first launch reports a missing runtime, install the dependencies required by the package you selected. Don’t assume instructions for a different interface version apply. After installing dependencies, restart the client and check the logs for core startup failures, configuration parsing errors, or listener failures. A standard system-proxy connection usually doesn’t require running the entire client as an administrator. Grant elevated permissions only when needed for tasks such as setting up a virtual network interface or installing a service.

On macOS, move the app to a permanent Applications folder and follow the system’s security prompts the first time you open it. Don’t disable system security entirely just to launch an app. If a Linux app won’t open, try launching it from a terminal or checking the desktop startup logs. First determine whether the problem is a missing graphical dependency or a proxy core error; they require different fixes, and reimporting a subscription won’t install missing system libraries.

Check the Listening Address and Port

Find the local mixed listening port in the settings and note its current value. This guide uses 10808 as an example; use the port shown in your client. A mixed entry point can typically handle HTTP and SOCKS requests, but the exact capabilities depend on the client and core configuration. Start by allowing local access only and listening on the loopback address. Unless you specifically need to share the proxy on your local network, don’t enable LAN access or listen on all network interfaces.

If the logs report that a port is already in use, check which process is listening instead of repeatedly trying different permission levels. The commands below only show connection and listener information; they don’t terminate processes. On Windows, check for a listener and its PID; on Linux, look for the local listening entry; on macOS, use the built-in port query tool. If there’s no output, confirm that you have the necessary permissions and that the queried port matches your settings.

# Windows PowerShell
netstat -ano | findstr :10808

# Linux
ss -lntp 'sport = :10808'

# macOS
lsof -nP -iTCP:10808 -sTCP:LISTEN

If the conflicting process belongs to an old client, exit that program normally. If it’s another service you need, choose a free port in the current client. Save the change, restart the core, and confirm that it’s listening on the new port. Update the port in any apps where you entered proxy settings manually. For detailed steps, see how to troubleshoot a busy local listening port. Don’t terminate system services based on a process ID alone.

Grant VPN Permission on Android

After installing an Android client, the first connection attempt requests VPN permission. This gives the app access to Android’s local traffic-routing interface; it doesn’t mean the app has connected to a remote server. Check the client logs and test access after granting permission. If installation fails, check for an architecture mismatch, Android version restrictions, a signature conflict, or an incomplete download. Don’t uninstall the old app right away, as this may remove its existing configuration and subscriptions.

Step 4 · Manage Connection Details

Import Subscriptions, Update Them, and Test Servers

Add the Subscription URL to a Subscription Group

A subscription URL lets the client retrieve server configurations and usually contains access credentials. Copy the full URL without removing query parameters, and don’t post it in public forums. Before importing it, confirm that you trust the source and have permission to use it. Check that the copied text doesn’t include spaces, line breaks, quotation marks, or extra instructions added by a chat app. The client needs a URL that returns configuration data—not an information page or an interactive sign-in screen.

In v2rayN, open subscription group management, create a group, enter a recognizable name, then paste and save the subscription URL. Return to the main window and update that group. Check whether the server list has been populated. Menu names may vary slightly between versions, but the order stays the same: save the source, fetch its contents, then choose a server. Don’t paste a subscription URL into the “Address” field for a manually added server.

In v2rayNG and v2flyNG, add a source in the subscription group settings, then return to the main screen and update it. Importing from a QR code or clipboard may add only a static server entry rather than a subscription that can be refreshed. After importing, check the group details to see whether future maintenance requires updating the subscription or replacing entries manually. A group name is for organization only; it doesn’t change the server protocol or core behavior.

Check the Response When an Update Fails

A subscription update usually has two steps: making a network request and parsing the returned content. If the request times out, check whether the URL is still accessible and whether the update uses a direct or proxied connection. If parsing fails, check whether the returned format is supported. A login page, error page, or usage-limit notice from the provider can’t be imported as server configuration, even if the request itself succeeded. After the client reports an update is complete, check how the entry count changed and look for errors instead of relying on the completion message alone.

Before you have a working proxy, try updating directly first. If your current network really can’t reach the subscription source and you already have a working server, try updating through that proxy. Don’t require a subscription source to use a server that hasn’t been imported yet; that creates a startup dependency. Keep existing working entries before updating. If you delete them all and the source is unavailable, you’ll lose both your working connection and a useful troubleshooting reference.

Select a Server Before Testing the Connection

After importing, select a server that’s compatible with your current core and make it active. A real connection latency test can help rule out configurations that clearly fail; then verify an actual request in a browser or from the command line. Results vary with the test target, DNS, network route, and time, so they’re not a fixed performance rating. Don’t simply choose the lowest number in the list, and don’t assume one failed test means the entire subscription is permanently unusable.

If most entries in a group fail, check the device clock, subscription validity, and protocol support first. If only one entry fails, compare its address, port, security settings, and transport parameters. Don’t change key fields in an automatically generated subscription entry at random; the next update may overwrite your changes. If you need to test a modified configuration, copy it into a separate manual entry and label it clearly so it isn’t confused with the subscription source.

After updating, check that the active server is still available. Renaming a source or removing entries may invalidate the current selection, and group filters can make a populated list appear empty. For more troubleshooting steps, see the checklist for subscription parsing failures and empty server lists. You’re done when the subscription source is maintainable, the active server is clear, and at least one connection has passed a real request test.

Step 5 · Route App Traffic

System Proxy, Manual Proxy, and Global Routing

Test a Browser with the System Proxy First

After selecting an active server, enable “Set system proxy” or the equivalent option in v2rayN. This updates the operating system’s proxy settings for apps to read, but each app can choose whether to follow them. Most standard browsers use these settings, but some command-line tools, download managers, and games have their own networking behavior. If the browser works but another app doesn’t, check how that app connects before switching servers.

“Clear system proxy” usually removes the proxy settings written by the client; it doesn’t necessarily stop the core. “Do not change system proxy” may leave the operating system’s existing settings in place. Refer to the current client interface for the exact behavior. Before exiting normally, restore system proxy settings you no longer need—especially before force-quitting the process. If the system still points to a local port after the listener has stopped, apps that use the proxy won’t be able to connect.

Separate Traffic Coverage from Outbound Routing

“Global proxy” can mean different things. In a client’s routing settings, it usually means sending traffic that has entered the core through a proxy outbound. It does not guarantee that traffic from every app enters the core. A system proxy controls how some apps connect; routing rules control how connections already in the core are handled; TUN changes which traffic is captured. These are different layers, so one “global” toggle can’t describe all of them.

If an app supports HTTP or SOCKS proxies, you can enter a loopback address and local listening port manually. This gives you precise control over that app’s connection without immediately enabling broader traffic capture. Check which protocol the app requires before entering the address; a mixed listening entry doesn’t mean every port in the interface is interchangeable. Don’t enter the remote server address as the app’s local HTTP proxy.

Compare Results with an Explicit Proxy Test

The commands below send requests to the same example site, one over HTTP and one over SOCKS. Use the port your client is currently listening on. On Windows, curl.exe avoids conflicts with some shell environments that use a different command with the same name. socks5h lets the proxy handle the destination hostname, although the actual resolution path still depends on the core configuration. A successful command confirms that this request path works; it doesn’t mean every app is using the proxy.

curl.exe --proxy http://127.0.0.1:10808 --connect-timeout 10 -I https://example.com
curl.exe --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 -I https://example.com

On macOS and Linux, use curl as the command name. Record the explicit proxy test result and compare it with the browser. If the command works but the browser doesn’t, check browser extensions, custom proxy settings, or stale connections. If both fail, check the local listener and proxy outbound. Don’t rely on a cached page to confirm connectivity; open a new window and request a page you haven’t visited before if needed.

Android’s VPN mode uses a system interface to route traffic, and per-app proxy settings can further affect which apps are covered. For your first test, don’t exclude the browser. After connecting, narrow the app list if needed. By the end of this section, you should be able to distinguish between an app that isn’t entering the proxy and a connection that fails after entering it. For quick instructions, see the user guide; for common symptoms, check the Troubleshooting guide.

Step 6 · Control Outbound Routing

Routing Rules, DNS, and Split-Tunnel Tests

Start with a Built-In Mode, Not a Blank Rule Set

Once the system proxy works, choose a routing mode provided by the client. Start with a built-in template, and learn what “direct,” “proxy,” and “block” mean before adding exceptions. Direct means the connection is established directly from the device; it doesn’t mean the traffic bypasses the core entirely. Block means a matching connection is deliberately rejected, not that it failed. Global mode can be useful as a diagnostic comparison, but it doesn’t need to replace all fine-grained rules permanently.

Rules are usually checked in order, and the first match determines the route. If a broad rule matches a domain earlier, a more specific rule below it may never take effect. Before adding a rule, specify what it matches, the intended outbound, and where it belongs, then check the logs. Don’t add overlapping exceptions for domains, IP ranges, and processes all at once; even if access starts working, it will be difficult to identify which rule made the difference.

Know What a Configuration Snippet Applies To

The snippet below is an example of V2Ray / Xray-style routing, not a complete configuration that can run on its own. It assumes the full configuration defines a direct outbound named direct and a proxy outbound named proxy. The example only shows how to route an example domain and private addresses directly. If your outbound tags have different names, update them too. Don’t overwrite a GUI client’s generated configuration directly, as it may be regenerated when you save settings.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
        "outboundTag": "direct"
      }
    ]
  }
}

In a domain rule, domain:example.com matches that domain and its subdomains; it can’t express arbitrary URL paths. Proxy routing generally can’t see the specific path inside an encrypted webpage, so don’t enter a full URL as a domain rule. Private address rules help keep local network services accessible, but they don’t cover every special-use address. Prefer a complete template maintained by the client, then add exceptions only when you have a specific need.

DNS Affects Which Rules Can Match

DNS translates domain names into addresses and affects the information available to address-based rules. The AsIs example doesn’t resolve a domain solely to match an IP rule; it doesn’t mean the connection never uses DNS. If an app gives the core only the resolved address, a domain rule may not match directly. Conversely, some address-based checks need additional handling when a domain is available but its resolved address is not.

Domain sniffing can add destination information for supported traffic, but it can’t recover domains from every protocol or decrypt app content. Browser secure DNS, app-specific resolution, and the system cache can all make the actual path differ from what you expect. When troubleshooting, first determine whether the failure occurs during resolution or connection, then decide whether to change the DNS strategy. Switching to a public DNS resolver at random won’t fix incorrect authentication parameters or a core that isn’t running.

To test split routing, choose one destination that should go direct and one that should use the proxy. Make a fresh request to each and check the destination and outbound tag in the logs. The address shown on the final webpage isn’t enough, as the page may use multiple domains. Reconnect after changing rules; existing connections may continue using their previous routes. Change one setting at a time and keep a summary of the configuration before and after so you can roll back if needed.

Step 7 · Expand Traffic Coverage

TUN Mode, Permissions, and Rollback

First, Decide Whether You Actually Need TUN

Consider TUN only if an app ignores the system proxy and has no usable manual proxy setting. TUN routes a broader range of traffic into the proxy chain through a virtual network interface, including traffic from many apps that can’t use standard proxy settings. It changes the entry point and coverage; it won’t fix a broken server, incorrect authentication, or an incompatible protocol. If the regular system proxy hasn’t been verified yet, fix the basic connection before adding another layer.

TUN support in v2rayN depends on the version, runtime components, and operating system. The toggle and service requirements may vary. Before enabling it, note the core, local port, routing mode, and DNS settings you’re using, and make sure you know how to restore the previous setup with TUN off. Don’t assemble an unknown core or replace program files just because an older guide doesn’t show a button. First check which features your current installer provides and what the interface says.

Test with a Single Traffic Entry Point First

Before enabling TUN for the first time, close other proxy software and any unnecessary virtual networking tools. Clear system proxy settings you don’t need, then enable TUN and grant any permissions or service access requested by the client. This makes it easier to identify which entry point handles the connection. Some setups allow both entry methods to coexist, but avoid combining them during your first test. Multiple entry points, virtual adapters, and automatic routes changing at once make troubleshooting much harder.

After enabling TUN, check the logs for virtual interface creation failures, insufficient permissions, route creation errors, or DNS binding conflicts. If the interface wasn’t created, switching servers repeatedly won’t help. If the interface is up but nothing can connect, turn TUN off and check whether the original system proxy still works. If access comes back, the basic outbound is probably working; focus on the traffic capture path instead of reimporting all your subscriptions.

Check DNS, UDP, and local services together

With TUN, DNS requests may use system resolution, core resolution, or virtual address mapping, among other paths. Check the actual configuration rather than assuming. Don’t copy DNS fields directly from another core. If webpages work but calls, games, or other services don’t, check whether UDP is supported all the way from the entry point to the proxy outbound. Creating a virtual interface alone doesn’t guarantee that the remote server can forward UDP traffic.

Local routes must remain available for network printers, storage devices, and office intranets. After enabling TUN, test local devices and proxy destinations separately to make sure neither disrupts the other. Corporate networks may provide their own DNS and routes, and overriding them can break internal services; check your organization’s network policies first. IPv6 also needs an explicit strategy. A successful IPv4 test doesn’t prove that all address families are being routed correctly.

Android VPN mode also routes system traffic, but you shouldn’t copy desktop virtual adapter drivers or administrator steps to Android. Common Android issues include VPN permissions, per-app exclusions, background restrictions, and conflicts with other VPN apps. By the end of this section, you should be able to explain why TUN is needed, verify the browser, target app, and local network services, and restore your original network setup when TUN is off—not leave the toggle in an unknown state.

Step 8 · Keep the Connection Working

Subscription Maintenance, Logs, and Layered Troubleshooting

Make Routine Checks Repeatable

You don’t need to change your configuration frequently for everyday use. When a connection fails, note the time, current network, client and core, active server, connection method, and routing mode, then repeat the same request once. These details can help distinguish a temporary network change from a persistent configuration problem. If results differ between a mobile hotspot and a fixed network, that’s a useful clue—but don’t change the server and DNS at the same time or you won’t know which change mattered.

Update subscriptions when the provider recommends it or when the contents need to be refreshed; there’s no need to make requests at very short intervals. After an update, check that the active server still works and that your local exception rules remain. Before upgrading the client, back up essential settings and read any migration prompts. Backups may contain credentials, so keep them somewhere secure. Don’t sync a full configuration to a public location or put subscription URLs in troubleshooting notes.

Troubleshoot in Four Layers: Local Setup, Subscription, Server, System

First, check the local setup: is the core running, is the listening port available, is the device clock correct, and can the disk be written to? Second, check the subscription: did the update succeed, is the active entry valid, and does the core support its protocol? Third, check the server: can you connect to its address and port, and do the authentication and transport settings match? Fourth, check the system: are the app entry point, system proxy, firewall, virtual interface, and DNS settings consistent?

Use clear log messages to narrow the search, but don’t skip the evidence. If the logs report a listener failure, fix the port first. If authentication fails, check credentials and the device clock. If only one app can’t connect, check its entry point first. For node timeouts, see how to troubleshoot connection timeouts using a four-layer approach. A timeout describes the outcome; it doesn’t prove that the remote server caused the failure.

Keep Logs Only as Detailed as Needed

Temporarily increasing log detail can help you identify the destination and outbound route, but keeping verbose debug logs for too long uses disk space and may record where you connect. Find the time range for a single failed request, save only the relevant lines, then restore the usual log level. Before sharing, remove subscription, authentication, and private destination details while keeping enough context to understand the error. A screenshot of only the final “failed” line usually can’t distinguish an entry-point issue from a remote connection failure.

Network changes, system sleep, and background app cleanup can all invalidate existing connections. On desktop, first check whether the system proxy still points to the current listening port, then restart the core to establish new connections. On Android, check background restrictions and VPN status. Don’t clear app data as soon as something goes wrong; you’ll lose valuable configuration for comparison. If a restart helps temporarily, keep tracking what triggers the problem instead of treating the restart as the root-cause fix.

Step 9 · Explore and Review

Advanced Configuration and a Long-Term Learning Path

Expand with Rules You Can Explain

After completing the first eight sections, the goal isn’t to collect more parameters. It’s to make every setting easy to explain, verify, and roll back. Start with one specific need, such as routing a domain directly, setting up a manual proxy for one app, or maintaining a stable connection after switching networks. Write down the expected traffic path, then compare it with the current configuration. The narrower the goal, the easier it is to test and the less likely it is to disrupt other services that already work.

When learning a configuration’s structure, start by understanding how inbounds, outbounds, routing, DNS, and logs refer to one another. Tags are internal names, and they must match wherever they’re referenced. Fields with the same name can also have different meanings in different cores. For advanced options provided by a GUI client, save changes through the interface whenever possible. Consider custom configurations only after you understand how they’re generated and overwritten, or a later save may erase your changes.

Compare Core Changes Under the Same Conditions

v2rayN’s support for multiple cores is useful for checking compatibility, but switching cores shouldn’t be a random fix. First confirm that the new core supports the protocol, transport, and security fields you need. Keep the network, server, and test destination unchanged while switching only the core. Record whether it starts and whether the actual request succeeds. If a feature isn’t supported, use a compatible core or configuration instead of removing important security fields just to make the configuration parse.

Migrate to another device in steps too. Install a client that matches the operating system and architecture, set up the subscription again, confirm the active server, then migrate routing exceptions and connection settings. Don’t assume the entire program directory can be copied across platforms. File paths, permissions, interface names, and system proxy behavior may all differ. After migrating, test a direct destination, a proxy destination, and a local service to make sure old rules aren’t based on assumptions that no longer apply.

Keep Configuration Experiments Small and Reversible

For advanced testing, keep a brief change log with the goal, setting changed, test result, and rollback action—but never include real credentials. Use the checklist below before and after each adjustment. It’s more practical than a complex network diagram: when results differ from expectations, you can quickly decide whether to roll back and which single layer to change next, rather than stacking more parameters onto the setup.

1. Pick one problem to solve and record the current working baseline.
2. Check which fields the target core supports and save the settings you need before changing anything.
3. Make one change, reconnect, and check the actual route in the logs.
4. Test proxy destinations, direct destinations, and local network services; note what was affected.
5. If the test fails, roll back and test again. If it works, restore the usual log level and return to everyday use.

Remote DNS, domain sniffing, IPv6, and UDP can be useful topics for further study, but tackle them separately. When investigating DNS, keep the connection method and server fixed. For UDP, first confirm that the server supports it. For IPv6, check the address family, resolution, and routing together. Enabling all of these at once creates a system that’s harder to understand. The more settings you add, the more important clear logs and specific test targets become.

Performance comparisons also need consistent conditions. Latency, connection setup time, throughput, and stability answer different questions; one latency test can’t represent the whole experience. Slow downloads may be caused by the destination site, network congestion, connection reuse, or device load. Compare results only after repeating tests under the same conditions. For details on the first connection test, see real connection latency tests and proxy verification. Don’t mistake sorting the server list for a complete diagnosis.