Get started with GUI clients, understand inbounds, outbounds and routing through real JSON configurations, and follow step-by-step guides.
Import subscriptionsRoute trafficConfigure DNS
config.jsonConfiguration index
{
log"log": {
"loglevel": "warning"
},
inbounds"inbounds": [],
outbounds"outbounds": [],
routing"routing": {
"domainStrategy":
"IPIfNonMatch",
"rules": []
},
dns"dns": {},
policy"policy": {}
}
Settingsv2rayN
GeneralRoutingDNS
Local listening port10808
Enable UDP
Enable traffic sniffing sniffing
Allow connections from LAN
Domain strategyIPIfNonMatch ▾
Routing modeGlobalBypass mainland China
CancelOK
GUI client
v2rayN
Core family
Xray · V2Fly
Configuration format
JSON
Maintenance
Open-source community
CONFIGURATION / Configuration sections
From GUI options to JSON keys
First identify where requests enter, what conditions they match, and which outbound handles them. Then adjust settings with a clear understanding of each layer.
v2rayN / v2rayNG / v2flyNG
The local port is the app’s entry point
An inbound accepts requests from apps; it is not the address of a remote server. Desktop apps can connect to the core through a local SOCKS listener, or use the system proxy when supported. This example listens only on the loopback address, making it suitable for local use. The port must match the client and app settings. Enabling UDP allows the listener to handle relevant requests, but successful forwarding also depends on the app, outbound and server. GUI clients generate most inbound fields, unlike a fully hand-maintained config. Before editing manually, check whether the client will regenerate the config.
Routing happens after a request enters the core; whether an app uses the system proxy is a separate matter. Rules are generally checked in order, and a match is sent to the outbound with the specified tag. This example sends private IP addresses to a direct outbound to illustrate the basics of LAN access; it is not a complete geographic routing setup. Built-in client modes combine rules with data files, so the mode name alone cannot tell you where every domain will go. Presets are an easier starting point than writing every rule by hand. For precise routing, check the tags, match conditions and rule order.
Understand DNS settings in the context of the request entry point. An app may resolve a domain itself and pass the resulting address to the core, or send the domain name for the core to resolve during routing or connection setup. This example uses a local resolver to show the configuration structure; it is not necessarily the best choice for every environment. Before changing DNS servers, check the query path, network reachability and routing policy, and avoid changing several variables at once. Core-level DNS has a clearer scope than changing system DNS alone, but it does not automatically handle every app’s queries. Browser built-in DNS must be checked separately.
Logs can show which layer a request failed at, but a single error does not explain every connection issue. Reproduce the problem once, then check entries around that time for DNS, connection or handshake errors. This example sets the log level to warning; during troubleshooting, increase the detail if the client supports it, then restore the original level. Testing one error type at a time preserves useful findings better than repeatedly replacing the entire configuration. Before sharing logs, remove subscription URLs, identity fields and destinations. A config that passes syntax checks does not guarantee that the remote service is reachable.
Choose v2rayN for desktop systems. On Android, start with v2rayNG, then consider v2flyNG if its core better fits your compatibility needs. Check your operating system and processor architecture before choosing an installer on the downloads page.
v2rayN offers a desktop edition and a classic WPF edition. The desktop edition uses a cross-platform interface, while the WPF edition suits users who prefer the classic layout. The interface frameworks differ, but actual features depend on the release notes and selected core—not on the interface alone.
If you already have a configuration, preserve your subscription groups, routing and DNS settings before switching program directories. For a first setup, choose one interface and use it to import and connect. Running two client instances at once can cause port conflicts or repeated changes to the system proxy.
v2rayN provides separate downloads for Apple Silicon and Intel. Check your chip in About This Mac, then choose the matching installer. The cross-platform interface follows similar configuration concepts, but permissions, menu locations and system proxy controls may differ from those on other desktop systems.
After launch, make sure the app can access its configuration directory before importing a subscription. If the system proxy is enabled but an app still does not use it, check that app’s network settings. Tools that ignore the system proxy may need the local address and port entered separately, as described in their documentation.
v2rayNG uses the Xray core and suits setups that need its protocol and transport support; v2flyNG is an alternative based on the V2Fly core. For most newer devices, check the arm64 download first; if you are unsure of the architecture, look into the universal package. Confirm compatibility on the download page and against your device specifications.
The first time you connect, the system asks for permission to create a VPN interface. This is how the client receives device traffic; it does not mean the remote server is reachable. Background restrictions, per-app routing and other apps using the same system interface can all affect connectivity.
v2rayN offers deb and rpm packages for x64 and arm64. Debian and Ubuntu users generally choose deb; Fedora users generally choose rpm. The package format must suit your system’s package manager, and the processor architecture must match your device.
Desktop environments do not all handle the system proxy in the same way. If a browser works but terminal tools do not, check how each app connects before changing the remote node. Verify startup settings, write access to the configuration directory and local port availability separately.
Before you begin, get a working subscription URL or the details for an individual node. The client stores configuration and starts the core; the installer itself does not provide remote connection details. These steps focus on the GUI: establish a minimal working setup first, then add routing rules and custom settings.
01 / IMPORT
Import a subscription and check its details
In v2rayN, add the URL to a subscription group, give it a recognizable name and update the group. On Android, save a subscription group before updating the node list. A single share link can be imported from the clipboard, but it is not the same as a subscription URL. Using the wrong import option can cause parsing errors.
Once entries appear, check that the protocol, server address, port, transport and security settings are intact. A node name is only a display label, not a substitute for checking its parameters. Subscription updates may overwrite manual edits. For changes you need to keep, use a separate configuration or the client’s override feature, and note where the changes came from.
Subscription URLs may contain credentials, so never include the full URL in a troubleshooting screenshot. If the list is empty, first check whether the URL is unreachable, the response format is unsupported or parsing failed. Then decide whether to import the subscription again.
02 / ROUTE
Choose a node and distinguish proxy settings from routing
Set the active node, then choose the system proxy option and routing mode. The system proxy determines which apps that follow system settings send requests to the client. The routing mode determines whether requests entering the core use a direct or proxy outbound. Both use the word “proxy,” but they operate at different layers.
For an initial test, use a setup with few rules and a clear traffic path. If you need LAN access, check that private-address rules take priority. “Bypass mainland China” modes typically rely on domain and IP rule data; the mode name alone does not guarantee that every app will route traffic as expected. After switching modes, establish a new connection and check what actually happens.
On Android, also check the scope of per-app proxying: “proxy only selected apps” and “bypass selected apps” mean opposite things. During troubleshooting, change one setting at a time and keep the last verified working node. This helps distinguish an entry-point issue from a node issue.
03 / VERIFY
Reconnect and test each layer
After starting the connection, check that the client does not immediately report a configuration error, then send a fresh request from the target app. A node test result reflects only that specific test method; it does not guarantee that web pages, file transfers or real-time communication will work. Judge the result using the app and destination you actually need.
If the connection fails, check the local entry point, DNS resolution, remote connection and protocol handshake—in that order. If an app never reaches the local entry point, changing remote settings repeatedly is unlikely to help. If the request reaches the remote server but the handshake fails, check the protocol fields, security parameters and system time. Log error types can help distinguish these cases.
After verifying the connection, add custom routing, background operation and startup settings as needed. Before closing the client, disable any system proxy you no longer use so apps do not keep pointing to an inactive local port. The full tutorial explains where to find each setting and how to handle common variations.
PROJECT V / Cores and clients
Open-source ecosystem and configuration boundaries
The client manages configuration; the core handles connections. Projects share technical history, but protocol support, field meanings and release schedules must be checked individually.
Project V, V2Fly and Xray
Project V is a useful starting point for understanding V2Ray’s technical background. V2Ray divides proxy functions into modules such as inbounds, outbounds, transports and routing, so the local app entry point and remote connection method can be configured separately. V2Fly continues community maintenance of V2Ray; Xray builds on related technical foundations with its own implementation and extensions. They share some configuration concepts, but not every field or protocol combination is interchangeable.
When consulting documentation, first confirm which core it covers, then check whether the client can generate the corresponding configuration. For example, REALITY is part of a security and transport setup, not simply a standalone option equivalent to every proxy protocol. A client may expose a setting for it, but a connection still requires matching remote parameters and a compatible core.
A GUI is not the core itself
v2rayN manages desktop node lists, subscriptions, routing presets and core launching. On Android, v2rayNG works with the system VPN interface and Xray core to handle traffic; v2flyNG offers another configuration path based on V2Fly. All three clients are open source, but similar names do not guarantee similar interfaces, configuration generation or compatibility.
A successful save in the interface only means the settings were recorded. The core must still read and parse the generated configuration, then negotiate with the remote server. Custom configuration and regular node modes may follow different generation paths, so direct edits to generated files may not persist. Before editing a file, check whether it is the source configuration or a runtime-generated output.
How to read the configuration guides
If you just need to connect, start with the quick-start guide. To understand terms such as “node,” “subscription” and “transport,” consult the glossary. For custom behavior, work through the JSON guide by configuration section. Code examples explain individual structures; a snippet without outbound details is not a complete connection configuration. When combining snippets, check tag references, array nesting and rule order.
Once the basic connection works, consult articles for specific questions. Choose an installer based on your system and interface framework; investigate speed issues by looking at the route and local entry point; choose protocols based on remote configuration and core support. Separating these questions helps identify which settings are worth changing.
Compare the cross-platform desktop and classic WPF editions by interface framework, system support and usability. Check which systems each installer supports before deciding whether to migrate an existing configuration. Treat interface differences separately from core capabilities.
Break speed issues into three layers: node load, connection route and local settings. Use DNS, sniffing, MTU and routing rules to investigate. Start with repeatable test conditions, then compare results one change at a time.
Compare protocols by encryption, handshake, transport options and client support. Understand how TLS and REALITY fit into proxy protocol setups, then choose based on actual compatibility rather than names alone.
To find a configuration key, go straight to the JSON guide. To understand the differences between subscriptions, nodes and cores, start with the glossary.