Complete V2Ray Guide
From Installation to Routing

Stage 1: Understand the Client, Core, and Connection Path

Break a proxy connection into separate steps: an app makes a request, the client provides a local entry point, the core reads the configuration and applies routing, and the selected server forwards the traffic. The GUI organizes these settings; it is not the connection itself. If the window opens, only the interface has started. If a subscription updates, only the configuration has been retrieved. A successful visit to the target site is what shows that the request's full path is working. Knowing where each step begins and ends makes it easier to find the right place to troubleshoot.

Project V, V2Fly, and Xray: What's the Difference?

V2Ray is part of the Project V proxy ecosystem. V2Fly continues community development of related cores, while Xray is a separate, actively developed core. The core handles protocol processing, transport, encrypted connections, routing, and DNS. v2rayN, v2rayNG, and v2flyNG are GUI clients that manage configuration and launch a core. Similar client names do not mean their cores, features, or configuration fields are identical. When checking whether a feature is supported, verify the client, the core it uses, and the server's requirements.

Protocols, Transports, and Connection Settings

VMess, VLESS, and Trojan are protocol names; WebSocket and gRPC describe transport methods; TLS covers the encrypted handshake and certificate verification. These are different layers that work together, not interchangeable options. Match the client settings to the combination required by the server. The connection can still fail if the address and port are right but the path is wrong, or if the protocol is right but the server name is not. Use a complete share link or subscription whenever possible instead of assembling settings from names alone.

A server entry is a set of connection details saved in the client, typically including the server address, port, user ID, transport, and security options. Its name is for your reference; a region or route label in the name does not prove the server's actual location or performance. A subscription is a way to retrieve server configurations in bulk. Importing one does not create a service or guarantee that every listed server is currently available. The client, subscription source, and remote service are three separate things.

Follow the Traffic Path to Understand Each Setting

Whether an app sends requests to the client depends on the system proxy, the app's own proxy settings, or traffic capture through TUN. Once a request reaches the core, routing rules decide whether it goes direct, through a proxy, or is blocked. That's why “Auto-configure” in the system proxy settings and “Global” in routing are not the same thing: the first controls how traffic gets in; the second controls where it goes afterward. If an app ignores the system proxy, changing routing rules alone usually won't change its network path.

Start with one device, one client, and one known-working server to establish a minimal connection. Avoid running multiple proxy tools at once. Keep your tests consistent: confirm the regular network works, test one destination that requires a proxy, then review the logs and egress address. Knowing what to expect at each step makes it easier to tell whether later DNS, routing, or virtual network adapter changes solve a problem or introduce another one.

Stage 2: Choose a Client for Your Platform and Needs

For desktop, start with v2rayN. When choosing a download, check the operating system first, then the processor architecture, and finally the interface variant and package format. “Supports this platform” does not mean every installer runs on it. Builds of the same product may have different dependencies, permission requirements, and interfaces. On the client downloads page, use the entry for your platform rather than guessing from a filename in an older tutorial screenshot.

Choosing Between the Desktop and Classic WPF Versions

On Windows, v2rayN is available as a desktop version and a classic WPF version. The desktop version uses a newer cross-platform interface; WPF keeps the classic interface. If you're setting things up for the first time, start with the desktop version. If you already have a familiar WPF workflow, you can keep using its menus and settings. The two interfaces may use different settings locations or local data layouts. Don't run an old and a new instance while both can modify the same data. Exit the client and save your existing configuration before switching.

On macOS, choose an Apple Silicon or Intel build based on the processor shown in About This Mac. On Linux, check your distribution's package system, then confirm whether the architecture is x64 or arm64. deb and rpm are package formats, not performance tiers; you can't determine architecture from how a device looks. Being able to launch through a compatibility layer doesn't mean you've chosen the best build for your system. If installation fails, rule out a package-format or architecture mismatch before investigating dependencies.

Choose an Android Client by Core and Architecture

