Import a subscription to see your server list here
System proxy: Automatic·Routing: Bypass mainland China·Core: Xray
Static v2rayN interface preview. Menu names and layout may change with client updates. Indicators and switches do not reflect the connection status of your device.
For desktop, start with v2rayN. On Android, use v2rayNG by default, or consider v2flyNG for setups using the V2Fly core. Check your operating system and processor architecture before choosing a download.
v2rayN offers a desktop edition and a classic WPF edition. The desktop edition uses a cross-platform interface, while the WPF edition retains its familiar layout. Before installing, check the system requirements. If you're already using v2rayN, back up your subscription groups and routing settings first.
After installation, import one valid subscription, select a server, and configure the system proxy. TUN requires additional permissions and a network interface, so leave it off during the initial check. Verify that the basic proxy works first to distinguish configuration issues from permission problems.
v2rayN offers downloads for Apple Silicon and Intel Macs. Check your chip or processor in About This Mac and choose the matching build—don't rely on the computer's appearance or purchase year.
Install the app in an appropriate location before launching it. If macOS displays a security alert, verify the download source and app details, then follow the instructions in System Settings. After importing a subscription, you still need to choose a proxy mode; simply opening the app won't route traffic from every application.
v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Most recent devices use arm64; if you're unsure which architecture you need, check for a universal build. Protocol capabilities and parameter handling depend on the core in use.
The first time you connect, the app will request permission to establish a VPN connection. Granting permission allows it to route traffic, but doesn't guarantee that the remote server is available. If the connection drops when the screen locks, check background activity, battery restrictions, and per-app proxy rules before assuming the subscription has expired.
v2rayN offers deb and rpm packages for x64 and arm64. First check your distribution's package format, then your processor architecture. Matching package formats doesn't guarantee identical desktop dependencies, permission policies, or system proxy behavior.
A desktop environment's system proxy usually affects only apps that honor that setting. Check terminal tools, containers, and apps with their own proxy settings separately. Before enabling TUN, review permissions and existing virtual networks. If something goes wrong, restore the previous network path before troubleshooting.
Prepare the client, subscription, and server separately
The client stores configuration and runs the core; it isn't a server. A subscription is one way to retrieve server settings in bulk. Its expiration, access permissions, and format are determined by the provider. Before installing, have a trusted subscription source or a complete configuration ready. Installing the client alone doesn't establish a connection.
Start with a basic setup you can reproduce
For your first setup, import from one source, select one server, and verify it with a single proxy mode. Once it works, add subscription groups, custom routing, or TUN. Change one setting at a time and note what changes so you have a clear rollback point if something breaks.
GUI clients organize common settings into menus; the core uses the resulting configuration to handle traffic. The snippets below illustrate how fields relate and are not complete configurations you can use to connect.
Subscription links and groups
Subscriptions let you update server settings in one place; they're not client login accounts. Save a link in a subscription group, give the group a name, and then update it. After importing, select the server you want to use. Keep different sources in separate groups to make broken links easier to identify and avoid mixing them with manual configurations. If parsing fails, check the link's expiration, response content, and supported format instead of repeatedly reinstalling the client. Subscriptions often contain access credentials, so hide the full link before sharing logs or screenshots. The example below uses an unsupported format.
https://subscription.example.com/list?token=xxxx
Rule order determines which rule matches
Routing selects an outbound based on conditions such as domain, destination address, and port. Rule order affects the result: put specific exceptions before broader rules, and make sure every referenced outbound tag is defined. Domain and IP rules rely on different information; after changing DNS, check which rules are matching. The snippet below sends private IP addresses to a direct outbound to illustrate the rule structure. It isn't a complete routing setup and doesn't include all DNS settings. Before importing someone else's rules, check that the core supports their syntax and rule resources.
A system proxy sets a local proxy address in the operating system and mainly affects apps that honor that setting. TUN uses a virtual network interface to capture traffic that matches its routing rules and often requires additional permissions. Neither option is a higher or lower tier of connection quality. For troubleshooting, start with one method and avoid stacking other network tools. The snippet below shows fields for a local SOCKS inbound; its port is an example, not a fixed value for every installation. If you configure a proxy in an app manually, its address, port, and protocol must match what the client is actually listening on.
The client edits and manages settings; the core handles protocols. Switching cores doesn't automatically convert every configuration. First check that the target core supports the protocol, transport, and security settings you need, then inspect the generated configuration and startup logs. On desktop, choose from the cores offered by your client. The two Android clients follow different core paths, so they're not the same app with different names. The log fields below help explain the core configuration layer, but a log level alone can't tell you whether a server is compatible.
{
"log": {
"loglevel": "warning"
}
}
Move your subscriptions, then recheck local settings
Cross-platform migration here means moving subscriptions or configuration; it doesn't imply that the client includes built-in cloud sync. You can import a subscription on multiple devices, but local listening ports, system proxy settings, TUN permissions, and per-app rules need to be configured for each platform. Back up your existing configuration before migrating. Then update the subscription and test one server before restoring your routing rules. The snippet below illustrates a direct outbound. Whether a full configuration can be reused depends on core and field support—not just the file extension.
Seeing entries in the server list only confirms that the client has read the configuration. You still need to check the selected server, system time, proxy mode, and the target app's network settings. If a browser works but other apps don't, first check whether those apps honor the system proxy. If all requests fail, check whether the core started, whether the logs report configuration errors, and whether the subscription's address and port are valid.
Latency tests also measure different things. Ping generally reflects a network probe; actual proxy latency includes establishing a proxy connection, while download speed depends on bandwidth, the test target, and timing. A low number doesn't replace testing real access. For the full first-time setup, see the quick start guide. For installation, permissions, and routing details by operating system, read the all-platform guide.
PROJECT / CORE / CLIENT
Project V ecosystem and open-source clients
Projects, cores, and graphical interfaces operate at different layers. Understanding the distinction helps you choose a client and narrow down configuration problems.
PROJECT V
Where it starts: proxy tools and configuration
V2Ray is a proxy tool in the Project V ecosystem, with configuration built around concepts such as inbounds, outbounds, routing, and transports. In everyday use, “V2Ray client” often refers to a GUI app for managing these settings, not a single core program. This distinction explains why the same subscription can appear in different menus across apps, and why interface updates and protocol support updates don't always happen together.
A server configuration usually combines a protocol, address, port, identity, transport, and security settings. Seeing VMess, VLESS, or another protocol name isn't enough to determine whether a configuration will connect. The transport options, server requirements, and core used by the client must all match. Treat protocol names in tutorials as clues for checking settings, not guarantees of speed or reliability.
V2FLY / XRAY
Core branches: similar concepts, different support
The V2Fly community continues to maintain V2Ray-related implementations, while Xray is another core branch developed from V2Ray. They share some configuration concepts but evolve independently. Similar JSON fields in a guide don't mean every newer option works across both cores. Import failures, startup errors, and connection failures after launch occur at different stages. Identify the core in use first, then check the error for the relevant stage.
When switching GUI clients, prioritize subscriptions or share links supported by both. Copying an entire custom configuration can also carry over platform-specific paths, resource references, and listening settings. If a field isn't supported, keep the original configuration and find out what the field does before removing it. Removing an error-triggering field may let the client start while changing the original routing or security behavior. Choose a core based on configuration requirements, not whether its name sounds newer.
OPEN SOURCE
Three clients: interface roles and license terms
v2rayN is an open-source desktop GUI client for managing servers, subscription groups, routing, and core usage. v2rayNG is an open-source Android client that uses the Xray core; v2flyNG follows the V2Fly core line. All three are configuration and connection tools—you need to source servers separately, and a GUI doesn't determine whether a subscription service is available. Choose by platform first, then check support for the protocols and settings you need.
The V2Ray and Xray cores use the MPL-2.0 license; these three GUI clients use the GPL-3.0 license. Licenses describe the terms for using, modifying, and distributing code. They aren't terms of service for remote services and don't establish whether a subscription source is trustworthy. Clients, cores, and bundled components may each have their own licenses. For redistribution or modification, consult the license text included with each project.
Open source makes code and development processes available for review, but it doesn't mean every installer, configuration, or subscription source is equally trustworthy. Keep account details and subscription credentials in a secure location. When asking for help publicly, share only the error details needed and redact identity fields, access tokens in full URLs, and anything else that could expose subscription access.
MAINTENANCE
Update in order: back up, review changes, test one thing at a time
Client updates may change the interface, dependencies, configuration generation, or bundled core. Before upgrading, save your subscription sources, custom routing, and important local settings, then read the release notes for that version. After upgrading, check startup and subscription updates first, then the system proxy or TUN, and finally custom rules. Changing several things at once makes failures harder to trace—especially when you replace a subscription, switch cores, and adjust DNS together.
A core update can't fix every connection problem. An expired subscription needs a current source; an incorrect system clock needs to be corrected; missing permissions require system authorization; and an unavailable remote server needs a status check. Reproducible tests are more useful than repeated reinstalls: use the same network, server, and target app, change one thing at a time, and record what changes in the logs.
READING PATH
Reading order: separate quick-start steps from platform details
For your first setup, follow the quick start guide to import a subscription, select a server, set a proxy mode, and test access. Once you're connected and want to change which traffic is routed, read about routing, permissions, and platform differences in the all-platform guide. This gets the basic setup working first and avoids changing your entire network configuration just to understand one option.
If the problem occurs while updating a subscription, check whether the link is still valid and whether the response is in a format the client supports. If it occurs while connecting, start with the core logs and system proxy path. These stages call for different evidence. When describing a problem, include the client, operating system, proxy mode, and steps that triggered the error. That's usually more useful than simply saying “can't connect.”
RECENT NOTES
Configuration guides and Troubleshooting
Start with the local network, subscription groups, and Android background permissions. Identify where the problem occurs before changing the configuration.
Troubleshoot in order: local network, system proxy and TUN, client routing rules, core logs, and node settings. Find out whether the timeout is on your device or the server.
When using multiple subscription providers, keep sources separate with subscription groups. Use alias keywords to filter, sort, and test servers in batches to keep the server list organized.
v2rayNG uses Android VpnService to route traffic. Learn about the permission prompt, background disconnections caused by device makers' battery policies, and per-app proxy settings.