V2Ray Client · Configuration Reference

V2RayKitv2rayN Downloads and Configuration Reference

Download v2rayN View the Guide

Xray · V2Fly cores / 4 desktop and mobile platforms

Choose your OS and explore open-source clients, from subscription imports to config.json field references. Check local ports, outbound protocols, and routing rules as you go.

config.jsonVLESS / VMessRouting & DNS

The configuration workbench shows selected fields for illustration. Authentication, server ports, and the direct outbound definition are omitted, so this is not a complete, runnable configuration.

Project V / Open-source proxy ecosystem Xray · V2Fly / Core families JSON / Configuration structure 4 / Desktop and mobile platforms

CONFIGURATION / FIELD INDEX

Find settings by configuration section

The client interface generates the configuration; the core uses it to handle connections. First understand where traffic enters, how outbounds are selected, and where DNS resolution happens, then edit the relevant fields. You don't need to expand every setting at once.

{
  "inbounds": [{
    "listen": "127.0.0.1",
    "port": 10808,
    "protocol": "socks",
    "settings": { "udp": true }
  }]
}

Inbound address and local port

Inbounds define how apps pass connections to the core. For local use, the listen address is usually the loopback address; the port must match the one configured in your browser or app. This example uses a SOCKS inbound, so don't treat its port as an HTTP proxy port. If startup fails, first check whether the port is already in use, then confirm that the client generated an inbound with the expected name. Checking inbounds can distinguish “the app isn't sending traffic” from “the core failed to listen”—a distinction you can't make by looking only at the system proxy toggle. Before changing the listen scope, consider which devices should be able to access it.

View the configuration reference →

DOWNLOADS / PLATFORM DOWNLOADS

Choose a client download for your platform

Use v2rayN on desktop. For Android, start with v2rayNG; consider v2flyNG if you need a V2Fly core. Downloads and configuration guides are organized separately so you can choose the right build for your system architecture before following the setup steps.

Windows

v2rayNDesktop / WPF

The cross-platform edition offers a modern interface, while the WPF edition keeps the classic desktop workflow. Choose based on your preferences, then check the installation requirements. If you already have a configuration, back up subscription groups, custom routing rules, and local ports first. Don't overwrite the entire program directory with a different edition.

After the first launch, check the local listening port in Settings before deciding whether to enable the system proxy. The app can open normally even if the core hasn't started. If you see a runtime requirements notice, install the components listed on the download page before importing nodes.

Go to Downloads

macOS

v2rayNApple Silicon / Intel

Check your chip details in About This Mac and choose the download for the matching architecture. System proxy settings and client routing operate at different layers: the former determines whether an app hands connections to the client; the latter selects an outbound for connections the client receives.

Pay attention to system prompts on first launch, and avoid changing several permissions at once while troubleshooting. If a browser works but other apps still connect directly, check whether those apps follow the system proxy or have their own network settings.

Go to Downloads

Android

v2rayNG / Xrayv2flyNG / V2Fly

Check the arm64 and universal builds of v2rayNG first. If you're unsure of your device's architecture, use the system information to decide. v2flyNG is an alternative using a different core family; whether it works with your nodes depends on the protocols and extended parameters, not just the app name.

You'll need to approve the system VPN connection when connecting. App-level routing, background activity limits, and battery management can all affect how the app behaves. If it connects in the foreground but drops when the screen locks, check the system's background restrictions before importing the same subscription again.

Go to Downloads

Linux

v2rayNdeb / rpm

Choose deb or rpm based on your distribution's package system, then select x64 or arm64. Desktop environments vary in system proxy support. After installation, check the core's status, desktop proxy settings, and the network configuration of the app you want to use.

Port conflicts, insufficient permissions, and missing dependencies are separate issues; use the specific error in the logs to guide your next step. If a graphical client and another proxy app are running at the same time, check which one is listening on the target port so you don't mistake another program's response for a working configuration.

Go to Downloads

Browse all clients →

QUICKSTART / SETUP STEPS

From subscription import to connection testing

For the initial setup, establish one connection path you can explain. Import first, choose how to route traffic next, and verify the result last. Changing one thing at a time makes issues easier to trace than enabling several advanced options at once.

01 / IMPORT

Create a group and import nodes

Add a subscription URL in the client's subscription manager, give the group a recognizable name, and update it. If you have a single share link, import it from the clipboard or scan its QR code. These methods work differently: updating a subscription fetches the group contents again, while a single share link usually creates just one local entry.

After importing, open the node editor and check the protocol, server address, port, and transport settings. A subscription name isn't a connection parameter, and a node's display name doesn't confirm that its settings are complete. If the format isn't recognized, check for extra spaces, explanatory text, or a webpage URL in the copied content, then confirm that the client supports the format.

Subscription URLs may contain access credentials, so don't post them in public screenshots or forums. For troubleshooting, you can share the protocol type and error message while keeping authentication details private. A failed subscription update and a failed node connection happen at different stages: check how the subscription is fetched first instead of changing the outbound protocol.

