From V2Ray Basics to Advanced Use: Complete v2rayN Setup

Core concepts and traffic flow

Start by separating the client, core, and server

The three objects most often confused when using V2Ray are the graphical client, proxy core, and remote server. v2rayN, v2rayNG, and v2flyNG are graphical clients. They store subscriptions, display server lists, generate runtime configurations, switch proxy modes, and translate user actions into parameters the core can understand. Xray and V2Fly belong to the core family. They listen on local ports, establish outbound connections, apply routing matches, and handle different transport methods. The remote servers configured by the subscription provider sit at the other end of the connection and receive protocol connections from the client. A graphical interface showing “started” only means that the local core process is running; it does not guarantee that the remote server is reachable. A successful subscription update only means that the address returned parseable content; it does not mean every node in the list can connect.

Once these three layers are clear, troubleshoot by boundary: if the program will not open, check the client installation and system dependencies; if the core fails to start, inspect local logs and port usage; if a server test fails, check node parameters, network reachability, and system time; if the browser still uses the normal network, check whether the system proxy or TUN is actually capturing the application. Calling every issue “a broken node” hides useful clues and often leads to unnecessary reinstalls.

How a request leaves an application

Using v2rayN's system proxy mode as an example, the browser first reads the operating system's proxy settings, then sends the request to the HTTP or SOCKS inbound port that v2rayN listens on locally. The core receives the request and checks the rules in routing from top to bottom against the domain, IP, port, protocol, or inbound tag. Once a rule matches, the request is sent to the specified outbound: the currently selected proxy server, the direct direct-connection outbound, or the block outbound. If no rule matches, the configuration's default outbound is used. DNS lookups may occur in the application, system, or core, so cases where a domain matches a direct rule but the request still uses the proxy are often related to DNS results and the stage at which matching occurs.

Protocol, transport, and security are separate parameters

Names such as VMess, VLESS, and Trojan usually describe the proxy protocol used by a node; TCP, WebSocket, and gRPC describe the transport; TLS and REALITY provide connection authentication or security. After importing a node, each field must correspond to the server-side configuration. Do not keep only the address and port and freely combine the rest. For example, a node using VLESS, TCP, and REALITY may rely on flow, serverName, publicKey, shortId, and other fields together to complete the connection. Changing any one of them can terminate the handshake before the actual request begins. For beginners, the safest approach is to import the complete share link or subscription and avoid manually changing transport parameters before understanding what each field means.

Latency, connectivity, and real-world speed

Latency tests in a client usually indicate whether a target is reachable and roughly how long the handshake takes; they do not measure sustained transfer speed. Different test methods may use a TCP handshake, a real protocol request, or a specified URL, so different results for the same node across clients are not unusual. A low-latency node may be unstable over long connections, while a slightly slower node may offer more usable bandwidth. When choosing a node, also check whether repeated connections succeed, whether the first byte of web pages arrives consistently, and whether long sessions disconnect frequently instead of ranking nodes by a single number. This layered understanding is the foundation for subscription management, routing, and TUN setup.

Choose and install a client

Choose a client for your platform

For desktop environments, v2rayN is the first choice. It supports Windows, macOS, and Linux, and can manage subscriptions, switch the system proxy, configure routing, and enable TUN, making it suitable for standardizing workflows across multiple desktop devices. For Android, v2rayNG is the first choice. It uses the Xray core and its interface is organized around mobile connection tasks; choose v2flyNG when the V2Fly core is required. These three clients serve different purposes, so there is no need to run them on the same device. Multiple clients listening on the same local port or trying to control the system proxy at the same time can create confusing port conflicts and state overrides.

Architecture, installation format, and directory permissions

Before installing, confirm your operating system architecture. Common Windows desktop devices use x64; on macOS, check the chip type in “About This Mac”; most recent Android devices use arm64, but choose the universal build if you are unsure; on Linux, run uname -m to check the architecture: x86_64 corresponds to x64 and aarch64 to arm64. With a mismatched architecture, the installer may refuse to run, the system may report an invalid format, or the program may exit immediately after launch.

