Choose a client · Import subscriptions · Configure routing
Choose an open-source client for your platform, start by importing a subscription, then configure routing and TUN mode.
CONFIGURATION / SETUP OPTIONS
First, distinguish subscriptions, traffic entry points, and outbound rules before changing specific settings. Choose a setup topic on the right; the mock interface on the left highlights the corresponding controls. It illustrates how the settings relate—actual menus depend on your client.
Interface illustration only; it does not show the current connection status. Import a subscription first, then verify the proxy and routing.
A subscription URL provides node configurations in one place; groups keep different sources separate. In v2rayN, add a subscription group, enter a name and URL, save it, then update the group and select an active node from the list. In v2rayNG, add the subscription first, then update it. Updating an existing group is not the same as adding it again; if nodes are duplicated, check which group they came from. Subscription links may contain access credentials, so don’t share them in public screenshots or with unfamiliar conversion websites. The graphical client parses the configuration; having a link does not mean the connection is working.
Learn moreSystem proxy settings determine whether apps send connections to the local client; routing determines which outbound handles connections once received. These are separate settings. On desktop, start with “Automatically configure system proxy” and test in a browser. Before closing the client, clear the system proxy so apps don’t keep pointing to a local port that is no longer listening. Some command-line tools and apps with their own proxy settings don’t use system settings and must be configured separately. If the browser works but command-line tools don’t, check how their traffic enters the client before switching nodes or routing all traffic through it.
Learn moreRouting rules match connections by criteria such as domain or destination address, then send them through a proxy, directly, or block them. For an initial setup, start with a built-in client rule set such as “Bypass mainland China,” then add a few custom rules based on logs. Rules are generally evaluated from top to bottom, so put specific domain exceptions before broad rules. Domain strategy and DNS resolution affect address matching; a rule’s name alone doesn’t tell you where traffic will go. Unlike a single proxy toggle, routing requires understanding the traffic entry point, match conditions, and outbound tags. Verify each change.
Learn moreTUN mode handles traffic through a virtual network interface, which can help with apps that ignore system proxy settings. Its coverage still depends on routing, permissions, and app exclusions. First confirm that a standard proxy connection works, then enable TUN and grant the permissions requested by the client. If other network tools are running, check for conflicts involving the default route, DNS handling, or virtual adapters. Enabling TUN does not mean every connection will use the proxy; routing rules can still send traffic directly. To troubleshoot, turn TUN off and compare results, preserve local network access, and note the original network settings so you can restore them.
Learn moreThe client provides the graphical interface; the core handles connections and routing. Being able to import a link for a protocol does not guarantee that the selected core supports all its settings. v2rayNG uses the Xray core, while v2flyNG is an Android alternative based on the V2Fly core. Check the selected core to determine what v2rayN supports. VMess, VLESS, and Trojan are protocol names; REALITY is a security-layer configuration, so these terms are not interchangeable. If a field is unsupported or startup fails, first check the node’s protocol, transport, and security-layer combination, then review the core output.
Learn moreCLIENTS / CHOOSE A PLATFORM
For desktop, start with v2rayN; for Android, start with v2rayNG. Choose an installer that matches your operating system, processor architecture, and package format. Node configurations for phones, desktop installers, and core files are different things.
v2rayN · Cross-platform desktop / Classic WPF
Choose the cross-platform desktop edition or classic WPF interface. Check your OS and processor, and avoid running clients on the same local port.
Browsers usually follow the system proxy; terminals may need separate settings. If browsing fails after exiting, check that the proxy was cleared.
Go to downloadsv2rayN · Apple Silicon / Intel
Check “About This Mac”: Apple Silicon needs arm64; Intel needs x64. Install the matching package and follow the system’s launch permission prompts.
Test the system proxy first; TUN needs additional permissions. After changing networks, check proxy status and routing before importing subscriptions again.
Go to downloadsRecommended: v2rayNG · Alternative: v2flyNG
Use v2rayNG with Xray or v2flyNG with V2Fly. Most recent phones use arm64; check the universal build notes if you’re unsure of the architecture.
Select a node, connect, and approve VPN access. If sites fail, check the node, DNS, and routing. For background disconnections, check battery restrictions.
Go to downloadsv2rayN · deb / rpm
Choose deb or rpm for your distribution and x64 or arm64 for your CPU. Avoid mixing the desktop client with system services that use the same port.
Test browsers, terminals, and package managers separately. Start with the system proxy, then configure TUN permissions and routing if broader coverage is needed.
Go to downloadsQUICK START / SETUP ORDER
Change one thing at a time. First, get a working configuration into the client. Then decide which apps should use it, and finally verify that the rules behave as expected. These three steps work for a first-time setup or when rebuilding your setup on a new device.
After installing and opening the client, have your subscription URL ready. In v2rayN, add a group in the subscription group settings, enter a recognizable name and URL, save it, then update the group. In v2rayNG, add the URL from the subscription menu and update that subscription. The name is for local organization; it cannot replace the full URL. The example https://example.com/sub?token=xxxx is not a working subscription and should not be copied as one.
After updating, check that the node list shows details such as protocol, address, and port. If it’s empty, check the update result, confirm the URL is complete and still valid, and make sure your current network can reach it. Don’t keep adding the same URL; that just creates duplicate groups. Subscription URLs may contain personal access credentials, so hide the full link before sharing a screenshot. Installing the client and getting a subscription are separate steps; installing the software does not create usable nodes.
Select a node from the imported list, then choose how apps send traffic to the client. On desktop, start with “Automatically configure system proxy.” On Android, allow the VPN service when starting the connection. Next, choose an existing routing profile and understand the difference between direct, proxy, and blocked traffic. There’s no need to change DNS, add custom rules, and enable TUN all at once. Menu names may vary by edition, but the order stays the same: select a node, route traffic into the client, then choose an outbound.
System proxy settings do not route traffic from every program. Browser extensions, custom proxy settings in developer tools, and terminal environment variables may override or bypass them. If only one app fails, check how that app handles proxy settings first. If an app ignores system proxy settings, read the TUN guide and check the required permissions. Global routing and TUN are not the same: routing affects outbound selection, while TUN mainly determines how traffic enters the client.
After starting the client, open a destination you need to reach and check the connection log for the corresponding request. Then visit a destination expected to connect directly and verify the routing result. If you use local network devices, confirm they’re still accessible too. A successful connection, a successful subscription update, and an accessible webpage are three different outcomes; none proves the others. Keep the node and rules unchanged during each test so you can identify what caused the result.
If it fails, check in order: whether the core started, whether the local listening port is available, whether the request reached the client, and which outbound rule matched. A timeout may occur while connecting to a remote server; for DNS resolution failures, check DNS first; if the core exits immediately, review its startup output. Hide subscription URLs, credentials, and personal addresses when sharing error details. Once the connection is verified, add routing exceptions one at a time and save a restorable copy of the configuration. Use the same troubleshooting sequence after future updates.
PROJECT V / OPEN-SOURCE ECOSYSTEM
Graphical clients, connection cores, and node protocols are separate layers. Understanding how they fit together helps you identify whether to update the interface, core, or remote configuration.
Ecosystem overview · Not a live status
Open-source networking ecosystem
The client manages configuration; the core handles connections. Supported features depend on the selected core and combination of settings.
Explore the projects →Project V is an open-source ecosystem of proxy tools and related components, with V2Ray as one of its widely used core projects. V2Fly continues community development along the V2Ray path, while Xray is a separate core that grew from related code. They share some concepts and configuration conventions, but their features and supported settings differ. When reading an older guide, first check which core it covers; don’t assume every configuration applies just because it uses “V2Ray” as a catch-all term.
Whether a node works depends on whether the client can generate the right configuration, whether the core understands its settings, and whether the remote service uses the same protocol combination. Successfully importing a link only confirms part of the parsing process. For errors involving REALITY, security layers, or transport settings, check core support and remote parameters first. Switching interface themes or repeatedly refreshing a subscription usually won’t fix a protocol mismatch.
v2rayN is designed for desktop use and manages node lists, subscription groups, system proxy, and routing, making it a good starting point for desktop devices. v2rayNG is for Android and uses the Xray core to import nodes and manage connections. v2flyNG is also for Android and is an alternative based on the V2Fly core. Choose based on your device and node requirements; you don’t need to install all three.
Similar client names don’t mean their menus, permissions, and backup formats are identical. When moving to another device, first confirm the subscription source still works, then set up the client again. Review routing exceptions, app exclusions, and DNS options separately. Desktop and Android also handle traffic entry differently, so don’t apply desktop system proxy steps directly to a phone. Download options and setup guides are separate here, making it easier to find the right instructions for each step.
v2rayN, v2rayNG, and v2flyNG are open-source clients. Public code lets the community review, discuss, and improve them. Open-source licenses set the terms for using, modifying, and distributing code; different projects and included components may use different licenses, so review each notice before redistribution. Open source describes how software is developed—it says nothing about the quality or data practices of a node service and does not replace checking the source of a subscription.
The client handles local configuration and connections; the subscription source provides node settings; the remote service forwards traffic. Each may have a different maintainer and update schedule. When reporting an issue, distinguish “the app won’t start,” “the subscription won’t update,” and “a node won’t connect” to identify where the problem lies. This site provides selection and setup guides, not subscription URLs. Use configurations you already have permission to use, and follow the rules that apply where you are.
Updating a subscription changes the node configurations in a group; updating the client changes its interface and integrated features; updating the core can affect protocol support and configuration fields. These are separate operations. For routine maintenance, save a recoverable copy of your settings first, then review the release notes and check compatibility with your core, routing resources, and existing nodes. After an important configuration change, verify three things again: the request reaches the client, the expected rule matches, and the destination is reachable.
For long-term use, periodically remove expired groups and duplicate nodes, and document the purpose of custom rules. You can temporarily increase log detail when troubleshooting, but don’t publish logs that reveal destinations or credentials. If a problem appears after an update, compare the startup output and configuration changes before adjusting multiple network settings at once. The full guide covers concepts, installation, subscriptions, routing, TUN, and maintenance in sequence.
Read the complete guide, from beginner to advanced →READING / SETUP & TROUBLESHOOTING
Once the basic connection works, read on to solve specific problems. These three articles cover custom rules, system proxy traffic entry, and log-based troubleshooting—in that order—helping you move from “it connects” to understanding where each connection goes.
Learn the full, domain, keyword, and regexp prefixes for domain rules; ip and geoip syntax; geosite categories; how rules are evaluated from top to bottom; and how domainStrategy affects matching.
Read about rule syntax →System proxy is on, but webpages or command-line tools still connect directly? Troubleshoot browser extensions and system settings separately from terminal http_proxy variables, with steps to check proxy status on each platform.
Check the traffic entry point →Learn what each loglevel is for, understand common messages about connection timeouts, handshake failures, and DNS resolution errors, and use logs to pinpoint where a problem occurs.
Read the log guide →