v2rayN Setup and Maintenance Guide

Core Concepts: Clients, Cores, and Configuration

Map the path of a request

To understand how a connection works, break it into stages: an app makes a request, the traffic reaches a local proxy entry point, the core reads the rules and selects an outbound, and the remote server connects to the destination. The client provides the graphical interface, stores subscriptions, and generates the runtime configuration; the core handles the actual connections. An open window only confirms that the interface has started. It does not confirm that the core is running correctly, much less that the remote server is reachable. When something goes wrong, check each stage in order instead of changing several settings at once.

Separate configuration into two categories. The first describes the remote connection: server address, port, credentials, transport, and security settings. The second describes local behavior: listen address, system proxy, routing, and DNS. Subscriptions usually provide most of the first category, while the client manages local settings. A subscription update can change the node list without changing your system proxy or routing. Likewise, a working local proxy entry cannot fix invalid remote credentials.

Know the core families and protocol fields

Project V provides the broader ecosystem context for related proxy technologies. V2Fly and Xray are separate core development projects. v2rayN is a desktop GUI client; the features available depend on the selected core and what the client supports. v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Keep client names, core names, and protocol names distinct. Whether a protocol field works depends on whether the client can represent it, the core can parse it, and the remote server uses a matching configuration.

VMess, VLESS, and Trojan are common protocol names. The transport determines how a connection is carried, while settings such as TLS and REALITY govern security negotiation. REALITY is not a standalone subscription format, and enabling a switch cannot give an arbitrary node REALITY support. After importing a configuration, keep the combination supplied by your provider. In particular, don't guess the server name, fingerprint, public key, or transport path from a label. Any mismatch can cause a handshake failure, which is different from an unreachable address.

Use observable symptoms to narrow down failures

Distinguish three stages: name resolution, connection establishment, and the app's response. If DNS lookup fails, the request may not have reached the remote server. For a connection timeout, check the local network, destination address, and network path. For a handshake error, inspect the protocol parameters and security settings. A client connection test covers only the part of the path exercised by that test; it does not replace testing with a real app. If one webpage loads, that only confirms that request worked at that moment—it says nothing definitive about other apps, protocols, or routes.

Establish a minimal working baseline: keep one configuration known to work, verify proxy-aware apps through the system proxy, then add split routing and a virtual network interface one step at a time. Change one variable per test and note what happens before and after. If you switch nodes, rewrite DNS rules, and enable a virtual interface all at once, even a successful connection won't tell you which change helped. Maintenance depends on repeatable results, not on stumbling into a working combination by toggling settings.

Choose a Client: Filter by Platform, Architecture, and Core

For desktop, start with v2rayN

Open the client downloads page, choose your operating system, then check the processor architecture and package type. v2rayN is the recommended desktop client for Windows, macOS, and Linux. Don't install a package just because its filename looks familiar, and don't assume that setup instructions for one platform apply to another. Interface frameworks, permission models, and package formats differ. Choosing the right download helps avoid startup failures, incompatible architectures, and installation mismatches.

On Windows, the downloads page offers a Desktop edition and a classic WPF edition. The Desktop edition uses a newer cross-platform interface; the WPF edition uses the Windows desktop UI framework. Choose based on your workflow and system, rather than assuming that a newer interface has exactly the same features. Menus, settings, and some interactions may differ. When following a guide, look for the setting by what it does, not by its exact screen position. See Desktop vs. WPF: What's the Difference? for details.

For mobile devices, check architecture and feature requirements

On Android, v2rayNG with the Xray core is the usual choice. Consider v2flyNG only if you specifically need the V2Fly core and have confirmed that your configuration is compatible. Both apps support subscriptions and connection management, but core-specific fields are not interchangeable. If an import fails, first check whether the subscription supports that client and core; then decide whether you need a different app. Switching clients is not a general fix for an expired subscription, incorrect password, or unreachable server.

The processor architecture determines whether a package will run. Most recent Android phones can use arm64, but check your device and OS support. If you're unsure, consider a universal build and account for its larger file size. On macOS, check the chip under About This Mac and choose the Apple Silicon or Intel download. On Linux, check both the architecture and the distribution's package format: use the appropriate deb or rpm package. Package format does not affect proxy features.