On Windows, choose either the v2rayN desktop edition or the classic WPF edition as your daily entry point. If you use an archive, fully extract it to a fixed directory with write permission before launching the main program. Do not run it from an archive tool's temporary preview window, or configuration files, logs, and core files may not be saved reliably. On macOS, launch the application from the Applications directory after installation. On Linux, deb or rpm installation places files according to the system rules; when dependencies are reported, let the distribution's package manager handle them instead of copying library files manually.

What to check on the first launch

After the first launch, do not enable TUN immediately. Check that the main window displays normally, the settings page detects the core, the log window shows no continuing errors, and no other proxy client is using the local listening port. Then import a configuration, select a server, and run the connection test provided by the client. Enter the routing and TUN sections only after the ordinary system proxy path works reliably. This separates installation issues from advanced traffic-capture issues.

How to handle permissions and security prompts

Installing a TUN driver, changing the system proxy, and writing firewall rules may trigger permission prompts. Verify the program name and the source of the request before granting access. A standard system proxy normally does not require permanent administrator privileges; TUN requires more because it creates a virtual network interface. On managed devices, confirm that local proxy and network-adapter changes are allowed by the organization's network policy. If only one account cannot save settings after launch, check write permissions for the program directory and the account's configuration directory instead of changing protocol parameters.

After installation, use the client downloads page to verify the client type and installation format for your platform. The goal of installation is not to configure every feature at once, but to create a basic environment that starts reliably, saves settings, and provides readable logs. Every later feature should preserve a path back to this working baseline.

Import subscriptions and manage nodes

Subscription URLs and single-node share links

A subscription URL usually points to an updateable server list. After requesting it, the client parses multiple nodes and places them in the relevant subscription group. vmess and vless share links describe the complete parameters for a single node and are useful for temporary imports or separate storage. The two cannot always be distinguished by appearance alone: a subscription URL may be an ordinary HTTPS link or include access parameters, while a single-node link usually starts with the protocol name. Do not paste a share link into a subscription URL field, and do not treat a subscription URL as single-node content to scan.

In v2rayN, open subscription group management, create a group, enter the subscription URL, and choose “Update current subscription” or the corresponding update command. Name groups by purpose or source rather than using labels such as “Subscription 1” or “Subscription 2” that will be hard to recognize later. The entry names in v2rayNG and v2flyNG may differ slightly, but the workflow is the same: save the subscription URL, update it, return to the configuration list, and select the target node. The client manages nodes according to the subscription content, so manual edits to subscription nodes may be overwritten during the next update.

A layered check for failed subscription updates

When the list is empty after an update, first check whether the log says “request failed” or “parse failed.” A request failure means the client could not retrieve the subscription content. Check that the URL is complete, the system time is accurate, the current network can reach the URL, and the update is not configured to use a currently unavailable proxy outbound. A parse failure means the server returned content, but not in the format the client expected. Common causes include an expired URL, a login page being returned, missing access parameters, or a client version that cannot recognize newly added fields. Without changing the original group, create a test group and paste the complete URL again to rule out stale fields.

If old nodes remain but updates keep failing, do not delete the entire configuration immediately. Keep the currently working nodes, copy the first clear error from the log, and then inspect the subscription link. Check the URL, network request, returned content, parsing process, and node connection in that order; do not jump from an update failure straight to reinstalling the client. For a fuller path, see common causes of subscription parsing failures and a self-checklist.

How to use node tests

Batch tests are useful for removing entries that clearly cannot connect, but a single test should not become a permanent ranking. Update the subscription first, choose one consistent test method, and then check whether failures cluster around one protocol, one group of domains, or one server region. If every node in a subscription fails at once, first check the local network, system time, core status, and subscription parameters; if only a few nodes fail, investigate the nodes themselves. Running several test rounds rapidly can cause connection congestion and fill the log with parallel errors, making diagnosis harder.

Groups, notes, and update strategy

