CLIENT / Client and Core Setup

Xray Official Site · v2rayN
Client Downloads and Core Setup

Download v2rayN View the guide

Start with an open-source client, import a subscription, then configure routing for your needs.

Xray / V2Fly VMess / VLESS Trojan / Shadowsocks
PLATFORMS
Windows Android macOS Linux

This interface illustrates the settings layout. Menu names, listening ports, and available options may vary by client configuration.

SECTION 01 / SYSTEM PROFILE

Client configuration. Trace traffic through the interface.

The graphical client manages connection parameters; the core handles traffic. Importing a link is only the first step: protocol fields define how to connect to the server, proxy mode determines whether app traffic reaches the client, and routing rules decide which outbound handles that traffic. Check these layers separately to pinpoint issues more easily than by changing several settings at once.

Protocols, transports, and core layers

v2rayN manages server settings through a graphical interface and passes them to the selected core. VMess, VLESS, Trojan, and Shadowsocks use different fields; transport and TLS settings must also match the server. After importing a configuration, check the protocol, address, port, and security settings, then confirm that the core supports that combination. A graphical manager makes it easier to save multiple connections than editing an entire configuration by hand, but the fields still have to work together. REALITY is a security-related transport configuration, not a standalone proxy protocol to swap in arbitrarily.

inboundsoutboundsstreamSettings

SECTION 02 / PLATFORM DOWNLOADS

Client downloads. Choose an OS, then an architecture.

Choose an installation package that matches your device. Desktop interface type, processor architecture, and package format are three separate choices; file size alone is not a reliable guide. The download page lists all client options and selection notes. Platform links on this page go directly to the relevant section.

Windows

v2rayN is the recommended desktop client. Desktop uses a modern cross-platform interface, while the classic WPF edition retains the traditional desktop layout. Choose whichever suits your workflow. The interfaces may differ, but the basic steps for importing a connection, selecting a server, and configuring the system proxy are similar.

Before installing, check your OS and the architecture supported by the package. On first launch, make sure the core runs correctly. If the window opens but connections fail, check the logs before concluding that the server settings are wrong.

Go to downloads Windows client →

macOS

Choose v2rayN and check your chip under “About This Mac.” Apple Silicon and Intel require different packages. Prefer the option built for your device's native architecture rather than assuming every disk image is universal.

System proxy works mainly with apps that follow the OS network settings. For broader traffic capture, review the TUN requirements. Permission checks and connection setup are separate steps: get the client running and import a connection before testing app access.

Go to downloads macOS client →

Android

For an Xray core, start with v2rayNG. If you need a V2Fly core, consider v2flyNG. Most newer devices use arm64 packages. If you're unsure of your architecture, check your device information and consult the download page's notes on universal packages.

A first connection requires system VPN permission. Background operation may also be affected by battery management. If the connection drops only when the screen is locked, check background restrictions before switching protocols. Test the connection again after moving between networks.

Go to downloads Android client →

Linux

On desktop Linux, choose v2rayN. Select deb or rpm for your distribution, then confirm the x64 or arm64 architecture. Package format must match the system's package manager, and processor architecture must match the device. Both need to be correct.

Whether apps use system proxy settings depends on the desktop environment and each app's implementation. For apps that require manual proxy settings, enter the address and port the client is actually listening on. Check permission requirements before enabling TUN, and avoid conflicts with existing network rules.

Go to downloads Linux client →

Browse all clients →

Linux penguin illustration: Font Awesome Tux, used under CC BY 4.0.

SECTION 03 / FIRST CONNECTION

Get started with v2rayN. Import, route, verify.

The client does not include a working remote connection. Before you begin, get a subscription URL or share link that you are authorized to use, and make sure your current network can retrieve the subscription. For your first setup, run only one client. Establish a repeatable basic connection before adding custom routing or TUN settings.

  1. STEP 01 / IMPORT

    Import a subscription or share link

    Save a subscription URL under “Subscription groups” in v2rayN, then update it. Import a single share link from the clipboard. After importing, check that the protocol, address, port, and transport settings are complete. An entry in the list only means the client recognized the data; it does not confirm that the remote server is reachable. If an update returns no entries, check the URL, network request, and subscription format instead of repeatedly deleting every group.

    Subscription URLs may contain access credentials, so store them like account passwords. Before sharing troubleshooting screenshots, hide the full URL, identity fields, and personal notes. Back up subscription sources and local rules separately before moving to another device; copying the server list may not include all your settings.

  2. STEP 02 / PROXY

    Select a server and proxy mode

    Set the server you want to use as active, then select “Automatically configure system proxy.” For an initial test, start with a clear routing preset and confirm which destinations go direct and which use the proxy. Browser proxy extensions, manual proxy settings, or other networking tools may override system settings, so check for these additional entry points before testing.

    If an app does not use the system proxy, first check whether it has its own proxy settings. Enable TUN only if you need broader traffic capture, and then configure the required permissions and DNS. Change one thing at a time and keep the last configuration you could reproduce, so you can identify where an issue begins.

  3. STEP 03 / VERIFY

    Verify real requests and app behavior

    Tcping primarily checks whether a target TCP port is reachable. A real connection test also involves the proxy handshake and a test request, so the two tests are not interchangeable. Results depend on the test target and current network conditions. After selecting a server, open a page in your browser that should use the proxy, then compare the result with connection and routing details in the client logs.

    If the test passes but an app still does not work, check in this order: app proxy settings, local listening address, routing match, then remote handshake. Do not rely on a taskbar icon or toggle state alone to confirm that the proxy is working. After testing, note the mode and any exceptions so you can repeat the same checks when switching networks.