Factor in how you'll use it

Before choosing, list the apps that actually need a proxy. If you only need a browser, start with the system proxy. If you need to cover apps that ignore system proxy settings, consider TUN mode. Corporate or managed devices, and systems running other network tools, may restrict drivers, routing, or permission changes. Check device policies first; taking over more traffic is not the default goal. More features involve more system layers and require more context to troubleshoot.

Finally, decide what needs to move with your configuration. Node links and QR codes typically carry remote connection parameters, not local routing, DNS choices, shortcuts, or interface preferences. When moving between platforms, import the remote configuration first, then set up local behavior for the new device. Keep a note of the platform, architecture, client edition, core, and required permissions. Use it to make informed choices after reinstalling or replacing a device instead of relying on an old package that may no longer run.

Installation: Set Up an Environment You Can Start and Stop

Review existing network settings before installing

Before downloading, check your OS version and architecture, and make sure you have enough free storage. If another proxy is already configured, note the system proxy address and port, along with the virtual interface status. Then quit related apps so multiple tools don't try to control the network at once. Don't delete configuration directories that are still in use. The goal at this stage is simple: start the client and core, locate the logs, and confirm the system network recovers after you quit. Complex routing rules and startup tasks can wait.

On Windows, use the appropriate download option and follow the installer. If you choose a portable package that needs extraction, extract all files to a fixed directory before running it; don't launch the app from the archive preview. A stable directory makes updates, log lookup, and configuration management easier. Avoid temporary locations that are regularly cleaned up, and don't move files while the app is running. If the app reports a missing runtime, follow the instructions for that edition to install the dependency. Don't download missing components from unverified sources.

Handle desktop and mobile permissions separately

On macOS, open the package for your chip, move the app to a stable Applications location, and launch it. If macOS displays a security warning, verify the source and follow the approval steps for your version of macOS in System Settings. Don't disable system protection entirely just to run one app. If the client opens but a feature fails, distinguish app launch permissions from network and later virtual-interface permissions. These are separate layers; seeing a window doesn't mean every permission is in place.

On Linux, install the appropriate package using your distribution's software installer or package manager. Review any dependency prompts, then confirm that your desktop environment can launch the GUI. If normal mode works but TUN mode doesn't, check permissions and service requirements instead of reinstalling the same package. Logs may be available in the client, your user directory, or the system service manager, depending on how the app was installed. Note the actual location so you know where to look after updates or when troubleshooting.

On Android, allow installation from the current download source when prompted, then check whether you should revoke that source permission afterward. The first time you connect, Android asks to set up a VPN connection. Review the prompt and approve it if needed. This allows the app to route traffic through Android's network interface; it does not verify that the remote configuration works. On managed devices, installation sources or VPN permissions may be restricted by policy. Follow device management requirements rather than trying to bypass them through repeated installs.

Check that the app starts and exits cleanly

On first launch, locate the logs, settings, and exit command. A desktop app may keep running in the notification area after you close its window; use the explicit Exit command to stop it. Check whether the system proxy is restored and whether any connection processes remain. Closing a window is not the same as stopping the proxy service. On Android, distinguish dismissing the app screen from stopping the VPN service, and check connection status in both the app and Android's network indicators.

Next, check the local listening settings. Keep the default port and localhost-only access for your initial setup; don't expose the proxy to your LAN. If the port is already in use, check for an old instance or another app before deciding whether to stop the conflicting process or change the port. If you change it, update any apps where the port was entered manually. Changing the client alone while leaving the browser or other apps pointed at the old port is a common cause of a core that starts successfully but receives no requests.

Import a Subscription: Save the URL and Verify the Configuration

Treat subscription URLs as access credentials

Subscription URLs often contain account or access information, so handle them as sensitive data. Don't share the full URL in public screenshots, online conversion tools, or public support posts. Verify its source, supported clients, and expiration before copying it locally. The client reads the configuration returned by the URL; it does not provide a remote service. If the app is installed but you don't have a valid configuration, an empty node list is normal. Changing the system proxy won't make nodes appear.

In v2rayN, open Subscription Group Settings under the Subscription Group menu. Add a recognizable group name, paste the subscription URL, and save. The name is for local organization only; it does not affect the remote connection. Return to the main window and choose Update all subscriptions (without proxy), or the equivalent update command in your version. Saving and fetching are separate actions: saving stores the URL, while updating downloads and parses its contents. After the update, check that configurations appear in the group.