As the number of subscriptions grows, use groups to maintain clear boundaries. Put different sources in different groups; keep manually added nodes in a separate group; give temporary test nodes clear notes. The automatic update interval should not be so short that it regularly interrupts normal use. Set it according to how often the source changes, and keep a manual update option. If an update task must use a proxy, ensure that its current node is available; otherwise, you can create a loop in which an update is needed to restore nodes but the update itself depends on an expired node.

A subscription URL may contain access credentials, so do not paste it into public screenshots, shared logs, or public documents. During troubleshooting, you can retain the domain and error type but redact query parameters and identifying information in the path. Node share links also contain complete connection parameters and should only be transferred between controlled devices. Good node management is not about keeping as many entries as possible; it is about making the source, update time, commonly used nodes, and failure reasons easy to identify.

System proxy and proxy modes

What the system proxy solves

The system proxy is the best traffic-capture method to learn first on desktop. When v2rayN enables it, the operating system's proxy address is pointed to a local listening port. Browsers and desktop applications that follow the system proxy then send requests to the core. Its advantages are clear boundaries, simple toggling, and low troubleshooting cost. The limitation is that some programs do not read system proxy settings, so certain games, command-line tools, or applications with their own network stack may connect directly. When one application is not captured, first confirm whether it supports the system proxy before deciding whether TUN is needed; do not immediately change the node protocol.

System proxy status and core status are separate. The core can be running while the system proxy is off, or the system proxy can still point to an old port after the core has exited. When closing the client normally, let it restore the system proxy. If an abnormal exit leaves the browser offline, open the operating system's proxy settings and check whether they still point to a local address. Reopening v2rayN and turning off the system proxy often restores connectivity.

Global, rule-based, and direct modes

“Global” usually means that all captured traffic is sent to the proxy outbound; “rule” means traffic is matched by routing first and then sent to a proxy, direct, or block outbound; “direct” means captured traffic is sent out through the local network. The key qualifier is “captured traffic”: if an application never enters the system proxy, switching between global and rule mode will not affect it. Conversely, global mode does not send every packet on the device into the client; it only changes outbound selection inside the core.

Use comparison tests to confirm the capture path

When verifying proxy modes, do not rely only on the tray icon color. First select a confirmed working node, enable the system proxy, and use a browser that follows system proxy settings to open a test page. Then switch to direct mode and open the same page, and finally disable the system proxy. If the three states show no difference, check whether the browser uses its own proxy settings, whether the system proxy points to the current port, and whether the client log contains the corresponding request. If the log shows a request but the connection fails, the issue is in routing or the node; if the log contains no request at all, the issue lies between the application and the local inbound.

Command-line tools need separate consideration. Some read the HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY environment variables instead of desktop system proxy settings. For a temporary test, set the proxy address according to the tool's documentation, but do not copy a port number from another device; use the current client's local listening setting. After changing the listening port, update all manually set environment variables and in-app proxy settings as well.

LAN access and local listening

Allowing LAN connections expands the listening address from local-only access to a LAN interface. Enable it only when other devices on the same network genuinely need to use this computer as a proxy entry point, and confirm the firewall scope, listening address, and access controls at the same time. For ordinary single-device use, keep listening local-only. If other devices still cannot connect, check the listening address, system firewall, router device isolation, and port entry in that order. Do not leave all interfaces exposed just to eliminate a variable, because that changes the previously clear local boundary.

Routing rules

Rules are matched in order

The core of routing is not the number of rules but their order. The core usually checks rules from top to bottom; once traffic matches one, it uses that rule's outbound and later rules are not evaluated. More specific exceptions should therefore come before broader rules. For example, if one domain must use the proxy while its domain set defaults to direct, put the single-domain proxy rule before the set's direct rule. If the broad rule comes first, the exception will never take effect.

Common matching conditions include domains, IPs, ports, network types, protocols, and inbound tags. The domain condition works well for full domains, suffixes, or rule sets; the ip condition handles resolved destination addresses; port limits a service port; inboundTag distinguishes traffic from different local entry points. outboundTag selects the outbound after a match. Rule tags must exactly match tags defined in outbounds; spelling differences can make configuration checks fail or produce unexpected routing.

