01 · General Prerequisites
Before You Install: Check Your Device, Subscription, and Traffic Entry Point
Choose a Client, Then Pick the Right Package
For desktop systems, v2rayN is the recommended choice. On Windows, distinguish between the desktop and classic WPF editions, and check your system architecture. On macOS, identify whether your device uses Apple Silicon or Intel. On Linux, check your distribution's supported package format and processor architecture. For Android, v2rayNG with the Xray core is the usual choice; consider v2flyNG only when an existing configuration specifically requires the V2Fly core. The client provides the interface and manages configuration; the core handles the actual connection. They are not the same thing. Even when a desktop client lets you switch cores, your existing transport and security settings may not work unchanged with another core.
Don't infer your system architecture from a package filename, or rely on another device's download history instead of checking your own. For example, you can import the same subscription on a computer and a phone, but a system proxy address used on the computer is local to that device and cannot simply be copied to the phone. For each device, note the client name, system architecture, and intended traffic-handling method. If the device is managed by an organization, check first whether software installation, virtual network interfaces, or proxy changes are allowed. Don't bypass policy restrictions by running commands with elevated privileges.
| Platform | What to Check When Choosing a Package | Where to Start Testing Traffic Handling |
|---|---|---|
| Windows | System architecture; desktop or classic WPF edition | Start by testing with a browser that follows the system proxy |
| macOS | Apple Silicon or Intel | Check proxy settings for the active network service |
| Linux | Distribution, deb or rpm package, processor architecture | Start by configuring a local proxy for one application |
| Android | Supported architecture and core requirements | Allow the system VPN, then verify which apps are covered |
Know the Difference Between a Subscription URL and a Share Link
A subscription URL lets the client fetch a list of entries from a remote server. This usually takes two steps: save the subscription first, then manually update it. Seeing the subscription group only confirms that the URL was saved; it doesn't mean the nodes have been fetched. Links beginning with vmess:// or vless:// are usually individual share links. Import them from the clipboard or as share links, not in the subscription URL field. Likewise, entering a subscription URL as a server hostname in a manual configuration won't create a usable node. Before importing a QR code, check what kind of content it contains.
Make sure the source provides a configuration that a V2Ray client can read, not an account management page, payment page, or URL that requires a browser session. Subscription updates and node connections use separate request paths: a successful update only means the client could retrieve the list. Connecting to a node also depends on the server, transport, and security settings. Name each subscription group with a note about its purpose and source. For your first test, select just one entry and keep a known-working configuration for comparison. Don't delete the old group as your first troubleshooting step: an update may replace its entries, and temporary manual changes may not be retained.
Record a Baseline Before Enabling TUN
Before the client handles any traffic, confirm that your network can reach a site you normally access directly. Note the network in use, other proxy apps, organizational VPNs, and custom DNS settings. If a public network has a sign-in page, complete its usual network authentication first. This gives you a baseline to compare against if sites that worked before stop opening after you enable a proxy. On desktop, also note the listening address, port, and protocol shown by the client. Even when they use the same local port, HTTP and SOCKS are not interchangeable.
For your initial setup, use just one traffic-handling method. The system proxy provides an entry point for apps that honor that setting. TUN uses a virtual interface and routing to handle more traffic, but it also involves more permissions and can have a greater impact on DNS and other network tools. If you only need to test a browser, start with the system proxy or the browser's own proxy settings. Once one node and one app are working, move on to programs that don't use the system proxy. This makes it easier to tell whether the node never connected or a problem began after changing which traffic is handled.
02 · Desktop Clients
Windows: Install v2rayN and Set Up the System Proxy or TUN
Choose Between the Desktop and Classic WPF Editions
In Windows, open Settings → System → About and check your system type, then verify the package on the Windows downloads page. Both downloads listed in this guide are x64. The desktop edition uses a cross-platform interface and is a good starting point for new users. Choose the WPF edition if you're already familiar with its classic interface, older screenshot-based guides, or its workflow. These are alternatives, not companion components, and you generally shouldn't run both at once during initial setup. Doing so can cause port conflicts, or one client may clear the system proxy settings written by the other when it exits.
If you downloaded an archive, extract it completely to a directory that's writable by your user and easy to find, then launch the app from there. Don't double-click the executable in the archive preview or move only the main program out of the extracted folder. If you downloaded an installer, follow its prompts rather than applying instructions for relocating a portable version. If startup reports a missing runtime, check the component type and architecture named in the message, then consult the current release notes and obtain the matching runtime from its publisher. If security software blocks the app or an organization policy restricts it, review the details instead of disabling protection globally. For package selection, see the Windows Desktop vs. WPF Installation Notes.
Import a Subscription and Confirm the Core Starts
In the subscription group settings, add an entry with the subscription URL and a note. Save it, then select the group and trigger an update. If the interface offers both direct updates and updates through a proxy, try direct first if you don't have a working proxy yet. Test updating through a proxy only if the subscription source requires one you already have available. Once entries appear, select one as the active server, then check the core status and logs. A highlighted entry doesn't prove the core is listening, especially if an older client or development tool is already using the same port.
If you have an individual link, import it from the clipboard. Check that its protocol, address, port, transport, and security settings match the source's instructions. Don't enter the client's local listening port as the remote server port. Menus may differ between the desktop and WPF editions. If you can't find an option, look for features named “subscription group,” “active server,” or “system proxy” rather than clicking where an older tutorial screenshot shows. If the client fails to generate the core configuration, start with the first specific error in the logs instead of repeatedly switching nodes.
Test the System Proxy First, Then Handle Apps That Need More
Enable the system proxy in v2rayN, then check its actual status under Windows Settings → Network & Internet → Proxy. Test with a browser that honors the system proxy and doesn't have a proxy extension taking over. If the system proxy points to the current client but the core isn't listening, the browser will usually fail to connect locally. If the browser works but terminal apps don't, that doesn't mean the connection is unstable: terminal tools may use their own settings or environment variables, and some services run under other accounts. Start by checking each app's entry point using the Browser vs. Terminal Troubleshooting Notes.
If you need to cover apps that don't use the system proxy, first exit other proxy or virtual network tools, then try TUN on its own. Follow the client's prompts to check permissions or driver status, and test everyday sites, the target app, and local network resources both before and after enabling it. If your company intranet or shared devices become unreachable, switch back to the previous mode and check whether TUN took over an existing internal subnet, DNS resolution, or the default route. Running the GUI as an administrator isn't a universal fix for network problems; it won't resolve a failed node handshake or a port conflict.
03 · Desktop Clients
macOS: Install v2rayN for Your Chip and Check Network Services
Choose the Right Disk Image Using System Information
Open About This Mac from the Apple menu. If it shows an Apple chip, select the Apple Silicon package on the macOS downloads page; if it shows an Intel processor, choose the Intel package. Don't rely only on the architecture reported by a terminal process: if the terminal itself is running in a translation environment, its result may not tell you the architecture of the Mac. Open the disk image and follow its instructions. Typically, you drag the app into Applications and launch it from there rather than repeatedly opening a copy from the mounted volume.
On first launch, if macOS shows a permissions or security alert, check the app name, download source, and system information. If the alert reports damage, malware, or an organization restriction, troubleshoot that specific warning instead of disabling system protection globally. After an update, make sure you're launching the newly installed app, not an older copy in Downloads or on the disk image. If the app crashes, first check whether its interface opens reliably before troubleshooting subscriptions and nodes. Routing rules can't help if the app hasn't launched. See the Desktop First-Install Checklist to identify startup issues.
Import a Subscription and Keep the First Test Focused
Create a subscription group in subscription management and update it. Select one server as the current entry, then check whether the core starts. Before importing from the clipboard, make sure you've copied the raw URL—not a block of instructions and a link from a chat app. Remove only extra whitespace at the beginning or end; don't edit the path, query parameters, or encoded characters. If you can sign in on the website but the client can't update, check whether you have the client subscription URL. Opening an account page in a browser doesn't prove that the subscription endpoint accepts the same URL.
For the first test, use just this group instead of migrating all app data from another computer. Old settings may include core paths, listening ports, or routing files that no longer exist. Migrate subscriptions and app settings separately: import the original subscription on the new device and confirm that a node works, then restore only the rules you actually need. Record old values before making changes so you can return to a working setup if a new rule breaks a specific domain.
Distinguish the Active Network Service, App Proxy, and TUN
After enabling the system proxy, go to System Settings → Network, select the active network service, and open its proxy settings. The labels and locations may vary slightly between macOS versions. Check whether you're using Wi-Fi or Ethernet, and confirm that the enabled proxy type, address, and port match the client. Check again after switching network services: settings that worked over Ethernet may not take effect as expected over Wi-Fi. Also check whether an automatic configuration script or another management tool could be changing the settings.
You can use Terminal to view the proxy settings currently reported by macOS. The command below only reads information; it doesn't change any settings. Compare the enabled flags, proxy host, and port in the output with what you see in System Settings. Even if macOS reports that a proxy is enabled, that only confirms the setting exists—it doesn't prove that a command-line tool uses it. If a browser and terminal behave differently, check the terminal tool's own network options. If you've configured a proxy directly in an app, don't use its behavior alone to decide whether the system proxy is working.
scutil --proxy
Before enabling TUN, check that your current version offers the option and follow the client's instructions for permissions. Don't change the system proxy, routing rules, and DNS all at once before verifying the core and node. If the connection drops after switching Wi-Fi networks, waking from sleep, or unplugging Ethernet from a dock, first confirm that macOS is back online. Then check in this order: disable additional traffic handling, retest the core, and re-enable TUN. If only company sites or local devices are affected, return to a known-working traffic mode and check the routes and DNS settings needed for intranet access.
04 · Desktop Clients
Linux: Install v2rayN and Set Up Desktop Proxy or Virtual Interfaces
Check Your Distribution and Processor Architecture First
Choose v2rayN from the Linux downloads page. Debian, Ubuntu, and related distributions usually use deb packages; Fedora and other RPM-based distributions use rpm. Check the architecture as well as the package format: x86_64 corresponds to x64, and aarch64 to arm64. Some system tools use amd64 for the same x64 architecture. If your distribution isn't a target environment for these packages, don't rename the file extension or force installation to work around dependency differences. Check distribution compatibility first.
uname -m
cat /etc/os-release
On a desktop, open the package with the software installer. If you prefer the command line, use your distribution's package manager to resolve dependencies and select the actual file from Downloads. When installation fails, check whether the message points to an unsupported architecture, missing dependencies, or an unavailable package repository. Don't create arbitrary links to system libraries, and don't run the GUI as an administrator by default. The app may then save configuration and cache files under another account, making it appear like a fresh install when you return to your regular user—and making permission issues harder to distinguish from client issues.
Import a Subscription and Test with One App
Launch v2rayN as a regular user in the current desktop session. Add a subscription group, update it, select an active server, and note the actual listening port once the core starts. If your browser has its own proxy settings, you can configure just that browser to use the proxy. This gives you an independent test even if your desktop environment doesn't apply the system proxy. If an old instance, container, or development program has used the same port, check what's listening first. Then stop the old instance or choose a free port, and update the browser's test settings to match.
On common Linux desktops, desktop proxy settings and command-line programs don't share a reliable traffic-handling mechanism. Desktop apps may follow GNOME or KDE proxy settings, or manage their own proxy. Terminal programs use their own settings or environment variables. For a temporary test, prefer a one-off command-line option or an app-specific setting instead of immediately adding proxy variables to a global environment file. A global proxy left in place can cause package managers, build processes, and background tasks launched later to keep connecting to a closed port after the client exits.
Check Differences in TUN, Routing, and DNS Resolution
If you need to route traffic from apps that don't use an app proxy, check that your installed version supports TUN and that your environment allows virtual interfaces. Common limitations include an unavailable device, insufficient session permissions, or a virtual machine or container without the required network permissions. These messages indicate that the interface hasn't been created; changing subscriptions won't fix it. First retest the regular app proxy, then check the error and your distribution's documentation. If someone else manages the environment, ask the administrator about permissions rather than granting device access to all users.
Before and after enabling TUN, compare the interfaces and IPv4 routes visible in the current session. The commands below are read-only. An unchanged default route doesn't rule out TUN: the client may use policy routing instead. Review the output alongside client logs and whether the specific request reached the core. If remote access is your only way to manage the machine, don't test traffic-handling changes without a recovery plan—you could lose your connection after changing routes.
ip -brief address
ip -4 route show
ip -4 rule show
If one domain fails while other requests work, first check whether it only happens under TUN, then compare DNS behavior in the app and the system. For example, a browser using its own encrypted DNS may get a different result from a system lookup. Switch back to a working app proxy for comparison, and don't change the resolver, routing table, and firewall all at once. If the app's request never reaches the core, check the traffic entry point. If it reaches the core but uses the wrong outbound, check the routing rules and DNS resolution.
05 · Mobile Clients
Android: Install v2rayNG, Import a Subscription, and Allow VPN Access
Choose the Package Architecture and Core
For most Android devices, choose v2rayNG from the Android downloads page; it uses the Xray core. Many newer phones support arm64, but installation also depends on the architectures supported by the device's OS, not just the processor specifications. If you're unsure which architecture to choose, use the universal package. It supports more architectures, but can't work around an incompatible OS version, insufficient storage, or organization restrictions. If you need to match an existing V2Fly configuration, choose v2flyNG. The installation and import steps are similar; check the core's actual capabilities for protocol and transport support.
During installation, Android may ask you to allow the app that opened the installer to install apps. First confirm that the file came from the downloads page, then follow the system prompt to allow this source for the installation. You can revoke that permission afterward. If installation reports a conflict with an existing app, don't uninstall it without a backup. Record your subscriptions and custom entries, and check whether you're trying to replace a build from a different source. Clearing app data also deletes existing configuration and shouldn't be your first troubleshooting step.
Update the Subscription and Check the Active Entry
Add the URL and a note in the client's subscription group settings, then return to the list and trigger an update. Once entries appear, open the group, select one as the current configuration, and start it with the connection button. For an individual share link, use clipboard import; subscription URLs belong in subscription settings. On a phone, copying can easily include nearby instructions. If you get a format error, make sure the clipboard contains only the URL or link instead of repeatedly tapping Update and expecting the client to recognize the text type automatically.
For your first test, use one app—ideally a browser without its own proxy settings or unusual network permission restrictions. On the same network, first visit a site that worked before, then test a destination that should use your configuration. If only one entry fails, compare it with a known-working entry in the same group to avoid mistaking an expired configuration for an installation problem. If the selected entry disappears after an update, check that you opened the right group, whether the subscription replaced its contents, and whether a new active entry is selected.
Handle System VPN Access, Per-App Proxy, and Background Disconnects
Android typically uses the system VPN interface to pass traffic to the client; the desktop step of “writing the system proxy” doesn't apply. On first launch, Android will show a VPN connection request. Allow it only if it comes from the client you just opened. A VPN icon in the status bar confirms that the system tunnel is established, not that the remote handshake succeeded. If another VPN app is active or Android has an always-on VPN configured, check which app is handling traffic. Don't change organization settings on a work profile or managed device without authorization.
When per-app proxy is enabled, check whether the list means “only selected apps use the VPN” or “selected apps are excluded.” The same browser can be checked in both configurations, with exactly opposite results. If one app consistently fails, first confirm whether it's within the current traffic scope, then check routing. If you change the scope during testing, record the original settings, change one thing at a time, and reconnect as the client requires before retesting. Otherwise, behavior from an existing connection can make it look like the new rule didn't take effect.
If the connection works but drops when the screen turns off, compare behavior with the screen on and off over the same Wi-Fi network. Then check whether Android pauses the background process or restricts background data; adjust the battery setting for this client only if needed. If it fails only on mobile data, check whether the app is restricted from using mobile data, Data Saver is enabled, and the subscription and node are reachable on that network. Don't change battery settings, per-app scope, and DNS at the same time, or you won't know which change fixed the connection.
06 · Cross-Platform Verification
V2Ray Routing and Connection Checks: From Traffic Entry to Outbound
Test the Entry Point, Core, and Destination Separately
Break a connection test into three questions: Did the app pass the request to the client? Did the core send it through the expected outbound? Did the destination connection succeed? System proxy, manual app proxy, and TUN handle the first. Routing rules handle the second. Node transport, authentication, and the destination's response affect the third. Enabling a traffic-handling option doesn't guarantee that routing will choose the proxy. Choosing a broad proxy-routing mode doesn't mean every app's traffic reaches the client. For an overview, see System Proxy vs. Routing Modes.
On desktop, if the client provides an HTTP proxy listener, you can test it directly with a command-line tool. The example below uses 127.0.0.1:10809; replace it with the HTTP listener address and port shown in the client. In Windows PowerShell, if curl is mapped to another command, use curl.exe. This explicitly tests the entry point, unlike checking whether the system proxy setting was applied. It's useful for checking whether the local listener accepts requests and what error occurs afterward. A successful response doesn't prove the request used a remote node; check the routing logs too.
curl -v --max-time 15 --noproxy "" --proxy http://127.0.0.1:10809 https://example.com/
If the local machine refuses the connection, check the listening address, port, and core status first. If the local proxy responds but the request later times out, check the outbound matched by that request and the remote connection logs. If you receive an application-level response from the destination—even an error page—that's different from failing to connect to it at all. On Android, you don't need to install a terminal app just to run the same test. Choose an app you know is within the VPN's scope, note the time of the request, and compare it with the client logs.
Understand Rule Order and Tags
Common Xray and V2Fly routing configurations check rules in list order; the first matching rule determines the outbound. For example, to send specific private addresses directly, put the rule before broader rules that might also match them. The snippet below is a single item for a compatible core's routing.rules array, not a standalone configuration file. It assumes an existing outbound has a direct tag and routes traffic directly. When using graphical routing rules in a client, make sure the outbound name shown in the interface matches the tag in the generated configuration.
{
"type": "field",
"ip": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
"outboundTag": "direct"
}
This rule matches only the listed private IPv4 ranges. It isn't a general-purpose LAN discovery solution and doesn't include IPv6. If an app sends a domain name, the routing stage may not have an IP address to match. That depends on the core's domain handling policy and DNS resolution at the time. To handle specific internal domains, add the appropriate domain match using your existing rules and check which resolver is in use. Avoid changing DNS globally just to accommodate one new rule; that could affect other apps that rely on internal DNS.
Keep a Short Record to Verify Changes
Before and after a change, test a site that should connect directly, a destination that should use the selected outbound, and a resource that depends on existing LAN access. Change one variable at a time—for example, adjust rule order first and consider DNS separately. Record the app, traffic-handling mode, whether you used a domain or IP, the request time, and the outbound shown in the logs. That's more useful for reproducing the issue than simply writing “works” or “doesn't work.” Speed tests may check different parts of the connection, so a low latency result can't replace a real app test, and one timeout doesn't prove a node is unavailable.
If changing the node or rules makes no difference in the same app, close any reused connections or restart the test app, then check with a new request. A webpage opening from the local cache doesn't mean the network is back. Apps that keep long-lived connections may need time to reconnect. Once the result matches your expectations, save the working rules in a separate configuration or keep a record of the changes. After a subscription update or core switch, you can retest against the same destinations instead of guessing why the settings were chosen.
07 · Troubleshooting
Common Setup Issues: Failed Updates, Handshake Errors, and Restoring Settings
Did the Subscription Update Fail, or Did It Finish with No Usable Entries?
First check whether the interface reports a request failure, a parse error, or a completed update with an empty group. For request failures, check your network connection, device time, and whether updates use a direct connection or a proxy. If updates are set to use the local proxy but you don't have a working configuration yet, they may be stuck waiting for a prerequisite. For parse errors, confirm that the response is a configuration from the subscription endpoint—not a login page, expired link notice, or response requiring renewed authorization. A page opening in a browser doesn't prove the endpoint is accessible. Don't leave security checks disabled to work around a certificate error.
If the update completed but the list is empty, open the correct group, clear the name search, and check whether a filter is hiding servers that don't meet certain criteria. If you have multiple subscriptions, update only the affected group first so you can isolate the error. Entries disappearing after an update could mean the source removed them, or that the group's filters changed; these require different fixes. If you manage several sources, see the Subscription Groups and Server Filters Notes to keep each source separate and avoid confusing entries with the same name.
Getting a Timeout or Handshake Error? How to Narrow It Down
If the logs clearly show that a local port is already in use, resolve the duplicate client or port conflict first. The core may not even be ready to accept app requests. If there's a remote handshake record, compare the original configuration's protocol, transport, and security type. For certificate or domain errors, check the device date and time zone, and confirm that the server name matches the source's instructions. Don't treat ignoring certificate errors as a fix. If you switched cores in the client, make sure the new core supports the entry's fields and transport.
A connection timeout is broad: the remote host may be unreachable, DNS may have failed, or the destination may simply not respond. On the same network, test two known destinations, then try the same configuration on another network where testing is allowed. If one app fails with every configuration, check its traffic entry point and network settings first. If only one entry fails in that app, check that entry's remote parameters. When asking for help, include the earliest specific error, when it occurred, and what you tested for comparison. Don't let the last generic error obscure the original cause.
Lost Internet After Closing the Client? Restore Your Previous Settings
On desktop, first check whether the system still points to a local proxy port. If the core has stopped, a leftover manual proxy can leave apps that follow system settings unable to connect. Restore the settings you recorded before installation. On devices with an automatic proxy script or management policy, don't remove the original value. If only one browser or terminal is affected, check its own proxy settings and whether the current terminal session has proxy environment variables set. If a new terminal works but an old one doesn't, note that difference before considering a reinstall.
If the issue involves TUN or Android VPN settings, disconnect normally using the client or system interface, then check whether the interface and connection status return to normal. If problems persist, review and restore the VPNs, internal DNS, and per-app restrictions that were in place before enabling it, one at a time. Network changes, old processes, and cached connections can all affect your diagnosis, but don't start by resetting all network settings; that could also remove working Wi-Fi, organization proxies, and access rules. Once connectivity is restored, test an ordinary destination on the original network before deciding whether to re-enable the client.