From installing a client to importing a subscription, follow the steps to configure the proxy and routing. Test the connection first, then adjust advanced options.
CLIENT / CHOOSE BY PLATFORM
Use v2rayN on desktop. On Android, choose a client based on the core you need.
Check your operating system and processor architecture before downloading the matching client. The client manages configuration and launches the core; a working connection also requires valid server parameters or a subscription URL. Even if you already have a subscription, choose the right architecture first: whether an installer runs and whether a subscription connects are separate issues.
Choose v2rayN. The desktop version offers a cross-platform interface, while the classic WPF version retains a familiar desktop workflow. Pick the one that suits how you work. After installation, import a subscription before setting the system proxy to help distinguish installation issues from connection problems.
Go to downloadsUse v2rayN and choose an installer for Apple silicon or Intel. Check your chip under “About This Mac.” If macOS displays a security warning on first launch, verify the file’s source, then follow the instructions in System Settings.
Go to downloadsStart with v2rayNG, which is based on Xray; consider v2flyNG if you need a V2Fly core. Most recent phones use arm64. If you’re unsure, check the universal build details. On first connection, approve the system VPN prompt. If it disconnects in the background, check your battery restrictions.
Go to downloadsUse the v2rayN deb or rpm package that matches your Linux distribution and processor architecture. Desktop proxy settings may not apply to terminal programs. Test in a browser first, then check proxy environment variables for command-line tools separately.
Go to downloadsChanging platforms doesn’t change the protocol. Compatibility still depends on whether the client core, server configuration, and transport parameters match.
View all clients →CONFIGURATION / HOW IT FITS TOGETHER
Before changing settings, identify which layer each one controls. The examples below are partial configuration snippets, not complete files you can use to connect.
Add a subscription URL from a trusted source in subscription management, save it, then update the list and select a server. A subscription provides configurations in bulk; it does not enable the system proxy or grant VPN permissions. Compared with pasting shared links one by one, subscriptions are easier to update in one place, but an update may also overwrite entries managed by that source. Keep the default group for your first setup, then organize names after confirming the update worked. Don’t share subscription URLs containing access credentials in public screenshots. The snippet on the right shows a local inbound connection: importing a configuration still requires a traffic entry point. It is not a subscription file format.
Steps: Add a subscription → Update → Select a server → Enable the proxy.
{
"inbounds": [
{
"tag": "socks-in",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": {
"udp": true
}
}
]
}Start with a routing preset provided by the client. After confirming the connection works, add rules for your LAN, specific domains, or app requirements. Routing is typically evaluated from top to bottom, so put more specific conditions before broad ones. Unlike switching everything to global mode, split routing can preserve direct access to local resources, but you need to check that the outbound tag exists. The snippet on the right sends private IP addresses to an outbound named direct. A working configuration also needs to define that outbound and provide the relevant rule resources. After adding a rule, reload the core and test it against a specific destination.
Test one rule first, then broaden its scope.
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"ip": ["geoip:private"],
"outboundTag": "direct"
}
]
}
}Apps such as browsers that follow the system proxy can start with automatic system proxy configuration. Apps that ignore it need a proxy configured separately or TUN. TUN captures traffic through a virtual network adapter and involves permissions, routing, and DNS; it is not a speed boost. It covers more traffic than changing the system proxy alone, but is also more likely to conflict with other network tools. Don’t enable multiple traffic capture methods at once during initial setup. The snippet on the right shows a local HTTP proxy inbound. Its port must match the value entered in the app; use the port shown in your client settings.
Test with the system proxy first, then enable TUN if needed.
{
"inbounds": [
{
"tag": "http-in",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
]
}Check the protocol, transport, and security parameters required by the server before deciding whether a core supports them. v2rayN can manage configurations for different cores; on Android, choose between v2rayNG and v2flyNG based on your needs. Checking which core is actually running is more useful for diagnosing compatibility than looking at the client name alone. Save a working configuration before switching, then check the startup log to confirm that the fields were recognized. The two core families share some syntax, but their extended features are not necessarily interchangeable. The freedom outbound on the right is a basic example; it doesn’t mean every configuration can be migrated unchanged.
Prioritize protocol compatibility over interface preference; don’t judge performance by name.
{
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
}
]
}First check whether DNS is handled by the operating system, browser, or core, then decide whether to change it. A browser’s own encrypted DNS may bypass system settings, and TUN can use a different resolution path too. Instead of swapping a DNS server address alone, check how requests reach the upstream resolver to narrow down the problem. The snippet on the right shows the core’s DNS servers array. If you use a remote resolver, make sure its connection path is reachable. If direct IP access works but domain names don’t, check the DNS results and logs first; don’t change routing and transport parameters at the same time.
Change one DNS resolution path at a time, and keep a way to revert.
{
"dns": {
"servers": [
"https://1.1.1.1/dns-query",
"localhost"
],
"queryStrategy": "UseIP"
}
}What to do after installation
Get a minimal configuration working first; add split routing, TUN, and custom rules later.
Menu names vary between clients, but the setup logic is the same: first give the client server parameters, then direct app traffic to the client, and finally confirm that requests use the expected outbound. Keeping these three layers separate makes it easier to identify whether a problem is with the subscription, system settings, or routing—rather than repeatedly reinstalling the software.
Get a subscription URL from a trusted source. In v2rayN, add and save a group in subscription management, then update it. Android users can do the equivalent in v2rayNG’s subscription group settings. After updating, you should see configuration entries. If the list is empty, check that the URL is complete and the subscription is valid, then look for format or network errors in the update log.
Select an entry as the active server rather than stopping at “imported.” The protocol, transport, port, and security parameters must match the server; don’t change them based on the name alone. Subscription updates can change existing entries, so note your active group first. This also helps confirm which configuration you’re using when troubleshooting later.
On desktop, start the core, then choose automatic system proxy configuration and test in a browser. If you have a proxy extension, check whether it overrides the browser’s settings. Running another proxy app at the same time can also point the system proxy to the wrong port. On Android, you must approve the system VPN prompt for the first connection; this is separate from whether the subscription imported successfully.
For your first setup, choose a routing preset that fits your needs and avoid changing DNS, outbound rules, and TUN all at once. If you need to capture traffic from apps that ignore the system proxy, read the TUN instructions for your platform first. Before closing the client, clear any system proxy settings you no longer use so apps don’t keep sending requests to a closed local port.
Open a website you expect to reach through the proxy, then check the client log for connection and outbound details. Successfully opening one website only confirms that particular request worked; it doesn’t prove every app is using the proxy. Terminal tools, browsers, and desktop apps may each have their own settings, so test them individually as needed.
If the client shows connected but you can’t access anything, check server availability, device time, DNS resolution, routing matches, and the local port in that order. Note the error message, change one setting, and test before deciding whether to keep or revert it. A connected status usually means the core has started or traffic capture is active; it doesn’t guarantee the remote service is reachable.
Clients, cores & open-source licenses
The interface manages settings, the core handles connections, and protocols define how data is exchanged.
V2Ray originated in Project V’s modular proxy toolkit. Its configuration commonly includes inbounds, outbounds, routing, and DNS, which handle traffic entry, connection exit, rule selection, and domain resolution, respectively. “V2Ray client” is often used as a catch-all: it may refer to the core or to a GUI program that manages it. Know the difference before downloading. It explains why different clients can read the same subscription without necessarily behaving identically across all cores.
The V2Fly community continues developing and maintaining the V2Ray core, while Xray has evolved independently from related technology. Both use a configuration-driven proxy architecture, but their extensions, supported fields, and release schedules differ. VMess, VLESS, Trojan, and Shadowsocks are protocol names; TLS, transport, and routing policies are separate dimensions. Recognizing a familiar protocol name doesn’t eliminate the need to check transport and security parameters—and software with V2Ray in its name isn’t necessarily all the same product.
When choosing a core, first confirm compatibility with the complete server parameters, then consider how easy the client is to manage. If an import reports an unsupported protocol or invalid configuration field, check which core is actually running and review its feature documentation instead of repeatedly changing the system proxy mode. The system proxy determines how requests reach the client; core compatibility determines whether it can establish the remote connection correctly. Troubleshoot these as separate issues.
v2rayN is designed for desktop platforms, with a GUI for subscription groups, server selection, routing, and core settings. It suits users who want a similar workflow across desktop environments. v2rayNG is an Android client for managing proxies with the Xray core; v2flyNG is another Android option built around the V2Fly core. Desktop and mobile platforms handle network permissions differently. The goal of a setting may be the same, but button locations and permission flows aren’t interchangeable.
All three clients are open source, but each client interface and the core it uses are separate projects. Switching clients won’t fix an expired server in your subscription or automatically provide every extension supported by another core. If your configuration already works, choose a client that interprets it correctly. Before migrating, export or note any custom rules, then check that your subscription, proxy mode, and DNS settings are restored.
v2rayN and v2rayNG use GPL-family licenses, and v2flyNG is licensed under GPL. The V2Fly core uses the MIT License; the Xray core uses MPL 2.0. Software may also bundle separately licensed dependencies. Refer to the license texts included with the distribution you obtained for the applicable rights and obligations. Open source means code can be inspected, used, and redistributed under its license; it doesn’t mean the client projects provide network services, server resources, or third-party subscriptions.
For everyday use, it helps to understand the limits of what a configuration contains: clients may store server credentials and subscription URLs, so remove sensitive information before sharing screenshots or logs. Logs are usually enough to diagnose handshake, DNS, or port errors; there’s no need to publish an entire subscription. To learn terms such as UUID, outbound tags, and domain strategies, start with the terminology guide before changing related fields.
Client, core, subscription, and rule-resource updates solve different problems. A client update may change the interface or how configurations are generated; a core update affects protocol support and runtime behavior; a subscription update syncs server parameters; and a rule-resource update changes domain and IP address lists. First identify which layer changed, then choose how to respond. Don’t treat “update subscription” as a fix for every issue.
Save custom routing and important settings before updating. Afterward, confirm the active server, proxy mode, and local port. To check whether a new configuration works, retest on the same network, in the same app, and with the same destination to reduce environmental differences. This site covers client selection and configuration; available features depend on the version you installed. For platform-specific instructions, continue to the cross-platform installation and configuration guide.
Not sure how the clients differ? Start with the comparison. Already installed but can’t connect? Go straight to the configuration guide. Matching terminology and setup steps to the symptoms is usually more effective than toggling settings at random.
Choosing a Client & Troubleshooting
Once the basic setup works, explore guides based on the issue you’re facing. Proxy behavior in browsers and terminals, Android background restrictions, and the difference between a client and a core each have their own troubleshooting path. There’s no need to relearn the entire setup for a single problem.
If a browser bypasses the proxy, check its extensions and proxy mode. If a terminal bypasses it, check environment variables and port settings. Learn when to use TUN to capture traffic system-wide.
Learn how v2rayNG uses VpnService, how to add it to the battery optimization allowlist to prevent background disconnections, and how to use per-app proxy settings to route only selected apps.
Compare the three clients by supported platforms, built-in cores, subscription and routing features, and interface. Learn why v2rayN is the top desktop choice and how to choose between the two Android clients.