A minimal routing example

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:example.com",
          "geosite:category-ads-all"
        ],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

The example first sends private addresses to direct, preventing requests to routers, printers, or LAN services from taking a remote route; the second sends the example domain and specified set to block; the final rule acts as a fallback and sends the remaining TCP and UDP traffic to proxy. Actual clients may generate equivalent configurations through their interfaces, and outbound tag names may differ, so inspect the tags in the current configuration before copying rules. The final rule is deliberately broad; if placed first, the LAN direct rule would never get a chance to match.

How domainStrategy affects routing decisions

domainStrategy determines when the routing stage resolves a domain to an IP. With AsIs, routing keeps the original domain and does not proactively resolve it for IP rules; IPIfNonMatch resolves the domain only when no domain rule matches, allowing IP rules to be checked next; IPOnDemand resolves more proactively when a rule requires an IP. More aggressive is not always better, because extra resolution introduces differences in DNS paths, caches, and results. For everyday routing, start with IPIfNonMatch and adjust only when the logs show a need.

Start with a minimal rule set

When building routing, begin with three basic behaviors: direct access for the LAN, proxying for clearly identified targets, and a default action for everything else. Once stable, add ad blocking, application-specific ports, or complex domain sets. Add one group of rules at a time and record its position in the list. If something breaks, switch to global mode for comparison. If global works but rule mode fails, the node is probably usable and the issue should be narrowed to routing conditions, DNS, or outbound tags.

For complex configurations, read a section-by-section explanation of V2Ray configuration files to understand the relationship between inbounds, outbounds, and routing. When troubleshooting routing, record the original domain, resolved address, matched rule, and target outbound rather than only whether the page opened. Once these four items line up, routing behavior can usually be explained and reproduced.

TUN mode setup

How TUN differs from the system proxy

TUN mode receives system traffic through a virtual network interface and can cover more applications that do not read system proxy settings. The system sends packets matching the routing conditions to the virtual interface, and the client converts them before passing them to the core. Because TUN works at a lower network layer than application proxying, DNS, UDP, LAN access, default routes, and firewalls all affect the result. TUN is not a “stronger global switch”; it is a broader traffic-capture boundary with more configuration variables.

Before enabling it, confirm three things: the ordinary system proxy connects reliably through the current node; routing behaves correctly in system proxy mode; and the client has the permissions needed to create a virtual interface. Without a verified baseline, a TUN startup failure could come from the node, rules, driver, or system network. Keep a working configuration with TUN disabled so you can roll back quickly.

Enablement and essential checks

After enabling TUN in v2rayN settings, the system may request elevated permissions and create a virtual network adapter. Once authorized, inspect the log and confirm that adapter creation, address assignment, route installation, and core startup complete without errors. Then open an ordinary web page, test an application that uses UDP, and finally check LAN devices. Do not enable custom DNS, strict routing, complex rule sets, and multiple network filters all at once; otherwise every failure will have several possible causes.

If TUN reports that it is running but all network access stops, disable TUN first and confirm that the basic network recovers. Then check whether the default route was written correctly, whether DNS has a usable outbound, whether the virtual adapter received an address, and whether other security software is blocking the new interface. If only the browser works while a particular application fails, check whether it uses TCP or UDP and whether the routing rules block that protocol. If domains fail while direct access to a test address responds, the issue is usually DNS.

DNS and loopback issues

In a TUN setup, prevent the client's own connections from being captured by TUN and sent back into the client, creating a routing loop. Mature clients bypass the tunnel for the core process, server address, or specific outbounds, but custom rules can break this relationship. Typical signs include repeated connections to the same server address, increased CPU usage, and rapid connection failures. Restore the default TUN rules, ensure the proxy server address goes directly through the real network interface, and confirm that the core's outbound does not re-enter the virtual interface.