Choose an update path that your network can reach

If you don't have a working proxy yet, try updating without one first. If the subscription service explicitly requires an existing proxy connection, establish another verified connection and then try updating through the proxy. Switching update paths repeatedly won't revive a subscription that can't be reached. If an update fails, check your local network, the full URL, account status, and whether the server returned configuration data or instead a login page, error page, or access restriction.

In v2rayNG, open Subscription group settings from the menu, add a name and URL, save, return to the configuration list, and choose Update subscription. The interface may have separate options for updating all groups and the selected group, so check which group is active. v2flyNG may organize its menus differently, but the steps remain the same: add the URL, save the group, update, and check for configurations. If nothing appears, don't add the same group again. Check the update result and logs for parsing errors first.

Know the difference between URLs, subscription data, and share links

A subscription URL is an entry point for retrieving configurations. Its response may contain multiple encoded links or another structure supported by the client. A single share link describes one remote configuration. Keeping these separate helps prevent importing a subscription URL as a single node, or entering a single-node link where a regularly updated subscription URL belongs. Base64 is just an encoding; it is not a connection protocol and does not mean credentials inside are encrypted. A share QR code may also contain full connection credentials.

After a successful update, select a configuration, make it active, and check that its protocol, address, and security fields are complete. Avoid editing subscription-managed connection parameters just to tidy up the list; the next update may overwrite your changes. If you need to keep manual edits, copy the configuration into a separate local group and note why you changed it. If subscription entries disappear or are replaced, the server-side list may have changed; don't assume the client lost data.

Verify with a real request, not just a populated list. Select an active configuration, start the core, and enable the system proxy as described in the next section. Then use an app known to follow system proxy settings to visit a known reachable page. If it fails, note whether the problem occurred while fetching the subscription, parsing the configuration, or connecting. If multiple devices share a subscription, check the provider's connection limits and usage rules. Importing a subscription doesn't guarantee simultaneous connections are allowed.

Proxy Modes: Verify the Entry Point Before Expanding Coverage

Use the system proxy for your first test

A proxy mode determines how app traffic reaches the core. On desktop, the system proxy registers a local proxy address with the OS, but only apps that read those settings will use it. Some apps have their own network settings; others ignore the system proxy entirely. So if a browser works after you enable the system proxy but a standalone app doesn't, the node isn't necessarily at fault. Find out which proxy entry point the app uses, then decide whether to configure it explicitly or use TUN mode.

In v2rayN, first confirm the active configuration and that the core is running. Then choose Set system proxy automatically from the System Proxy menu. Test with an app that follows the system proxy settings. “Automatically configure” does not mean the client will pick a node, configure every app, or optimize routing; it registers the system proxy. If that fails, compare the address registered in the OS with the client's actual listening address, especially if you previously changed the port manually.

Understand the difference between clearing settings and leaving them alone

Clear system proxy removes the system proxy settings managed by that action. Do not change system proxy leaves the current system state untouched. These are not equivalent: the latter does not mean the proxy is off. Whatever was registered before may remain. If the network stops working after you exit, check whether the system proxy still points to a local port that is no longer listening. To restore a direct connection, explicitly clear or reset that setting; closing the client window may not be enough.

To configure a proxy for one app, check which entry types and listening ports the client actually offers, then choose the matching HTTP or SOCKS setting in the app. Don't copy a port number from another guide, and don't use the remote server address as the local proxy address. DNS handling varies too: some apps resolve names locally, while others can pass them to the proxy. This affects routing and resolution, so check the app's own settings.

On Android, understand VPN service and per-app coverage

v2rayNG uses Android's VPN interface as a local traffic entry point. The first connection requires system permission. Once connected, the client's routing and related settings determine where traffic goes. A VPN indicator only confirms that the interface is established; it doesn't prove that every destination is using a remote outbound. With per-app routing enabled, apps outside the selected scope may not use this path. Check the app scope, routing rules, and active configuration together.