For Android, start with v2rayNG, which uses the Xray core. Consider v2flyNG if you need a V2Fly-based setup. Choose between them based on core compatibility and your preferred workflow—not the number of servers or the interface color. Recent mainstream phones generally use arm64. If you can't confirm the architecture or the matching package won't install, check the universal-build guidance. A universal build supports a wider range of devices, but it can't bypass the operating system's minimum requirements.

Choose a core based on the features your server configuration requires. Don't assume that switching cores will preserve every protocol setting as-is. Some security options, transport fields, and newer features are available only in specific cores or builds. If an import reports unsupported fields, skips servers, or fails configuration checks, consult the subscription provider's compatibility notes instead of cycling through random options. Updating the client cannot add capabilities the server doesn't support.

For use across devices, keep the same subscription source and naming conventions where practical, but don't copy the entire application data directory. Desktop system proxy settings and Android's VPN-based traffic capture work differently, and routing and DNS options can vary by platform. A safer migration is to import the subscription again, select the active server, and configure the proxy entry point for the new device. Record why you chose that platform, architecture, and core so you won't have to guess again after an update.

Stage 3: Install and Check Before Launch

Before installing, confirm the device has a working regular network connection, the system date, time, and time zone are correct, and there's enough space for configuration and logs. Certificate verification depends on the system clock. A badly wrong time can cause a TLS handshake to fail even when the server settings are correct. Downloading and launching are local setup steps; don't enable TUN or change DNS yet. Handling installation, core startup, and traffic capture separately keeps the first troubleshooting steps clear.

Windows: Check the Program Folder and Runtime Dependencies

Follow the download page's instructions to run the installer, or fully extract the archive to a fixed directory you can write to. Don't launch the main program from an archive preview, and don't extract only the executable; missing files can prevent the interface or core from starting. If the first launch asks for a runtime component, install the dependency for the architecture required by that build. A missing dependency is not evidence that a server is unavailable—the issues occur at different stages.

After launch, check the main window and system tray, and make sure there isn't another instance running. If the logs say a local port is already in use, exit other proxy clients and start v2rayN again. If you genuinely need to run multiple instances, assign each a different listening port and decide which one manages the system proxy. This is not recommended when you're starting out. Review firewall prompts in context, including the program path and its purpose; don't disable system protection entirely just to troubleshoot.

macOS and Linux: Separate Installation Permissions from Traffic-Capture Permissions

After installing on macOS, move the app to a stable location before launching it. If macOS blocks it, check the download source, package type, and exact system message, then follow the system's supported steps. Don't copy bypass commands written for a different system version. Regular proxy use and TUN require different permissions; opening the interface does not mean the app can create a virtual network interface. Verify a regular proxy connection first, and grant additional permissions only if you need to capture traffic from more apps.

On Linux, install the package using the method for your distribution and review dependency errors from the package manager. Run desktop clients in a regular user session; don't run the entire desktop app with elevated privileges just because TUN may need them. If startup fails, check the program logs, directory write permissions, and desktop environment requirements. System proxy settings usually depend on the desktop environment. Command-line programs follow their own proxy rules, so one result does not tell you what the other will do.

Android: Grant Permission, Then Check Background Behavior

Install the Android app through the system's normal process, then open it and import your configuration. The first time you connect, Android asks for permission to establish a VPN connection. This grants the client access to the system traffic-capture interface; it does not mean the remote server is connected. If another app is using the same interface, stop it before starting this client. If the connection drops immediately, check system permission and app logs before deleting the subscription or changing every server setting.

Once a foreground connection works, check whether it drops when you lock the screen or switch apps. Some systems restrict background activity; adjust the client's battery and background permissions if needed, without removing restrictions from every app. At the end of installation, confirm that the interface works, settings can be saved, the core starts, and logs show no recurring local startup errors. Then import a subscription and choose a server. For the permission steps, follow the Quick Start Guide.

Stage 4: Import a Subscription and Manage Active Servers

A subscription URL is an entry point for retrieving configuration and often contains access details linked to your account. Use it only in the client's subscription settings—don't paste it into public discussions, screenshots, or online converters. First check whether you have a subscription URL or a single-server share link: the former belongs in a subscription group; the latter is usually imported from the clipboard. Pasting an account webpage URL into a subscription field, or treating raw configuration text as a subscription URL, will cause parsing to fail.