Keep DNS processing on one clear, explainable primary path. If system DNS, the client's built-in DNS, the browser's own resolver, and other network tools are active at the same time, a domain may receive different results at different points. During troubleshooting, temporarily disable extra application-level DNS features, use the client's recommended defaults, and inspect the logs to see which inbound receives the query and which outbound returns it. Once stable, restore custom policies one at a time.

Recovery after sleep, network changes, and exit

After a laptop resumes from sleep, switches between wired and wireless networks, or moves from one network to another, the virtual interface and default route may still reference the old state. If connections break, stop TUN first, wait for the physical network to obtain a valid address, and enable TUN again. If the client exits abnormally and the network does not recover, check the system proxy, virtual adapter, and default route instead of deleting the whole configuration. On Windows, turn off any leftover system proxy and restart the client; on Linux, use ip route to inspect the default route; on macOS, confirm the current service order in Network settings.

A complete TUN setup is not defined by a “ready” icon. It should produce predictable results for ordinary web pages, UDP applications, LAN resources, sleep recovery, and client exit. After testing, record the DNS method, private-network rules, and permission settings so future upgrades or network changes can be compared quickly.

Troubleshooting and routine maintenance

Read the first actionable error

When the core fails to start, many later errors in the log may be cascading results of the first problem. Start at the current launch time and read downward until you find the first clear error containing a field name, port, file path, or configuration section. Common types include a local port already in use, invalid JSON formatting, a missing outbound tag, missing transport parameters, an unexecutable core file, or a configuration directory without write permission. Record the original error before changing anything, address one cause at a time, and restart; avoid changing the node, port, core, and routing rules simultaneously.

When a port is already in use, first check whether another client is still running in the background. On Windows, use the following command to find the process ID using the local port, then confirm the program in Task Manager; on Linux, use ss to inspect the listening process. Replace the port number with the local listening port shown in the client's settings.

netstat -ano | findstr LISTENING
ss -lntup

Do not change the port to a random number just because it is occupied. If the browser, environment variables, or another application has the old port entered manually, update those settings too. For a more detailed log-reading method, see a troubleshooting path for locating core startup errors in the log window.

Build a troubleshooting checklist around the connection path

When the program starts but cannot reach a target, check in order: whether the subscription updates, whether the target node passes its connection test, whether the core is running, whether the application request reaches the local inbound, whether routing selects the correct outbound, and whether DNS returns a usable result. Each step needs observable evidence, such as subscription logs, core startup logs, request records, or mode comparison results. If global mode works but rule mode fails, focus on routing; if the system proxy works but TUN fails, focus on the virtual interface, DNS, and system routes; if no mode can connect, return to node parameters, system time, and the basic network.

Routine updates and rollback

The client, core, subscription, and rule set are four different update targets and should not all be replaced during one maintenance session. A safer order is to record the current working state, update one item, restart and verify common scenarios, then continue. After a client upgrade, check configuration migration and menu changes; after a core update, inspect protocol parameters and startup logs; after a subscription update, watch for node additions, removals, and name changes; after a rule-set update, compare common websites and LAN access. With a verification point at every step, an issue can be narrowed to the most recent change.

Rollback requires an identifiable baseline. At minimum, record the client type, subscription group, commonly used nodes, system proxy mode, TUN status, and custom routing rules. Store exported configurations in a controlled location; subscription URLs and node information should not enter a public sync directory. If an upgrade causes problems, roll back the most recent change first instead of deleting the entire configuration. Rebuilding may restore service temporarily, but it also removes the logs and differences that could explain the cause.

Preparing logs before sharing

Logs are useful for preserving the error time, error type, field name, target port, and client steps, but they may also contain subscription paths, server addresses, user identifiers, or local directories. Before sharing a log, remove subscription query parameters, node identifiers, and personal directory names while retaining the error context. A final line alone usually lacks startup information; publishing the entire configuration exposes unnecessary data. Prefer sharing what happened beforehand, the expected result, the actual result, the first error, and several lines around it.

