Choose a GUI client for your platform, then complete subscription import, system proxy, and traffic routing setup in order. This page also explains how Xray and V2Fly cores relate to their clients.
Xray-core
Free to use
Open source
Chinese documentation
CONFIGURATION FLOW
The client interfaces differ, but the core workflow stays the same: choose the program for your operating system, import a valid subscription, confirm which traffic the proxy will handle, then use routing rules to determine the outbound path for each type of connection.
INPUT
Save each subscription URL to a group before updating it. The client reads the configuration and rebuilds the server list. Multiple sources can be managed in separate groups, keeping updates and filtering independent.
CORE
The GUI client handles importing, selection, and status control. The core handles protocol processing, DNS, inbounds, outbounds, and route matching, keeping the two layers clearly separated.
OUTPUT
Routing checks domains, IPs, and processes in order; once a rule matches, the connection is handled by the direct, proxy, or block outbound.
SUBSCRIPTION
Importing a subscription does not mean using a web address directly as a server connection. The client first saves the subscription URL, requests its configuration, and generates selectable server entries only after parsing succeeds. On the first attempt, verify that the URL is complete and place sources in the appropriate groups. After saving, choose “Update Subscription” and wait for the list to refresh. Future updates use the same entry point; there is no need to add servers one by one again.
If the list is still empty after an update, check the system time, network access, and subscription validity first, then review the request result in the client log. This separates URL, network, and parsing issues.
Subscription Groups
└─ Default Group
├─ Add Subscription
├─ Update Subscription
└─ Filter Servers
URL structure:
https://example.invalid/sub?token=xxxxROUTING
Traffic routing answers the question “which outbound should each type of connection use?” The client passes a domain or IP to the rule list, and the core checks conditions in order before selecting direct, proxy, or block. A common approach is to handle private addresses and explicit domain sets first, then define a default rule. A broad condition placed too early can capture traffic unexpectedly, so after editing, check both rule order and the target outbound—not just the rule content.
Built-in policies are useful for getting started quickly; custom policies suit fixed domain, process, or port requirements. After adding a rule, test only the related connections to identify which condition changed the result.
{
"type": "field",
"domain": ["geosite:cn"],
"outboundTag": "direct"
},
{
"type": "field",
"ip": ["geoip:private"],
"outboundTag": "direct"
}SYSTEM PROXY
The system proxy works well for browsers and desktop applications that follow the operating system’s proxy settings. After choosing “Configure system proxy automatically,” the client writes its local listening address to the system settings; clearing the system proxy removes that setting. It does not override each app’s own proxy options, so when an app is not connected, first check whether it uses the system configuration or has a separate proxy address saved.
When troubleshooting, confirm that the client is running, then check the system proxy status and whether the local port matches. Clear the system proxy before quitting the client to prevent the system from pointing to a stopped local listener.
System Proxy Menu
○ Clear system proxy
● Configure system proxy automatically
○ Leave system proxy unchanged
○ PAC mode
Local entry point:
http://127.0.0.1:10809PROXY MODE
Proxy mode determines how application traffic enters the client; routing mode determines how the outbound is selected afterward. They should not be treated as one switch. “Configure system proxy automatically” mainly captures apps that follow system settings; PAC mode uses a script to decide which addresses enter the local proxy; “Leave system proxy unchanged” preserves the current system state for manually configured app proxies or other capture methods.
For everyday use, start with the system proxy and routing rules. When debugging, fix the capture method first, then adjust routes one at a time. Changing both layers together makes diagnosis harder and obscures whether the problem is at the entry point or outbound.
Entry Layer
Application → System Proxy → Local Inbound
Policy Layer
Local Inbound → Route Matching
├─ direct
├─ proxy
└─ blockDNS
DNS settings convert domain names into addresses, directly affecting later IP matching and connection results. When using domain rules, first determine whether resolution is handled by the system or by the core, then choose the appropriate query outbound. If DNS succeeds but the connection fails, inspect the DNS response, domainStrategy, and final route match separately rather than relying only on the browser message.
Complex configurations can assign servers to different domain sets and use rules to send queries through direct or proxy. After changing DNS, clear application and system caches before making a new request so stale records do not hide the configuration change.
{
"dns": {
"servers": [
"localhost",
{
"address": "https+local://1.1.1.1/dns-query",
"domains": ["geosite:geolocation-!cn"]
}
]
}
}TUN
TUN mode receives system network traffic through a virtual network interface, making it suitable for apps that do not read system proxy settings. Before enabling it, allow the client to create the network device and modify the routing table; after disabling it, confirm that the relevant routes have been restored. Compared with a regular system proxy, it covers more traffic but depends more heavily on system permissions, DNS handling, and exclusion rules.
When enabling TUN for the first time, do not add many custom rules at once. Start with a basic configuration and confirm that the network works, then add private-address bypasses, LAN access, and app routing. If connections drop, check permissions, virtual interface status, the routing table, and DNS in that order instead of repeatedly switching servers.
{
"inbounds": [{
"tag": "tun-in",
"protocol": "tun",
"settings": {
"name": "xray-tun",
"mtu": 1500
}
}]
}GROUPS
Subscription groups organize configuration sources; they are not the same as routing outbounds. Saving work, test, and other purpose-specific subscriptions separately lets you update, filter, and select servers independently, reducing duplicate names in one list. Group names should describe the source or purpose. Avoid putting temporary connection states in them because states change while the group structure should remain stable.
Before updating a group, confirm the current selection scope; after the update, filter by region or keyword. Deleting a group also affects its server entries, so check whether the active server comes from that group and prepare a configuration you can switch to.
Subscription Groups
├─ Default Group
│ └─ In Use
├─ Work Configuration
│ └─ Independent Update
└─ Test Configuration
└─ Keyword FilterDIAGNOSIS
When a connection fails, check in this order: subscription content—server selection—core operation—local inbound—system capture—routing outbound—DNS resolution. First confirm that the client log shows no configuration parsing errors, then check that the system is sending traffic to the correct local port. Route matches and remote connection results are meaningful only after the entry point works.
Change one variable at a time—for example, replace the server, switch the routing policy, or disable TUN. Recording log changes after each action prevents temporary network fluctuations from being mistaken for a configuration fix and helps identify stable reproduction conditions.
Troubleshooting Order
1. Is the subscription updated?
2. Is the configuration parsed?
3. Is the core running?
4. Is the local port listening?
5. Is the system proxy working?
6. Do routing and DNS match?CLIENT DOWNLOADS
Use v2rayN on desktop platforms; on Android, choose between v2rayNG and v2flyNG. The download page also explains package types, processor architectures, and system requirements.
DESKTOP
Use the v2rayN GUI client and choose between the desktop edition and the classic WPF edition. After installation, import a subscription first, then configure the system proxy and routing policy.
DESKTOP
Choose the v2rayN Apple Silicon or Intel package for your device’s processor. On first launch, follow the system prompts to allow the app and configure network permissions.
MOBILE
Choose v2rayNG with the Xray core by default; choose v2flyNG when you need the V2Fly core. Most recent devices use arm64; if unsure, check the system architecture information.
DESKTOP
Use the v2rayN desktop client and choose a deb or rpm package for your distribution. On ARM hardware, also select the corresponding arm64 build.
OPEN SOURCE ECOSYSTEM
Clients, cores, protocols, and subscription services belong to different layers. Keeping these concepts separate makes it easier to identify whether an issue lies in installation, configuration, or connectivity.
Project V is an open-source technology ecosystem built around network proxy protocols and composable configurations. Early on, the name V2Ray referred both to the core program and, more broadly, to related protocols, clients, and configuration formats. As the project evolved, V2Fly continued the community-maintained path of v2ray-core, while Xray developed as an independent core while retaining compatibility with common configuration approaches. Both include modules for inbounds, outbounds, routing, DNS, transport, and policies, but their specific features, configuration fields, and release schedules may differ.
A GUI client is not the same as a core. v2rayN, v2rayNG, and v2flyNG provide menus, subscription management, server selection, log viewing, and system capture controls; the core called by the client handles protocol connections and route matching. For interface issues, check the client settings. For configuration parsing, protocol handshakes, or routing behavior, consult the core logs as well.
v2rayN targets Windows, macOS, and Linux desktops, and suits users who need subscription groups, a system proxy, routing rules, and TUN. v2rayNG targets Android and is commonly used with the Xray core, with an interface focused on importing, selecting, starting, and capturing traffic on mobile devices. v2flyNG also targets Android but follows the V2Fly core path, making it useful when specific core behavior or configuration compatibility is required.
All three programs are open-source clients maintained by their communities. Open source makes code, change history, and license terms available for review; it also means each project releases updates according to its maintainers’ plans. A client and its core may use different open-source licenses, so check the license text supplied with each project before using or redistributing it rather than inferring the scope from the product name.
Client updates commonly change the interface, system integration, subscription handling, and core management; core updates are more likely to affect protocol implementation, transport behavior, routing rules, DNS, and lower-level networking. They do not have to be updated on the same day. The download page provides the current client packages, while the client’s built-in core manager lets you view and switch the core components it calls.
Configuration compatibility must also be assessed by layer. Basic inbound, outbound, and routing structures may be similar, but specific protocol parameters or extensions may not transfer directly between cores. Before migrating a configuration, preserve the original and test from the smallest working configuration; once the basic connection works, add DNS, routing, and TUN settings gradually. This makes it clear which field caused a parsing failure or behavioral difference.
COMMON QUESTIONS
These questions cover client selection, subscription updates, the system proxy, and rule order. More complete installation and troubleshooting steps are covered in the tutorials, advanced guides, and FAQ.
Start with v2rayN on Windows, macOS, or Linux. Before downloading, confirm your operating system and processor architecture, then choose the matching package. After installation, follow this order: “Add Subscription—Update List—Select Server—Configure System Proxy.” Avoid changing complex routes before a usable configuration is available.
Compare Clients →Adding the URL only saves it; you must also update the subscription. If the list remains empty, check the URL’s completeness, system time, subscription validity, and logs for network-request or parsing errors. Different causes require different fixes, so repeatedly deleting and reinstalling the client is not recommended.
View Subscription Import Steps →The system proxy affects only apps that read the operating system’s proxy settings. Some applications use an independent network stack, save their own proxy address, or require TUN mode for capture. First confirm that a regular app such as a browser works, then inspect the target app’s network settings rather than mistaking an app-capture issue for a server connection issue.
Troubleshoot the System Proxy →direct sends the connection out directly, proxy sends it through the configured proxy outbound, and block prevents the connection. Rules are usually checked from top to bottom, and the first match is used. When adding a rule, verify both its match content and that it appears before broad default rules.
Read the Traffic Routing Section →LATEST GUIDES
Step-by-step, reproducible procedures for permissions, subscription groups, and DNS paths. Each article focuses on one specific issue, making it easy to enter the appropriate checks based on the symptoms.
Starting with the system block message, this guide covers allowing the app in Privacy & Security, authorizing the network extension, and handling permission requests. It distinguishes between an app that will not launch and one whose network features lack authorization.
Read the Full Article →Learn how to isolate sources when multiple subscriptions coexist, set update schedules, filter servers by regional keywords, and keep group selection aligned with routing policies.
Read the Full Article →Explains why DNS requests may leave the intended path, provides step-by-step checks, and shows how dns outbounds and domainStrategy can redirect DNS traffic.
Read the Full Article →