Create a Subscription Group in Four Steps

1. Open subscription group settings in v2rayN, add a group, and enter a recognizable name and the full subscription URL.
2. Save the group, then update the subscription. For the first attempt, use a network path that currently works.
3. Return to the server list. Confirm the servers appear in the group and check the update log for parsing errors.
4. Choose a server and set it as active before configuring the system proxy or starting a mobile connection.

An example URL might look like https://example.com/sub?token=xxxx. The domain and parameter here illustrate the format only; they are not a working server. When pasting a real URL, check for extra spaces, line breaks, and missing characters—especially parameters after the question mark. The group name is for local identification and does not change connection settings. “Enabled” usually controls whether a group is included in a given action; check the current interface for its exact behavior.

Understand Update Intervals and Request Methods

Automatic update intervals control how often the client retrieves configuration; they don't need to be short to improve connection speed. Frequent requests may trigger subscription service limits and add noise when troubleshooting. The User-Agent can affect the format returned by the server; usually, keep the client default and change it only when the subscription provider specifically asks you to. If an update returns a webpage, login page, or unsupported format, check the URL and response type first. Don't repeatedly overwrite a group that was working.

Choose direct or proxied access for subscription updates based on the network available at the time. If no server works, forcing the subscription download through an unavailable proxy can leave you stuck in a loop. Switch the retrieval path only when you have a working proxy but direct access to the subscription URL fails. First note whether the failure occurs during connection, authentication, or parsing. An update failure doesn't necessarily remove existing servers or mean you must stop using them immediately.

Subscription Updates, Speed Tests, and Real Connections Are Different

Updating a subscription retrieves settings; setting an active server selects the outbound connection. Both steps are required. A server speed test only describes the result of a particular test at a particular time. TCP latency mainly reflects establishing a TCP connection; it doesn't cover protocol authentication, TLS, transport, or reaching the target. A connection test is closer to a real request, but still depends on the target, timeout, and network conditions. Don't choose a server for long-term use based only on the lowest number in the list.

On Android, add the address under group or subscription management and update it, then return to the server list, choose a server, and start the connection. Menu labels may vary between clients, but the sequence is the same: retrieve, select, connect, verify. For your first connection, see How to Choose a v2rayNG Server and Verify Proxy Traffic. For share links and raw configuration, read Subscription Formats and Configuration Conversion to avoid mixing input types.

Stage 5: Configure a Proxy Entry Point and Verify Traffic

On desktop, start with a regular system proxy to establish a basic connection. After selecting an active server, open the client's system proxy menu and choose “Auto-configure system proxy” if needed. This sets the local proxy entry point in the system settings; only apps that honor those settings will send requests to the client. The client must remain running. If it closes while the system proxy still points to a local port, your browser may be unable to connect even though the regular network is still available.

Three System Proxy Actions to Know

“Auto-configure system proxy” sets the proxy entry point. “Clear system proxy” removes the corresponding system settings. “Do not change system proxy” tells the client to leave the current system configuration alone. The last option does not force a direct connection, and it doesn't mean another app hasn't set a proxy. When switching clients or troubleshooting a loss of access after exit, check the actual state in the system's network settings. Don't rely only on the tray menu label; check which address and port the operating system is still using.

Configure apps that ignore the system proxy individually

Some apps offer their own HTTP or SOCKS proxy settings. Use the listening type and port shown by the client. The local address is usually 127.0.0.1; check the current settings rather than copying numbers from another device. If the entry point requires a username and password, configure those too. When an app asks for a proxy URL, check the protocol prefix as well. Entering a port alone does not make HTTP and SOCKS interchangeable.

Keep the local listening address separate from the remote server address. Apps connect to the local entry point; the client core uses the remote server settings. If only this device needs access, keep the listener on loopback. Allowing LAN connections expands who can reach it, so consider authentication and firewall rules too. Other devices on your LAN must use the local network address of the device running the client, not their own loopback address. Most users don't need to widen the listening scope just for testing.

Verify the Connection with Three Types of Evidence