Reliable maintenance depends on reproducible steps, not repeatedly clearing the configuration. Keep a baseline, change one variable at a time, and read from the first error; most issues can then be traced to a specific layer. For the role of each area in the main window, see a detailed tour of the v2rayN main interface.

Configuration files and the Advanced path

Map graphical settings to the configuration structure

The goal of Advanced study is not to abandon the graphical client and hand-write every setting, but to understand which structural section each interface action changes. V2Ray configurations commonly contain sections such as log, dns, inbounds, outbounds, and routing. inbounds define how traffic enters the core, such as a local SOCKS, HTTP, or TUN entry; outbounds define proxy, direct, and block exits; routing decides which outbound receives inbound traffic; dns affects how domains are resolved and which path carries DNS requests; log controls the logging level and output location.

When switching servers in v2rayN, the parameters of the primary proxy outbound usually change; switching between global and rule modes changes route selection; changing a local port affects the inbound listener; enabling TUN adds or adjusts the related inbound and system network settings. With this mapping in mind, terms such as inboundTag, outboundTag, and domain strategies in the log are no longer isolated fields. When reading a configuration, first draw the relationship between “entry, rules, and exit,” then inspect protocol details.

Make the smallest possible configuration change

Before manually adjusting a configuration, copy the current working version and label the copy with its purpose. Change only one logical target at a time, such as adding a direct domain, changing the DNS outbound, or adding a test inbound. After saving, run the configuration check provided by the client or core, start it, inspect the opening log lines, and verify a request directly related to the change. Do not reorder all routes, replace DNS, change the listening port, and switch nodes in one edit; even if the connection works afterward, you will not know which change made the difference.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "block",
      "protocol": "blackhole"
    }
  ]
}

This example shows a local SOCKS inbound and two basic outbounds: direct and block. The listening address is 127.0.0.1, meaning that only the local machine can access it; enabling UDP allows the inbound to receive corresponding requests. It is not a complete remote proxy configuration because the proxy outbound must use real protocol parameters supplied by a subscription or server. Use this concise fragment to understand the structure, but for everyday connections let the client generate a complete configuration that matches the subscription.

Log levels and what to observe

For everyday operation, a restrained level such as warning is sufficient; when investigating complex routing or connection flows, temporarily increase the detail and restore it after confirming the issue. Detailed logs grow quickly and may record more destination information, so they are not suitable for permanent use. For each test request, note its time and inspect the nearby inbound, target domain, routing decision, and outbound error. A long log without a clearly defined test action is difficult to distinguish between background and target requests.

Recommended Advanced learning order

First master the system proxy, node selection, and log entry points; next understand domains, IPs, ports, and rule order; then learn where DNS requests occur and how domainStrategy affects them; only afterward study the TUN virtual interface, default routes, and UDP; finally move on to protocol fields and transport parameters. This order progresses from observable local behavior to protocol details while preserving a verified foundation for troubleshooting.

Study protocols through field relationships. Protocols such as VLESS provide identity and flow-control fields; transports such as TCP, WebSocket, and gRPC carry the traffic; TLS or REALITY provides the relevant security and authentication parameters. Treat every share link as one complete parameter set rather than swapping fields because names look similar. To compare single-node links with subscriptions, read how to use vmess and vless share links.

Establish your own operating baseline

After completing this guide, create a device baseline recording the client name, platform, listening port, system proxy mode, TUN status, DNS path, routing-rule source, and commonly used subscription groups. The baseline does not need sensitive node parameters; it only needs to describe the configuration relationships. After each upgrade or change, verify the same scenarios: client startup, subscription update, ordinary web pages, rule-based routing, LAN access, UDP applications, and sleep recovery. A change is complete only when the results match the baseline.

Going from zero to advanced use does not mean memorizing every field. It means following a stable analysis order: identify the problem layer, collect log evidence, make the smallest change, and confirm it with a comparison test. To repeat the shortest configuration flow, return to the quick guide; to switch platform installers, visit the client downloads page. These are the operational entry points, while this guide explains the cause-and-effect relationships between configuration settings.