Static interface illustration. Menus and options may move as the client is updated.
Proxy Settings: Know the Four Options
Routing, system proxy, core type, and subscription setup each handle a different part of the process. Identify which layer is causing the issue before changing its settings.
Routing
Routing rules determine whether connections passed to the core go direct, through a proxy, or get blocked. For everyday use, start by learning the “Bypass mainland China” preset: connections matching mainland Chinese domains or IP addresses go direct, while others follow the rules. “Global” sends all connections handled by that route through the proxy. Neither option replaces the system proxy or means every app is covered. After switching, test the same site again and avoid changing DNS and servers at the same time. With custom rules, check their order: an earlier match can prevent later rules from taking effect.
v2rayN manages the interface and configuration; the core handles the actual connections. Choose a core that supports the server’s protocol, transport, and related parameters—not just one with a familiar name. Xray and sing-box are separate implementations with different configuration fields and support. Start with the client’s compatible defaults, then check the logs if a field isn’t supported. V2Fly is another core family and should not be confused with sing-box. After changing cores, verify that the server starts successfully rather than relying on its continued presence in the list.
Core Types · Switching Explained
Check the configuration against Xray’s protocol support and logs; parameters such as REALITY must match the server.
Check sing-box’s configuration format and compatibility; don’t reuse a full configuration intended for another core.
On desktop, selecting “Set system proxy automatically” adds the local proxy endpoint to the operating system’s proxy settings for apps that follow them. “Clear system proxy” removes that setting; “Leave system proxy unchanged” keeps its current state—it does not disconnect the proxy. If a browser works but another app does not, check whether that app uses the system proxy or has its own proxy address configured. System proxy and TUN are different ways to route traffic. For your first setup, start with the system proxy and explore other modes only after confirming the basic connection works.
The plus menu in the top-right corner of v2rayNG offers “Import from clipboard” and “Scan QR code.” These options are commonly used to add a single server’s share link; don’t treat a share link as a subscription that can be refreshed regularly. For a subscription URL, open “Subscription groups,” enter a remark and the address, save, then update the subscription. After importing, select a configuration and start the connection. Approve the system VPN prompt the first time. QR codes and clipboard contents may include access credentials, so hide addresses, identifiers, keys, and other sensitive fields before sharing screenshots.
Check your operating system and processor architecture first, then choose the matching package. Use v2rayN on desktop; on Android, choose v2rayNG or v2flyNG based on the core you need.
Choose v2rayN. The download page distinguishes the Desktop edition from the classic WPF edition: Desktop uses a cross-platform interface, while WPF retains the classic desktop workflow. Check the listed operating system and runtime requirements rather than relying on the filename alone. Extract the archive fully to a writable folder before running it; don’t launch the app from inside the archive.
Choose v2rayN and check your chip under “About This Mac.” Apple Silicon uses arm64; Intel uses x64. If macOS shows a security warning the first time you open the app, verify the download source and installation steps, then use the option provided by the system. Don’t disable system-wide security protections just to run the client.
Start with v2rayNG, which uses the Xray core; choose v2flyNG if you need the V2Fly core. For most modern devices, check whether the architecture is arm64. If you’re unsure, see the universal-build notes on the download page. Starting a connection requires system VPN permission. If another VPN is already connected, resolve the conflict first, then check the server and per-app proxy settings.
Choose the v2rayN deb or rpm package that matches your x64 or arm64 architecture. deb packages are commonly used on Debian and Ubuntu; rpm packages are common on Fedora and similar distributions. Desktop environments differ in how they support system proxy settings, so a successful installation doesn’t guarantee apps are using the proxy. If needed, enter the local proxy endpoint in the app’s own network settings.
Installing the client is just the first step. You also need a valid configuration, a working proxy endpoint, and the right way to route traffic. The steps below focus on desktop; mobile instructions are covered separately.
Add and Update a Subscription
In v2rayN, open “Subscription Group Settings,” add a group, enter a recognizable remark, and paste the full subscription URL into “Address (URL).” For your first setup, keep the default update options, save, then update the group’s subscription. A subscription URL typically returns a set of configurations. It serves a different purpose from a single-server share link beginning with vmess:// or vless://; don’t interchange their import options.
In v2rayNG, manage subscriptions from “Subscription groups.” If the list is still empty after an update, check the logs for download or parsing errors. Make sure the URL was copied with all query parameters and isn’t a link to an information page. Subscriptions are sensitive: when troubleshooting, note only the error type and never post the full URL publicly.
Select a Server and Routing Mode
After updating, select a configuration in the intended group and set it as the active server. First confirm that the current core can recognize it, then choose a routing preset for everyday use. Beginners can start by learning what “Bypass mainland China” does, and briefly switch to “Global” to compare routing behavior if needed. Change one setting at a time and keep the test conditions reproducible.
Importing a configuration doesn’t guarantee the server is reachable, and the client can’t create connection details for you. A timeout could be caused by the service, address, port, or current network; one test alone can’t identify the cause. If the logs say a protocol parameter isn’t supported, check the core and configuration instead of repeatedly updating the same subscription.
Enable the Proxy and Test It
On desktop, select “Set system proxy automatically,” then use a browser that follows the system proxy to visit the target site while checking the client logs. On Android, select a configuration, start the connection, and approve the system VPN prompt. When testing, distinguish DNS resolution failures, connection timeouts, and certificate errors; each calls for different checks.
Then test a site that normally works to make sure routing hasn’t disrupted your usual connection. Before closing the desktop client, clear the system proxy so it doesn’t keep pointing to a local port that is no longer running. If the browser works but other apps don’t, check their proxy settings first. If all connections fail, check the core startup logs and local port.
Projects with similar names don’t necessarily do the same job. Knowing what each layer does helps avoid mistakes when choosing, updating, and troubleshooting software.
Project V and Core Families
Project V provides context for understanding the V2Ray ecosystem. The V2Ray core provides foundational capabilities such as protocol handling, inbound and outbound connections, and routing. V2Fly continues community maintenance of related cores, while Xray is another implementation that grew out of this technical ecosystem. They share a background but have evolved differently and use different configurations.
VMess, VLESS, and Trojan are protocol-related names; WebSocket and gRPC describe transport methods; REALITY involves connection security and handshaking. These terms belong to different layers and aren’t interchangeable options. Choose the combination supported by the server, then confirm the client’s core can handle it.
Three GUI Clients
v2rayN gives desktop users an interface for managing subscriptions, selecting configurations, and setting up the system proxy and routing. v2rayNG is for Android and uses the Xray core. v2flyNG is also for Android, offering an alternative for users who need the V2Fly core. Similar interfaces don’t guarantee the same parameter support—that depends on the core each client includes.
All three clients are open-source projects released under the GPL-3.0 license. Open-source licenses set the terms for using and distributing code; they don’t mean every dependency uses the same license. When following configuration instructions, check both the client and core names. Menu locations in one client may not match another.
Subscriptions and Connection Services
The client stores and runs configurations, subscriptions provide configurations, and servers provide the actual connection endpoint. Each has a different role. This site offers client selection and setup instructions; it does not provide subscription URLs or maintain servers. If the list is empty after installation, first obtain a configuration from a legitimate source rather than looking for a subscription option in the system proxy settings.
Updating a subscription fetches the latest content published by the server, and may overwrite manually edited servers. Before keeping a test configuration, check how groups and copying work in your client. A subscription may also stop working because its URL changed or access was revoked; reinstalling the client repeatedly won’t fix every issue.
Update and Troubleshooting Order
Updating the client, core, and subscription are three separate tasks. A client update may change the interface and how configurations are generated; a core update affects connection capabilities; a subscription update changes the configurations themselves. If compatibility issues arise, note the error and steps taken, then decide which layer needs an update. Avoid making several changes at once, or the issue may become impossible to reproduce.
Before updating, keep any groups and custom rules you need. Afterward, test a configuration that worked before. If it fails, check in order: whether the core starts, whether the server is reachable, whether DNS works, and whether the app uses the proxy. Before sharing diagnostics, remove subscription URLs, user IDs, keys, personal paths, and other sensitive details.
Configuration Guides: Browse by Topic
These three recent guides cover first-time installation, DNS routing, and share links. Get a basic connection working first, then explore additional settings as needed.
Covers first launch, runtime requirements, and core selection. First make sure the app starts normally, then configure the system proxy to avoid confusing installation issues with connection problems.
Explains the roles of local and remote resolution, and the uses and limitations of DoH and FakeDNS. Adjust the relevant settings based on where the failure occurs instead of replacing everything at once.
Compare link contents and import options to understand the difference between a single configuration and an updatable subscription. Learn when to import from the clipboard or a QR code, and when to use a subscription for centralized management.