First, visit a destination that should be reachable without a proxy to confirm the regular network works. Then visit a test destination that requires a proxy and confirm the page loads. Finally, compare the egress information with the client logs to understand the traffic path. An egress address reflects only the app that made that request and the route it used at the time; it can't tell you what happened in other apps. With split tunneling, a direct destination showing your local network egress may be expected, not evidence that the proxy is broken. Decide in advance which route each test destination should use.

If the browser works but one app doesn't, check whether that app supports proxies, has its own settings, or reuses existing connections before changing servers. An established long-lived connection may keep using its old route after a proxy change; close it or restart the test app and try again. If every app fails, check the active server, core logs, and local listener. See Verify the Connection and Proxy for a full first-run test. After exiting the client, also check that the system proxy has been restored to complete the test.

Stage 6: Set Up Split Tunneling and DNS Rules

Adjust routing only after a regular proxy connection works. Routing rules decide whether traffic entering the core goes through a proxy, connects directly, or is blocked. They are usually evaluated in order, though behavior depends on the core and rule type. Start with a standard split-tunneling setup offered by the client, then add only a few specific rules. This is easier to maintain than importing a large rule set from the start. Before changing anything, note the routing profile, default outbound, and rule order so you can restore them if needed.

From Specific Rules to the Default Outbound

Handle clearly local or internal resources first, such as LAN addresses and internal domains, then specific service domains, and finally the default outbound. Put rules that need precise matching ahead of broader ones. Domain and IP rules rely on different information: a domain rule can match when the request still includes the target domain; if only the target IP is available, matching may require a DNS result or another identification method. Don't assume every request includes both a full domain and an address.

The example below shows the Xray routing field structure for sending private LAN addresses direct. It's not a complete client configuration and assumes an outbound tagged direct already exists. In the GUI, use the corresponding rule editor provided by the client. Don't paste this snippet into a subscription URL or replace the entire runtime configuration. The client may regenerate its configuration, so save persistent changes in a supported location.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      }
    ]
  }
}

Match DNS Resolution to the Destination Route

DNS converts domain names to addresses, but three separate questions matter: who initiates the lookup, which path the DNS request takes, and how the result is used for routing. An app that resolves a domain itself and gives the proxy an IP behaves differently from one that sends the domain to the proxy for resolution. Changing the operating system's DNS may not affect lookups inside the core; changing the core's DNS may not control an app's built-in resolver. Find out which layer is actually doing the lookup before changing anything.

Internal domains usually need a local or organizational DNS server that knows about them. Proxy destinations need a resolver that works with the route used to reach them. With encrypted DNS, also consider how the resolver itself connects and how its domain is resolved initially; otherwise, you can create a dependency loop. Changing a DNS address is not a universal fix for access problems. After a change, clear the relevant app cache or reconnect; old results can make it seem as if nothing changed.

Test Individual Rules, Not Just the Mode Name

For every new rule, test one destination that should match and another that should not, then check the target and outbound in the logs. If a site's main page loads but images or login fail, check whether related domains are taking different routes. Rules that depend on IP region databases or domain lists also require those resources to be available. Missing data, mismatched names, or different update times can all produce unexpected results.

Aim for routing that is easy to explain and undo. Record the purpose and test destination for each custom rule; if something breaks, temporarily disable the rule you just added. If only a few apps need a special route, choose a narrowly scoped solution rather than applying complex policies to the whole network.

Stage 7: Enable TUN and Virtual Network Traffic Capture When Needed

TUN brings traffic in through a virtual network interface, which is useful for apps that can't be configured to use a proxy and ignore the system proxy. It changes how traffic reaches the client; it doesn't improve the remote server or eliminate congestion. Before enabling it, confirm the same server works for your destination in regular proxy mode. Otherwise, if the network goes down, you won't know whether the server is still working or whether the issue is with the virtual interface, system routes, or DNS.

Check Permissions, Conflicts, and Default Settings First

Creating a virtual interface or changing system routes on desktop usually requires additional permissions. Follow the client's prompts; a lit-up toggle does not prove traffic capture is working. Check the logs for permission errors, interface creation failures, or failed route updates. If the device also runs a work network tool, another virtual adapter, or a different traffic-capture app, check their requirements first. If you're unsure, stop the TUN test to avoid disrupting a work connection.