Avoid running multiple traffic entry points at the same time where possible. When testing TUN, clear the system proxy first to rule out a request passing through the local entry point twice. If you use an in-app proxy, note its explicit settings so you can restore them later. Don't use “global” as a complete diagnosis: it may mean all apps are covered, or that routing sends everything to the proxy. Those are different layers. When describing a problem, specify both the entry method and routing mode.

By the end of this section, you should be able to answer three questions: Which app is making the request? Which local entry point does it use? Did the core receive it? If there is no corresponding activity in the logs, check the entry point and app settings first. If the logs show a connection, move on to remote connectivity and routing. Narrowing down the layer avoids blaming every connection issue on the subscription or node, and gives you a clear baseline before setting up a virtual interface.

Routing and DNS: Keep Match Conditions and Resolution Paths Aligned

Start with preset rules to establish a routing baseline

Routing decides where traffic leaves after it enters the core. It is separate from the system proxy: the system proxy determines whether traffic enters the core; routing decides whether traffic that enters goes direct, through a proxy, or to another configured outbound. In v2rayN, you can start with a preset under Routing Settings, such as Bypass mainland China, and learn what it targets before using it. Rules depend on domain and address data, so results can vary with update status, where resolution happens, and changes to the destination. A preset name is not an absolute guarantee of how every site will behave.

Most rule systems evaluate rules in order, so specific exceptions should come before broad rules. If an all-traffic rule is first, later domain rules may never be reached. For every rule you add, check its conditions, target outbound, and position—not just whether it is enabled. Outbound tags can vary between clients. Verify the actual tag before copying a configuration snippet; a reference to a nonexistent outbound can prevent loading or cause requests to behave unexpectedly.

Distinguish domain rules, IP rules, and DNS strategies

Domain rules depend on the core having domain information; IP rules match the destination address used for the connection. If an app resolves a domain locally and submits only the address, domain rules may no longer apply as expected. Traffic sniffing can provide additional information in some cases, but it can't recover the real domain for every request and is no substitute for a correct DNS setup. If traffic is routed incorrectly, check what the core actually received in the logs before deciding why a rule didn't match.

This snippet shows how Xray routing fields match. Use it to understand the rule structure; it is not a complete, runnable configuration. The example sends the specified domain and its subdomains through an existing direct outbound. Before integrating it, confirm that the full configuration defines an outbound named direct. The example domain is for syntax only, not a real service. In a GUI client, use the routing editor to express the same rule rather than overwriting the generated file.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "direct"
      }
    ]
  }
}

AsIs means routing matches against the information currently available; it does not mean that domain resolution stops throughout the system. A connection may still require resolution later in the process. Understand other resolution strategies using the documentation for your core; don't infer whether they trigger additional lookups from their names alone. DNS and routing affect each other. After changing either, check the final destination address and outbound, not just the text displayed in the rule editor.

Build a separate checklist for DNS

When planning DNS, identify who makes each query, where it goes, and which outbound carries it. Domains that should connect directly generally need a resolution method that returns addresses suited to the local network path. For domains accessed through a proxy, confirm that the DNS path matches your intended setup. Encrypted DNS changes how queries are protected in transit; it doesn't automatically correct the outbound selection. If a remote resolver itself requires a proxy connection, avoid making that same path responsible for resolving the proxy server's address, which can create a startup dependency.

Browser secure DNS, the OS cache, and an app's own cache can all affect test results. After changing rules, close existing connections and, if needed, clear the relevant cache before testing the same destination again. An old connection continuing along its original path doesn't prove the new rule is ineffective. If only one app has a problem, check whether it bypasses the client's DNS settings. For more on split DNS, see DNS Configuration Explained. When troubleshooting, record both the resolved address and the routing match.

Enable TUN: Check Permissions, Routing, and Conflicts

First decide whether you need a virtual interface

TUN receives traffic routed through a virtual network interface and can cover apps that ignore system proxy settings. It changes the entry point and system network path; it does not fix an invalid remote configuration or guarantee that all traffic will use a proxy outbound. Traffic still depends on routing, protocol support, and exclusion rules after it enters the interface. Enable TUN only after the system proxy works and you've confirmed that you need broader app coverage. This keeps troubleshooting variables to a minimum.