Read the full guide →

SECTION 04 / OPEN-SOURCE ECOSYSTEM

Project V and the core family. Tell projects, protocols, and clients apart.

From V2Ray to V2Fly and Xray

Project V is a good starting point for understanding the V2Ray ecosystem. V2Ray combines inbound connections, routing, outbound connections, and transport capabilities, making it more than a client for a single protocol. The server lists and toggles users interact with day to day usually belong to a graphical client layered on top. When someone says “V2Ray client,” first clarify whether they mean the interface, the runtime core, or the protocol used by a connection. These concepts are related, but they belong to different layers.

V2Fly continues community development of V2Ray, while Xray has evolved from related code into its own feature set. The two share configuration conventions but also differ in implementation and development. Similar-looking basic fields do not mean that every configuration can be used unchanged in either core. For VLESS, REALITY, transport extensions, or specific security options, check support in the core you actually run instead of relying on the client name alone.

What each of the three clients does

v2rayN is an open-source desktop client with a graphical interface for managing servers, updating subscriptions, choosing proxy modes, and configuring routing. v2rayNG is an open-source Android client that uses the Xray core; v2flyNG also targets Android and offers a V2Fly core. Choose a client based first on your operating system, then on the protocol features your connections need. Being able to import a configuration does not mean every field is supported.

A graphical client translates interface settings into a configuration for the core, so interface labels do not necessarily map one-to-one to native JSON fields. The core may support options that the graphical interface does not expose. For advanced settings, read the current client's documentation and check what the core fields mean. Following instructions for a different client's interface can lead you to mistake similar labels for identical features.

Open-source licensing and configuration responsibilities

Open source means code can be reviewed, used, and redistributed under the applicable license; it does not mean every related project uses the same license. Xray-core and V2Fly's V2Ray-core use MPL-2.0. Review the license terms for the client interface, core, and bundled components separately. When modifying, distributing, or integrating software, follow the relevant project's license text rather than relying on a blanket description of the ecosystem.

Open-source status does not remove the need to assess where a configuration comes from. The subscription publisher sets connection parameters, the remote server determines service availability, and the local client controls traffic entry and routing. For unfamiliar configurations, understand the routing destinations, DNS settings, and listening scope. In particular, do not expose a local proxy listener to other devices just to troubleshoot.

Update clients, cores, and rules separately

Client interface updates, core updates, and rule data updates affect different layers. An interface update may move menu items; a core update may change supported fields or runtime behavior; a rule data update may affect domain or IP collection matches. When troubleshooting a change after an update, identify which layer changed first, then compare connection parameters and routing results instead of blaming every issue on the server.

Keep the local settings you need before updating, then test the same app request that previously reproduced the issue. If you have many custom rules, check that specific rules still come before general ones. The download page provides client links, and the protocol reference explains design trade-offs. For the behavior of a particular field, consider the core currently running and its logs.

Read the protocol and core reference →　Compare the three clients →

SECTION 05 / PRACTICAL GUIDES

Connection checks and protocol choices. Follow the issue to the next guide.

These three articles cover protocol trade-offs, routing priority, and first-connection checks. Start with a stable, repeatable test path before adding custom rules. If you're migrating an existing connection, understand its protocol and transport combination first to avoid losing fields when switching clients.

Choosing Wisely

VMess vs. VLESS vs. Trojan vs. Shadowsocks: Comparing Four Proxy Protocols

Compare four protocols by their origins, encryption, handshake overhead, and mobile battery use, with guidance on choosing one for your needs.
Advanced Setup

Writing custom routing rules: domain, ip, and geosite syntax and match priority

Learn the domain, full, regexp, geosite, and geoip rule prefixes, how rules are matched from top to bottom, and how domainStrategy affects the result.
Getting Started

First connection with v2rayN: choose a server, test a real connection, and verify proxy behavior

After importing a subscription, learn how to choose a server, distinguish Tcping from real connection latency tests, and verify the proxy with system settings and browser requests.

Browse all articles →