For your first test, keep the stack, interface, and route settings recommended by the client. Don't change MTU, DNS hijacking, and sniffing options all at once. TUN implementations and settings vary by build, so don't copy fields from a different core. Whether to enable the system proxy alongside TUN also depends on the client's implementation. Decide which entry point is responsible for traffic; don't turn on multiple entry points to disguise one that isn't working.

Verify Traffic Capture in Stages

1. Keep the known-working server selected, enable TUN, and confirm the core stays running without repeated errors.
2. Test the browser and an app that normally ignores the system proxy, checking the actual requests from each.
3. Visit your router, printer, or an internal service to confirm LAN resources are still reachable as expected.
4. Check whether the network recovers after waking from sleep, switching networks, and turning TUN off.

If external sites work but LAN resources fail, check private-address exclusions, internal DNS, and route priority before changing servers. If domain access fails but a connection to a known IP behaves differently, investigate the DNS path; one reachable IP does not prove all lookups work. If only a particular app fails, also check its transport, connection method, and network restrictions. TUN cannot give a remote server forwarding capabilities it doesn't have.

Handle UDP, IPv6, and MTU with Care

For apps that use UDP, the entry point, core, selected server, and remote service must all support the required traffic. Check IPv6 against the system's addresses, default routes, DNS results, and the client's traffic-capture scope. A successful IPv4 test doesn't prove the other address path is working. Review actual connection targets and logs to confirm uncaptured traffic follows the expected route; don't permanently disable an entire networking feature at the first sign of trouble.

MTU sets the maximum packet size allowed on an interface. On some links, large packets or extra encapsulation can cause loading stalls, but similar symptoms can come from packet loss, DNS, or the server. Change MTU only when you have evidence, and save the original value. Change one setting at a time and repeat the same test; if there's no improvement, restore it. Applying a supposed universal value can leave you without a reliable baseline for future troubleshooting.

Android captures traffic through the system VPN interface; its options don't necessarily correspond one-to-one with a desktop TUN switch. Focus on system permission, route scope, DNS, and keeping the app running in the background. If you don't have a specific need, keep the simple setup you've already verified.

Stage 8: Establish an Update, Backup, and Maintenance Routine

Once you can connect, shift from constantly changing settings to maintaining a known-working baseline. Record the client variant, active server, routing profile, DNS setup, and whether TUN is enabled. You don't need to include credentials or every speed-test result. The point is to know what changed recently and what worked last time when the next problem occurs. Make routine updates against this baseline instead of replacing every component at once.

Manage Four Types of Updates Separately

Client updates affect the interface and configuration management; core updates affect protocol and connection behavior; subscription updates replace remote server settings; rule-resource updates can change routing results. These are separate actions. Even if a build offers a combined update option, read the prompt to confirm what's included. Unless you have a compatibility reason, don't update the client, switch cores, and refresh every rule at once, then use a single visit to decide whether all those changes worked.

Before updating, exit extra instances and save your settings. Afterward, test with the same server and routing profile before enabling new features. If you're prompted to migrate configuration, check whether the old data can still be restored. Don't let old and new programs write to the same configuration directory at the same time. To return to an older setup, use a backup compatible with that version. Data structures may change between builds, so copying a new configuration back to an older program may not restore its previous behavior.

Back Up Settings; Keep Sensitive Data Private

Use the client's export or backup feature to save groups, routing, and necessary preferences. Backup files may contain subscription URLs, user IDs, or service settings; store them somewhere private and don't upload them to a public attachment area. When moving to another device, restore subscriptions and rules first, then configure listening ports, the system proxy, and TUN permissions for that device. Don't assume local interface names or LAN addresses will work on every device.

Keep support materials separate from full backups. When asking for help, provide the symptoms, platform, operating mode, reproduction steps, and redacted logs. Hide access parameters in URLs, server authentication fields, and account details; also check screenshot notes, QR codes, and clipboard areas. You don't need to erase all configuration when clearing logs. A few useful lines from just before and after the failure are better than a long record of repeated retries.

