Client and Configuration Docs · Project V Ecosystem Reference
Start by choosing a client, then work through subscription import, split routing, and configuration troubleshooting. The guide covers desktop and Android clients and explains when to use the Xray or V2Fly core.
Paste a subscription URL to import it into v2rayNCLIENT WORKBENCH
Most day-to-day actions live in five places: subscription groups, routing mode, system proxy, core selection, and the log window. Identify which settings layer you are working in before changing a parameter; this makes problems easier to isolate than repeatedly reimporting configurations.
A subscription is a set of configuration entry points maintained by a service. Only after the client updates it are its nodes, protocols, and transport parameters written locally. In practice, create a clearly named group first, paste the complete subscription URL, and run an update. If the update fails, do not keep clicking; first determine whether the message indicates a network access failure, an invalid response format, or an expired URL. Groups preserve source boundaries: subscriptions do not overwrite one another, and disabling one group does not affect the others. Manually added nodes are useful for temporary testing, but should not be mixed with long-term subscriptions in the same group.
Split routing is not a simple toggle; it is an ordered set of matching rules. A client can route requests to a proxy, direct connection, or blocked exit based on domains, IPs, ports, or protocol types. More specific rules should come first, while broad fallback rules belong at the end. After making changes, also check how domains are resolved: IP-only rules may never match without an appropriate domain strategy. For everyday configurations, start with the client's stable built-in rule set and add custom rules only when needed; this is easier to maintain and troubleshoot than importing a large set from unknown sources.
A successfully started core only means that the local proxy port is listening. Whether applications use that port depends on system proxy settings or each application's own proxy options. If a browser works but a standalone program cannot connect, check whether that program reads the system proxy. If no applications can connect, then check core logs, the local port, and the current node. Allowing LAN connections changes the listening scope; enable it only when other devices on the same network genuinely need access, and review the operating system firewall rules as well. Keeping these two layers separate prevents a disabled system proxy from being mistaken for a node or protocol configuration error.
v2rayN, v2rayNG, and v2flyNG provide graphical controls for subscriptions, nodes, and system proxies, but the underlying core is what reads the configuration and establishes connections. Xray and V2Fly share a common ecosystem background, yet their maintenance directions, protocol extensions, and support for some fields are not identical. Choose a core based on the node configuration requirements, not just its name. If a configuration includes specific flow-control, transport, or security fields, the client must use a core that supports them; for standard configurations, focus on whether the client-core combination is stable. After switching cores, restart the connection and check the startup log to confirm that the intended core actually loaded.
loading config: config.json
routing: domainStrategy=IPIfNonMatch
inbound: socks / http
outbound: proxy / directConfiguration parsing failures, occupied ports, DNS resolution problems, and TLS handshake failures leave different clues in the logs. Begin troubleshooting with a completely fresh start, find the earliest line containing error or failed, and use the surrounding configuration fields to determine the cause. JSON syntax errors usually identify a line and column; an occupied port produces a listen failure; certificate and handshake issues call for checks of system time, serverName, SNI, and transport parameters. A flood of later repeated messages is often just a cascade from the first failure. Preserve the original error text and change one item at a time; this makes it easier to tell what restored the connection than changing the node, DNS, routing, and core simultaneously.
PLATFORM ENTRY
Platform pages bring together compatible clients, installer formats, and architecture options. The homepage does not distribute files directly; open the relevant platform page and choose an installer based on the device type.
For desktop systems, start with v2rayN. The modern desktop interface suits standard installations, while the classic WPF version fits users who prefer a traditional layout. Both versions can manage subscriptions, routing, and the system proxy.
Go to DownloadsUse the v2rayN desktop client on macOS. Before downloading, check the processor type in System Information, then choose the Apple Silicon or Intel installer that matches it to avoid an architecture mismatch.
Go to DownloadsOn Android, choose between v2rayNG and v2flyNG. The former follows the Xray core route, while the latter follows the V2Fly core route. Most recent devices can use arm64; if the architecture is unknown, use the universal package.
Go to DownloadsOn Linux desktops, use v2rayN. Choose deb or rpm according to your distribution's package system, and select x64 or arm64 for the processor architecture. After installation, system proxy settings still need to be configured in the desktop session.
Go to DownloadsOPEN SOURCE ECOSYSTEM
Clients, cores, protocols, and subscriptions are different layers. Understanding their roles helps determine whether a problem belongs to the graphical interface, the configuration file, or the underlying protocol implementation.
Project V developed a configuration-driven ecosystem of network tools. The early V2Ray project established core structures for inbound and outbound connections, routing, DNS, policies, and transport layers. Community maintenance later developed into two widely used core routes: V2Fly and Xray. They share many foundational concepts, such as describing listeners, remote exits, and matching rules in JSON, but differ in their priorities for new protocols, transport features, field extensions, and release evolution.
The term “V2Ray client” usually refers to a graphical tool for managing these cores and configurations, not to one specific program. v2rayN handles subscriptions, nodes, routing, the system proxy, and core startup on desktop systems; v2rayNG and v2flyNG handle configuration management on Android. A graphical client converts user actions into a configuration the core can read, then starts a local listening port. Connection success ultimately depends on the subscription contents, protocol parameters, transport settings, DNS resolution, system time, and local network conditions together.
Open source allows protocol implementations, configuration structures, and client behavior to be discussed publicly and improved continuously, but projects do not release updates on the same schedule. A client upgrade may introduce a new interface or configuration-generation logic, while a core upgrade may add protocol fields, fix compatibility issues, or change defaults. Before updating, read the change notes, keep a working configuration, and confirm whether the current subscription depends on a specific core feature. Stable use does not require chasing every release; upgrading only when there is a clear compatibility need, bug fix, or system-support change usually keeps variables under control.
Open-source licenses also define the boundaries for copying, modifying, and redistributing code. For most users, the practical concerns are whether the project name matches the package source, which core the client actually invokes, and whether the configuration contains fields supported by that core. This site explains client operations and core concepts separately: introductory guides focus on visible controls, the configuration reference explains each JSON section, the glossary covers protocol and networking fundamentals, and troubleshooting articles trace log symptoms back to specific settings.
Covers Windows, macOS, and Linux, with one place to manage subscription groups, node selection, the system proxy, routing rules, and core settings. Best suited to desktop environments where multiple configurations need graphical management.
Uses the Xray core route and provides subscription updates, configuration imports, routing settings, and connection logs. Configurations containing specific Xray extension fields generally work best with this combination.
Uses the V2Fly core route and follows a workflow similar to common subscription setups. Choose based on configuration requirements and core compatibility; there is no need to install both clients.
First confirm that the URL is complete and still accessible, then check whether the response uses a subscription format the client can recognize. Handle network errors, expired URLs, and format errors separately instead of deleting all local configurations.
View the Subscription Import Steps →Whether a domain rule matches can depend on where resolution occurs and which domain strategy is active. Changing only DNS or only routing can hide the real cause; check the requested domain, resolution result, and final exit together.
View DNS and Routing Configuration →Check which protocol, flow-control, and transport fields the subscription or manual configuration uses, then choose a core that can parse them completely. Basic configurations are usually supported by both; verify extension features individually.
View Core and Protocol Terms →Logs can distinguish configuration parsing, port listening, DNS, connection timeouts, and handshake errors. Change one variable at a time and record the first error from a completely fresh start to keep the troubleshooting path clear.
View Configuration Troubleshooting Reference →LATEST NOTES
Reusable checklists for core startup, protocol fundamentals, and TLS errors. Configuration snippets explain relationships between fields; use your own subscription or service configuration as the source of truth for actual parameters.
Start with the client's log window and interpret typical errors across four common causes: JSON syntax errors, occupied ports, misspelled fields, and missing protocol parameters. Follow the step-by-step fixes and restart checks to confirm the result.
Read the Full Article →Explains REALITY handshake characteristics and how XTLS Vision reduces redundant encryption overhead through flow-control design, including the key fields that must align across the client, core, and node configuration.
Read the Full Article →For common messages such as certificate invalid and handshake failed, follow a check sequence covering system time drift, serverName mismatches, and certificate-chain problems.
Read the Full Article →