Before enabling it, save your current configuration and make sure you can find system network settings, client logs, and the off switch. Desktop platforms may require administrator approval, a helper service, or a network component, depending on the OS and package. Follow the client's instructions for necessary permissions; don't run your entire everyday environment with elevated privileges. If device policies prohibit virtual interfaces or route changes, use an allowed entry method instead. Repeatedly granting permissions won't override a policy restriction.

Follow a consistent sequence for the first setup

Select an active configuration already verified with a regular proxy, then quit other tools that change network routes. Temporarily clear the system proxy to keep one clear traffic path. In v2rayN, find Enable Tun or the equivalent switch in your version. Grant the requested permission and check the logs for successful interface creation and route loading. If you see a permissions error, interface creation failure, or address conflict, address that startup error first. Don't immediately edit the subscription or switch through a batch of remote configurations.

Once the interface is up, test a regular website, an app that ignores system proxy settings, LAN devices, and essential work services in turn. Testing just one external page can miss problems with local printers, file sharing, or LAN admin pages. If local resources fail, check whether private addresses and required subnets are correctly excluded, then confirm that the destination actually belongs to one of them. Don't exclude every private address mechanically; access to some organizational networks depends on their specific topology.

Handle loopback, DNS, and multiple network interfaces separately

TUN must prevent the proxy's own remote connections from being routed back into its entry point, which can create a loop. Clients usually handle necessary exclusions and outbound binding, but multiple interfaces, shared connections, and other network tools can still cause routing problems. Symptoms include all connections dropping after enablement, repeated similar connections in the logs, or unusually high core load. Turn TUN off to restore your baseline, then check interface selection and routes one at a time. Don't keep stacking additional proxy layers.

DNS is another common source of problems. TUN can change where system queries go, potentially conflicting with secure DNS, organizational resolvers, or another VPN. If IP addresses work but domain names don't, check the resolution path first. If only large downloads or some protocols fail, also investigate the network path, packet size, and protocol support. Don't lower the MTU or copy someone else's settings without testing. Note the default first, and make sure every change can be rolled back and tested against the same destination.

Pay close attention to network changes on devices with multiple interfaces. Switching between Wi-Fi and Ethernet, resuming from sleep, or sharing a connection can change the default route. If the problem starts only after a switch, stop traffic capture and restart it, then check whether routes were updated for the new interface. Android uses the system VPN interface for traffic capture; don't copy desktop driver or service instructions. Focus instead on system permission, per-app scope, and whether another VPN is already in use.

Maintenance: Updates, Backups, and Layer-by-Layer Troubleshooting

Keep updates easy to roll back

Separate maintenance into three kinds of updates: the client app, the core, and the subscription. An app update can change the interface and configuration management; a core update can change supported fields and connection behavior; a subscription update changes the remote list. Don't apply all three at once and then try to identify the cause of a problem. A safer sequence is to back up, update one layer, test against a fixed destination, and then move on. If the connection matters for work, allow time to recover instead of changing everything right before you need it.

Decide what to back up before you start. A subscription URL can retrieve the remote configuration again, but may not restore manual nodes, local rules, DNS settings, or interface preferences. Client exports may contain credentials; store them securely and don't casually upload them to public cloud storage or group chats. When restoring on another OS, check the backup format and import support, then review local paths, listening ports, and permission settings. Don't assume the same backup behaves identically on every platform.

Protect manual configurations when updating subscriptions

Before updating a subscription, confirm the URL still works and note the active configuration. Afterward, check the groups, active item, and connection parameters for changes. The server may remove entries, and the client may select a different active item, so test a real connection even if the update succeeds. Keep long-term manual configurations in a separate group and note their source to prevent them from being overwritten alongside subscription-managed entries. Repeatedly importing the same subscription won't fix a group management problem.

When using one subscription on multiple devices, manage the shared remote list separately from local settings. Desktop routing doesn't need to match your phone's, and LAN exclusions and app scope should be set up for each device. See how to sync configurations across devices for when to use subscriptions, QR codes, or backups. Whatever method you choose, recheck the entry point, DNS, and routing on the receiving device. An import success message isn't enough.

Organize troubleshooting evidence by layer