Turn Common Issues into Repeatable Checks

If a subscription suddenly fails to update, check the URL and retrieval path first. If one server fails, compare it with a known-working server in the same group. If all servers slow down, check the local network and device load. If only one destination has trouble, check the destination and routing result. Troubleshoot speed by separating server, network route, and local settings; see How to Troubleshoot Slow v2rayN Speeds by Layer. Don't use repeated reinstalls as a substitute for finding the cause.

After extended use, remove stale groups, duplicate manual servers, and rules you no longer need—but first confirm the active configuration doesn't depend on them. Also check startup settings and automatic system proxy configuration: if the client fails to start, does the system still have a proxy entry? If the network isn't ready, will a failed automatic update retry? Test basic behavior after waking from sleep, switching between Wi-Fi and Ethernet, or connecting to a mobile hotspot.

The goal of maintenance isn't to have no log messages at all; it's to understand the connection behavior. Investigate recurring errors, but interpret normal shutdowns and temporary network changes in context. A simple, repeatable process is more useful than a collection of unverified optimization settings.

Stage 9: Troubleshoot by Layer and Plan Your Next Steps

Advanced troubleshooting starts by finding where a failure occurs, not by collecting more switches. Follow a consistent order: local network, client startup, configuration parsing, local entry point, remote connection, destination access, routing, and DNS. Move to the next layer only when you have evidence. A browser timeout alone can't tell you whether the problem is a certificate, DNS, or routing issue. Check the client logs from the same time to see whether the request arrived, where it connected, and where it stopped.

Narrow Down the Issue by Failure Stage

If a parsing error appears at startup, check the fields, format, and core compatibility first. If the local port won't bind, look for another instance or a port conflict. If the remote connection times out, check the address, port, network path, and server status. If a handshake or authentication fails, verify the protocol, user ID, transport, and security settings. When a destination returns a clear application-level error, consider restrictions on the destination service too; not every unsuccessful response is caused by the proxy client.

For TLS issues, check the device clock first, then the server name, certificate coverage, and certificate chain. The server address and TLS server name can serve different purposes, but both must match the server's requirements. Don't permanently disable certificate verification just to clear an error; that changes the connection's security checks without fixing a name or certificate mismatch. See Troubleshooting TLS Handshake and Certificate Errors. Test the same destination before and after a change for comparison.

Keep Test Inputs and Success Criteria Consistent

When testing performance, keep the device, network, server, and destination the same, and distinguish connection setup time from sustained transfer speed. A small file that loads slowly may point to DNS or the handshake; a slow sustained download may also involve bandwidth, congestion, or server load. Mux multiplexing isn't always faster—it changes how connections are organized, and results depend on the protocol and network. Record the original setting before testing and revert if the improvement isn't consistent. Don't keep a complex setting based on one result.

Move from GUI Settings to Reading Configuration

Next, learn how inbound, outbound, routing, and DNS settings are structured. First map GUI options to what they actually do, then read the fields supported by the core. A client's generated runtime configuration may not be the right place to make persistent edits; manual changes may be overwritten on restart. When using custom configurations, prepare a separate test setup rather than replacing your daily working one. Check every outbound tag, resource name, and dependency in the examples.

If you want to deploy on a router or secondary gateway, learn about system forwarding, policy routing, transparent proxying, and DNS loops. These are network-device topics, not desktop TUN settings to copy over unchanged. Start with Xray Router and Secondary Gateway Deployment Overview to understand the roles of the main router and secondary gateway. Set up a local recovery path before experimenting, so a change to the default gateway doesn't lock you out of the management interface.

The end goal is to do three things: establish a connection with a minimal setup, explain where each flow goes using evidence, and restore a known-working state when something goes wrong. When a new issue comes up, return to the relevant stage on this page instead of reinstalling everything. For a first-time setup, review the subscription import steps in the Quick Start Guide. When changing devices or clients, revisit the downloads page to confirm the platform and architecture. Clear boundaries are the foundation for reliable advanced configuration.