02 / ROUTE TRAFFIC

Choose a system proxy and routing mode

Select a node, then choose how traffic enters the client. On desktop, start with the system proxy; on Android, approve the VPN connection when prompted. The system proxy affects only apps that follow it. Routing applies to connections that have already reached the core. They aren't interchangeable.

For first-time use, keep the client's default routing rules and make sure local network resources still work before adding rules for specific domains. Don't enable LAN listening just to get one app working, and don't assume every routing issue is caused by the node. First check whether the app is sending requests to the client; this narrows down the cause.

If you change a local port, update the settings of any apps that use it. HTTP and SOCKS are different proxy interfaces, even when they share the same listen address. If the client offers a mixed port, follow the option's own description rather than copying a port number from another device.

03 / VERIFY

Check logs and app behavior layer by layer

After starting the connection, check that the core is running, then send a request from the target app. A node test reflects only its specific test method; it can't replace testing with the actual app. Check these separately: “core started successfully,” “app request reached the client,” “rule selected the expected outbound,” and “remote connection completed.”

For certificate errors, check the system time, server name, and transport security settings. If the address is already in use, revisit the local port settings. Keep a backup of the original parameters while troubleshooting, and note each change alongside what happened. This gives you a clear basis for restoring settings instead of losing track of the original configuration after repeated attempts.

Once the connection works as expected, consider enabling auto-update, launch at startup, or app-level routing. Repeat the same checks after switching networks, restarting the device, or resuming from a locked screen. If an issue occurs in only one app, check its DNS and proxy settings before changing the global configuration.

Read the full guide →

PROJECT V / CORES AND CLIENTS

Open-source ecosystem and configuration boundaries

V2Ray, V2Fly, Xray, and graphical clients aren't all the same kind of software. Knowing how they differ helps you identify which component provides a feature, where an error originates, and what to preserve when moving a configuration.

Project V and its core families

Project V is an open-source ecosystem built around network proxy components, with V2Ray as one of its widely used core implementations. V2Fly continues community development of V2Ray, while Xray has developed its own core from related code. They share some configuration concepts, but protocol extensions, field support, and defaults can differ as each project evolves. Treating them as the same core can lead you to overlook compatibility when importing configurations or consulting documentation.

The core handles protocols, establishes transports, matches routing rules, and resolves domains. A graphical client organizes these capabilities into node lists, subscription groups, and settings screens. An option in the interface doesn't mean every available core interprets it the same way. When troubleshooting compatibility, note which client and core you're using, then check the documentation for the relevant fields. Don't infer the entire configuration from the beginning of a share link.

What the three clients do

v2rayN is an open-source graphical client for desktop systems, with node imports, subscription updates, routing management, and system proxy controls. It makes common settings easy to manage through the interface while leaving room for custom configurations. After switching cores or changing node types, recheck the generated transport and security settings. Saving a node entry doesn't mean the remote server supports its features.

v2rayNG is an open-source Android client that uses the Xray core; v2flyNG uses the V2Fly core as an alternative compatibility option. The apps may have similar interfaces, but that doesn't mean all extended fields are interchangeable. Choose based on your configuration requirements, then consider subscription format support, app-level routing, and background behavior. If you use the same subscription on desktop and mobile, configure local listening and system-level traffic handling separately on each device.

Open-source licenses and feature support

The V2Fly core is licensed under MIT, and the Xray core under MPL 2.0; clients and their dependencies have their own applicable licenses. Open source allows you to read, use, and modify code within the terms of its license, but doesn't mean every component follows the same release schedule. License information helps explain the conditions for using and distributing software; it doesn't replace checking specific features, runtime requirements, or configuration details.

A client is a connection tool; it doesn't provide a usable remote service on its own. You must supply the server address, authentication details, and related parameters. Example addresses on this page are for explaining fields, and routing snippets show matching logic only. When using examples to learn, distinguish structural examples from values that must be replaced with parameters from a service you already have. Don't mistake a demonstration configuration for a complete node.

Updates and configuration maintenance

The client interface, core, and routing data files can change independently. After a client update, some fields may be generated again; after a rules data update, the domains or addresses included in a category may change. Keep track of where configurations come from and which parts you've customized, and add clear notes to important rules. If behavior changes, compare the generated configuration and logs before deciding whether to revert a setting.

Subscriptions are useful for centrally updating remote parameters; backups should cover local settings. They aren't interchangeable: subscriptions may not include system proxy preferences, app-routing lists, or manually added routing rules. When moving between devices, keep reusable node details separate from device-specific listening, permissions, and startup settings. V2RayKit's configuration reference is organized by field, while its tutorials follow the setup process—choose whichever suits the issue you're working on.

NOTES / PRACTICAL GUIDES

Configuration guides and troubleshooting

Find guidance for specific issues, from first-time installation and rule priority to certificate errors. Articles complement the configuration reference; before making changes, check which core you're using and what settings the client controls.

Browse all articles →

Download clients