When a problem occurs, note whether all apps are affected and whether basic connectivity works with the proxy off. If the basic network is down too, check your local connection and upstream network first. If only apps using the system proxy fail, check the listening entry point. If the core received the request but couldn't connect remotely, check the active configuration and handshake logs. If only certain domains or apps fail, focus on routing, DNS, and app-specific settings. Narrowing things down by scope helps avoid reinstalling everything as a first step.

When checking logs, keep the surrounding context and timestamp, but remove addresses, account identifiers, subscription parameters, and credential fields first. A timeout can have several causes; one error word isn't enough to identify one. Tie the error to an action—for example, “while updating the subscription,” “while starting the core,” or “after opening this app.” For support requests, include the OS, client edition, proxy entry method, and most recent change. This is usually more helpful than sending your entire configuration.

Finally, verify that recovery worked. Stop TUN, clear any leftover system proxy settings, and exit the client; then confirm that the regular network works. Restart from the minimal baseline, adding one layer at a time. If the issue occurs only after waking from sleep or switching networks, record that trigger instead of treating it as a permanent configuration error. See Troubleshooting for similar symptoms. Keep a record of the cause, changes, and retest results—a clear note from one successful fix can save time the next time the same issue appears.

Advanced Setup: Expand Your Configuration with Testable Changes

Start with a baseline you can explain

Advanced setup isn't about turning on every option. It's about being able to explain how each request enters, where it is resolved, which rules match it, and which outbound it ultimately uses. Start with a working baseline: record the OS and client, the active configuration's source, the entry method, the routing preset, and the DNS setup. Separate required features from optional experiments. Without a baseline, even a complex setup that works briefly can be hard to restore after a network change or update, and you won't know what an added setting actually fixed.

Plan each experiment around a question you can verify: Does this app ignore the system proxy? Does this domain use the expected outbound? Does DNS still work after a network switch? Choose a fixed destination, record what happens before the change, and adjust only the relevant setting. After testing, close existing connections and make a fresh request so connection reuse doesn't skew the result. If you can't reproduce the result consistently, narrow the scope instead of adding rules to explain an uncertain symptom.

Expand routing and DNS in dependency order

A first advanced step is more precise routing. Learn the difference between an exact domain match, a domain suffix, and an IP range before adding exceptions and checking rule order. Wildcards, regular expressions, and core-specific rules can have different semantics; don't paste expressions from another setup without checking them. Document the purpose and test case for every custom rule. Remove rules that are unused, redundant, or difficult to explain instead of letting them accumulate.

A second step is split DNS. Map out app queries, client-side resolution, remote resolution, and the system cache, then check the network dependencies at each stage. Don't judge a resolver by its name; observe the addresses it returns for your actual destinations and whether those addresses suit the final outbound. With encrypted DNS, also consider how the resolver's own hostname gets resolved. A clear startup path is easier to maintain than a long list of backup resolvers added without a plan.

Distinguish complete configurations from snippets

A third step is understanding generated configuration. Use the client's built-in viewer to inspect what actually runs, then learn the roles of inbounds, outbounds, routing, and DNS. A GUI client may regenerate configuration files on startup or save, so direct edits to generated output may not last. If you need a custom configuration, first understand how your client loads it and what it supports, and keep a complete baseline. A partial example missing other sections isn't a complete file you can run as-is.

Learn protocol parameters in response to a real need. If a configuration includes a new field, first check which core and client support it, then understand its dependencies. Don't change authentication or security settings your service hasn't provided just to try a protocol. The transport, server name, and related security fields must match the remote server; the client can't decide them on its own. As you read the glossary, connect each term to your actual configuration and note what conditions make it effective.

Finish each learning session with a verification checklist

A complete check covers connectivity, routing, DNS, LAN access, and recovery after exit. Confirm that apps needing a proxy work, and that resources meant to connect directly still do. Test first startup as well as network switching, waking from sleep, and rebooting. Choose test cases from your actual workflow rather than chasing a particular benchmark. Behavior varies across networks, so recording the environment is more useful than keeping a single result.

When you're done, turn temporary experiments into a short maintenance note: why each setting was added, how to verify it, how to disable it if something goes wrong, and which fields may need updating when the service changes. For quick setup, return to the setup guide. To replace a client, check the platform options on the downloads page. For a specific error, go to the relevant section and troubleshooting guide. Clear boundaries and a rollback path keep your setup understandable, testable, and maintainable as your needs grow.