V2Ray Protocol and Core Reference

Connection Layers: Identify which layer each setting belongs to

The client, core, and server are different components

A graphical client stores server profiles, organizes subscription groups, generates configurations, and displays logs. The core reads the generated configuration and handles local inbounds, routing, remote connections, and traffic forwarding. The server accepts remote connections and performs authentication as configured. A protocol name in the interface only means the client offers a setting for it. Actual support depends on the selected core and whether the server uses the same combination.

On desktop, for example, an app sends a request to the system proxy, which points to a local listening port opened by the client. The core receives the destination address, decides whether to connect directly or use a remote outbound, and then establishes the remote protocol connection. Android VPN mode receives app traffic through the system’s virtual network interface. The entry point differs, but protocol authentication still has to match field by field. Turning on the system proxy does not mean the remote connection has succeeded.

Break a connection into four groups of settings

The first group is the server address and port: where to connect. The second is the proxy protocol and authentication fields, such as a VMess user ID or Trojan password: how the other end identifies the request. The third is the transport, which determines how proxy data is carried over the underlying connection. The fourth is security, including TLS, server names, certificate verification, or REALITY parameters. A mismatch in any group can lead to a timeout or handshake failure.

“VLESS over TLS” is a layered combination: VLESS handles the proxy request format and authentication, while TLS provides security for the outer transport. WebSocket is a transport, not a replacement for user authentication. REALITY is a security mechanism, not a complete set of authentication details you can enter on its own in a server list. When reading a subscription or tutorial, first identify which layer each term belongs to so you know where to find the relevant setting.

The connection address and server name can differ

The server address is used to establish the network connection. The TLS server name is used for negotiation and identity verification. They may be the same in some deployments and different in others. If you change the address to an IP, don’t remove the server name as a follow-up. Conversely, entering the right name doesn’t mean you can connect to any address. With a reverse proxy, the transport path, host field, and service name must also match the deployment’s entry point.

A port number alone doesn’t tell you what service it runs. Common ports can host different services, and a port number doesn’t prove that TLS is enabled. A client’s “allow insecure connections” option usually affects certificate verification; it’s not a general compatibility fix. Keep identity verification enabled in a normal configuration. If you see a certificate error, check the system time, server name, and trust chain rather than hiding a field mismatch by disabling verification.

To check a connection, note the client, core, protocol, transport, and security type first, then compare them with the complete details from the service provider. Change one setting at a time, save, reconnect, and review the logs for that attempt. If the original subscription works but a manually recreated profile doesn’t, look for missing fields before changing routing rules. Keeping a record of the layers is more useful over time than memorizing where a particular button is.

VMess and VLESS: Trade-offs in authentication and encryption

VMess puts more responsibility in the protocol itself

VMess is an older proxy protocol widely used in the Project V ecosystem. Its design incorporates user authentication and data protection into the protocol. Its user ID is usually a UUID, and clients may also show fields such as the encryption method. Use modern configurations with authentication methods supported by the server; don’t fill in legacy settings just because an old tutorial shows them. In particular, older share links may still include alterId, but that doesn’t mean you should set a nonzero value.

VMess connection authentication depends on time, so a badly misconfigured device clock can cause authentication to fail even when the profile looks correct. When troubleshooting, enable automatic time and time zone settings in the operating system, then try again. A displayed time zone difference doesn’t necessarily mean the clock is wrong; what matters is the actual system time. If the same profile works on another device, compare the device clocks and core support before repeatedly copying the user ID.

VMess’s built-in data protection doesn’t necessarily make outer TLS redundant. The outer security layer, transport, and proxy protocol each have their own role; the right combination depends on the server deployment. If you already have a complete subscription, keep its original combination and check the imported settings. Don’t remove TLS just because you see the word “encryption.” Dropping a layer at random may leave you with a connection the server doesn’t listen for, not a lighter one.

VLESS simplifies the protocol itself, not necessarily the whole connection

VLESS is designed to do less at the protocol level and doesn’t provide the same data encryption layer as VMess. User authentication still requires the correct ID, while data security is generally handled by a complementary security mechanism. The common interface value encryption: none describes the protocol’s field requirements; it doesn’t mean you should disable outer security. For connections across networks, use a complete security combination explicitly supported by the server.

So the claim “VLESS has one less layer than VMess, so it’s always faster” doesn’t hold. Opening a page also involves DNS lookup, connection establishment, security negotiation, server processing, and the destination site’s response. Protocol header differences account for only part of the process. Short connections may be more affected by handshakes, while long transfers may depend more on link capacity and device encryption performance. Differences between routes can also outweigh differences between the protocols themselves.

flow is a compatibility requirement, not a universal speed boost

Some VLESS configurations include a flow value for a specific flow-control scheme. It must be supported by the client core and match the server, transport, and security settings. If the subscription doesn’t provide it, don’t add it just because it appears in a tutorial screenshot. If the subscription includes it but it disappears on import, check whether the share format and parser preserve the field. Switching the protocol in a dropdown won’t create a valid flow-control combination by itself.

For a manual check, work through protocol type, user ID, encryption field, transport, security, and flow, in that order. Confirm the protocol first, check the UUID for extra spaces, then review the transport and security pages. If the logs report an unknown field or unsupported flow, confirm which core is actually running instead of checking only whether the client interface offers that option. Being able to edit a field and the running core being able to recognize it are separate requirements.

There’s no need to migrate a stable VMess setup just for a different protocol name. If a new profile offers VLESS, assess it against core support and the security combination, then test it with real apps. For more detail, see VMess vs. VLESS: encryption and compatibility. The goal is a complete, server-supported, maintainable configuration—not mistaking “simpler” for “no need to check the other layers.”

Trojan, SS, and REALITY: Tell protocols apart from security mechanisms

Trojan requires a valid TLS connection

Trojan places proxy authentication inside a TLS-protected connection. Common client settings include the address, port, password, and server name. Since TLS is fundamental to its design, a correct password alone isn’t enough. The server certificate name, system trust, and connection endpoint must also match. If the client reports a certificate error first, the failure occurs before proxy password authentication; changing the password usually won’t help.

Keep the Trojan password as one complete string. When copying it, watch for leading or trailing spaces, line breaks, and encoded characters in the link. Some share links percent-encode special characters, which clients should parse according to the link format. When editing manually, don’t escape an already decoded password again without a reason, and don’t include link separators as part of the password. Importing the original link first makes it easier to compare with a manually entered profile.

Shadowsocks requires the right method and password

Shadowsocks, often shortened to SS, began as a relatively simple encrypted proxy design. Its key settings are the server address, port, encryption method, and password. The method isn’t a local preference you can choose at will; both ends must use the same one. Even with the right password, a method mismatch prevents successful decryption. A method listed in an older guide may not be supported by every current core; check the actual implementation and server configuration.

Traditional AEAD methods and the Shadowsocks 2022 family have different key requirements. The latter may require keys that meet specific length and encoding rules; a regular password won’t necessarily work. Share links can also carry extensions that the three clients don’t all recognize. If import succeeds but the connection fails, check the method name, key format, and core support—not just whether the server appears in the list.

Understand REALITY as a security-layer mechanism

REALITY is a security mechanism in the Xray ecosystem, not a protocol on the same level as VMess, VLESS, Trojan, or Shadowsocks. One common setup combines VLESS with REALITY: VLESS provides the proxy protocol, while REALITY provides the associated security handshake. You still need a valid address, port, and user authentication details, along with server-provided parameters such as public key material, server name, and short ID.

You can’t migrate to REALITY by renaming a regular TLS toggle. The server must explicitly support it, and the client’s core must recognize its parameters. Interface labels may vary by implementation, so focus on what each field does: which values are public verification material, which are user authentication details, and which specify the handshake name. The private key is sensitive server-side configuration. It shouldn’t appear in a client subscription or be requested to fill in a missing import field.

When comparing these options, write down the full combination. “Uses REALITY” alone doesn’t tell you how the user is authenticated, and “uses SS” doesn’t specify the encryption method. Short names in a client list are convenient for browsing, but not enough for troubleshooting. Recording the full combination reduces ambiguity and helps prevent misattributing an outer handshake failure to the proxy protocol itself.

Start with the server configuration you have. If it offers only a Trojan entry, check TLS and the password. If it offers only SS, check the method and key. If it offers VLESS with REALITY, confirm Xray support and that all fields are present. Ask the configuration provider for missing details instead of guessing by cycling through security options. Guesswork adds variables and makes the original missing field harder to find.

Performance and Battery Use: Compare the cost of the whole connection

Connection speed has several stages

Perceived speed includes at least three stages: establishing the connection, receiving the first response, and transferring data over time. The first depends on DNS resolution, network round trips, and handshake count. The first response also depends on the remote destination, while sustained transfers are limited by link capacity, congestion, and device performance. So a protocol comparison needs to specify which stage is being measured. Treating a single latency test as a download-speed ranking can lead to conclusions that don’t match real-world use.

Protocol authentication, encryption, and encapsulation use resources, but hardware acceleration, system scheduling, and implementation optimizations vary between devices. The names VMess, VLESS, Trojan, and SS don’t tell you a fixed order of CPU usage. VLESS doesn’t handle the same encryption responsibilities at the protocol level, but that doesn’t make the associated TLS or REALITY cost-free. Compare the same device, similar network routes, and clearly defined security combinations—not just protocol names in a dropdown.

Transport overhead and connection reuse have trade-offs too

Transports such as WebSocket may add overhead to fit a server’s entry point; how much it matters depends on the workload. Multiplexing carries multiple requests over fewer underlying connections. This may reduce repeated connection setup, but it can also make requests share the impact of packet loss and scheduling on one connection. Whether to enable it depends on the server and flow-control scheme; don’t turn on every option labeled “multiplexing.”

For a fair test, use the same destination site and keep routing and DNS settings unchanged. Compare the first page load, subsequent loads, and a sustained transfer. Change one variable per round and note whether a new connection was established. Browser caches, destination caches, and existing connections all affect results, so repeating a test once doesn’t automatically remove the noise. If configurations connect to different servers, the results mostly compare two service routes and can’t isolate protocol efficiency.

Android battery use depends more on sustained activity

Android VPN mode uses the system’s VpnService to receive app traffic. When apps keep making network requests, the client may wake up and process data. Reconnection attempts, DNS queries, and log writes also add activity. Lower resource use for a protocol on desktop doesn’t prove it will use less battery while a phone is idle. Wireless quality, background apps, and system battery policies are often major factors on mobile devices.

To investigate battery drain, compare the system battery records with the client enabled and disabled under the same usage habits. Then narrow the test to VPN mode, per-app routing, or a specific app. Look for spikes during weak signal, network switching, or background transfers. If the logs show repeated connection attempts, fix the connection failure first. Simply increasing every timeout may keep a failing connection waiting longer without reducing its work.

Set the log level to match the troubleshooting task. Increase detail temporarily for diagnosis, then restore a suitable level for daily use to avoid generating excessive logs. Latency probes and automatic tests also initiate connections, so don’t run them too frequently just to check status. Keep client list updates, subscription refreshes, and real app traffic separate; not all background activity comes from the app you’re browsing in.

If only a particular app drains battery or fails, check whether it relies on UDP, persistent connections, or background push, then review the proxy scope. Routing only necessary apps through the VPN can reduce unrelated traffic, provided you understand how per-app mode works. See v2rayNG permissions, battery settings, and per-app routing. For speed issues, troubleshoot the server, route, and local settings layer by layer instead of switching protocols as a substitute for diagnosis.

V2Fly and Xray: Check compatibility feature by feature

A shared ecosystem doesn’t mean identical implementations

Project V provides useful background for understanding the V2Ray ecosystem. V2Fly continues development of related cores and components, while Xray has evolved from a shared history along its own feature path. They share some protocols, configuration structures, and terminology, so basic configurations can look alike. But that doesn’t mean every file is interchangeable. Security mechanisms, flow control, transport details, and DNS behavior can differ; check each feature specifically.

REALITY and specific VLESS flow-control schemes are common deciding factors when choosing a core. If a subscription requires a capability specific to Xray, switching to V2Fly won’t add support just because the configuration looks similar. Conversely, a basic connection that doesn’t use those features doesn’t prove that one family is always required. Choose a core to support your existing protocol combination and maintenance needs, not as a performance tier.

Where the three clients fit in the same setup

v2rayN is the recommended starting point for desktop use across Windows, macOS, and Linux. It provides graphical management and configuration generation; the available core features depend on the specific distribution and runtime settings. An option in the interface doesn’t mean every core can handle it. When troubleshooting, check the startup records to confirm which core actually ran instead of inferring the runtime environment from the client’s name.

On Android, v2rayNG is designed for use with the Xray core; v2flyNG is an alternative for the V2Fly core. Their workflows may be similar, but protocol differences still matter. If the imported profile uses a security or flow-control feature implemented by only one core, choose the client based on that feature first, then configure permissions and connectivity. See how to choose between three V2Ray clients for a full comparison.

Check the generated configuration when switching cores

The most reliable starting point for migration is the original subscription or complete share link, not guessing each field from screenshots of the old client. Create a separate group in the target client, import the profile, then check the protocol, address, authentication, transport, security, and flow. Keep the old configuration until you’ve verified one entry. If the original details omit extension parameters, even a client that supports them can’t restore information that was never provided.

When migrating native JSON, distinguish a complete configuration from a partial outbound. A complete configuration may specify local inbounds, routing tags, DNS, and logging. A new core accepting a field doesn’t guarantee that the whole setup will behave the same. In particular, routing tags must refer to existing outbound tags; otherwise, the configuration may load while traffic takes the wrong path. Verify a minimal connection first, then migrate local policies step by step.

Updating the client and updating the core aren’t always the same operation. Depending on how it’s distributed, a client may bundle the core or manage it through its own features. Follow the installed package and interface instructions; avoid core files from untrusted sources. Export your configuration before upgrading, then check key connections and routing behavior. If something breaks, record what changed and determine whether the parser, configuration generation, or core execution was affected.

Open source means the code and implementation can be studied and improved; it doesn’t mean every fork uses the same license, release schedule, or feature set. Follow each component’s actual license when redistributing it. For everyday troubleshooting, the most useful record is the client, the core actually running, and the protocol features you need—not the vague note “V2Ray installed.” Those details also make future bug reports more precise.

Subscription Formats: A successful import doesn’t guarantee complete fields

The URL, response, and internal configuration are three different things

A subscription URL is just an entry point for retrieving content; its ending doesn’t determine the response format. A request may return a list of share links, a base64-encoded list, native JSON, or an error page. After retrieving the content, the client still has to identify the format, parse the fields, and convert them into its own configuration model. So opening a URL in a browser only confirms that it returned a response; it doesn’t prove the content contains server details the client can read.

base64 is an encoding method, not encryption, and it doesn’t make content secure. A common subscription encodes multiple share links joined as text; after decoding, each link still has to be parsed according to its own format. Double encoding, missing line breaks, embedded web page markup, or character encoding issues can all affect parsing. Don’t upload a private subscription to an online decoder. The URL itself may contain access credentials and should be treated as sensitive.

Share links don’t have one universal field syntax

Common VMess share links contain encoded structured data. VLESS and Trojan links often combine an address with query parameters, while SS has several share formats. Similar protocol prefixes don’t mean you can copy query parameters between formats. The name is usually just a label; changing it won’t change what the server supports. Transport paths, server names, and flow settings can directly affect the connection and shouldn’t be dropped during conversion.

A parser also has to recognize extension fields. A client may keep the main protocol details but ignore security parameters it doesn’t understand, leaving a profile in the list that can’t connect. After importing, open the server editor at least once and check the protocol, transport, security type, and key related fields. If anything is missing, look for an original format supported by the target client instead of repeatedly converting a copy that has already lost fields.

Native JSON may not belong in a subscription-group importer

Native JSON can be a complete runtime configuration or a partial set of outbound details. A complete configuration may include local listening ports, DNS, routing rules, and multiple outbounds, so it behaves differently from a regular server subscription. Some clients manage it as a custom configuration rather than splitting it into servers in the usual list. Check the importer’s instructions before importing to avoid treating a full configuration as a list of individual servers.

A complete configuration may also override existing local behavior. Subscription lists are usually used by the client to generate inbounds and routing, while custom JSON may specify them directly. If the system proxy stops working after import, check whether the actual listening port still matches the system setting. If you use additional routing tags, confirm that their referenced outbounds exist. Valid JSON syntax alone doesn’t make a configuration suitable for your graphical client’s management model.

In v2rayN, open subscription group management and choose “Subscription Group Settings.” Save the URL, then run the relevant update action. If the client offers “Update current subscription (without proxy),” it means the request for subscription content won’t use the existing proxy route; it doesn’t change the response format. If connections work but a direct update fails, check which update methods the client supports. If no connection works, first confirm whether the subscription endpoint is reachable directly.

If no servers appear after a subscription update, first check whether the request succeeded, then whether the content could be parsed, and finally whether group filters are hiding the entries. A login page, quota notice, or error text is different from an incompatible format. If only a few entries fail after the update, focus on their protocol fields instead of deleting every group. When asking for help, share a redacted error type and protocol combination; don’t expose the full subscription URL or authentication details.

Format conversion can preserve meaning only when the source contains enough information; it can’t invent server parameters. Exporting a full configuration as a simple link usually loses complex routing and DNS settings. Rebuilding JSON from a link can’t restore local policies the link never contained. See conversion limits for base64, native JSON, and share links for examples. After conversion, recheck key fields and verify the connection.

Routing and Settings: Configure routing after the protocol works

First distinguish the local entry point from the remote outbound

A local SOCKS or HTTP listener receives app requests; a remote outbound connects to the server. Their ports can be completely different, so don’t enter the server port in an app’s local proxy settings. Ports shown in examples are conventions only; use the port the client is actually listening on. If another program is using that local port, the core may fail to start, and even correct remote protocol details won’t be used.

The example below shows a real inbound configuration snippet to explain how its fields relate; it isn’t a complete configuration for connecting to a server. It listens only on the local loopback address, so apps must connect to the corresponding port on the same device. Don’t change the listening address to all network interfaces just to fix an app’s proxy settings; that changes which other devices can access the local proxy. Provide remote protocol and authentication details separately in a complete outbound.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    },
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

domainStrategy controls name resolution during route matching

In routing, domainStrategy determines how destination domains are handled while rules are being matched. AsIs keeps the original destination form and doesn’t resolve a domain just to match an IP rule. IPIfNonMatch tries to resolve the name when no domain rule matches, then continues with IP-based matching. IPOnDemand triggers resolution when a matching rule needs IP information. These options affect the matching process; they don’t directly decide whether traffic goes through the proxy or connects directly.

Don’t confuse these values with similarly named policies in an outbound or another module. Before choosing one, check which configuration object contains the field and what it means there. If an app initially provides only an IP address, routing may not have a domain to match. Sniffing can sometimes recover a domain clue from connection content, but it doesn’t work for every protocol or type of traffic and can’t guarantee recovery of the complete original domain.

DNS, rule order, and destination format all affect the result

Common routing configurations check rules in order. A broad rule near the top may prevent more specific rules below it from taking effect. Domain and IP rules also depend on the destination format available at the time. If a rule doesn’t seem to match, first check whether the request appears as a domain or an IP, then identify which rule matches first, and finally check the destination outbound tag. Don’t start by widening every rule.

Core DNS and operating system DNS may serve different purposes. An app may resolve a name itself, the core may resolve it again for routing, and the remote server may resolve the final destination. Changing one DNS address doesn’t prove that every request uses the same path. If a domain works but an IP rule behaves unexpectedly, check where resolution happens, which address family is returned, and whether cached results are involved before changing domainStrategy.

Android per-app proxy settings control which apps enter or bypass the VPN path; core routing decides how traffic is forwarded after it enters. In bypass mode, the app list may change from an inclusion list to an exclusion list, so follow the interface instructions. After changing the list, reconnect the VPN if the client requires it so the system applies the new scope. Test one specific app and destination to avoid changing the app list, DNS, and domain rules at the same time.

Validate in order: confirm the local listener is active, the app’s request reaches the client, the protocol connection works, and only then add routing rules. If something breaks, temporarily return to a verified simple policy, then restore rules one by one. See Frequently Asked Questions for common routing, DNS, and proxy mode issues. This separates “traffic never entered,” “the remote server is unreachable,” and “the route didn’t match” so you don’t have to keep guessing at protocol fields.

Use Cases and Troubleshooting: Turn your choice into a clear checklist

On desktop, choose a client first, then check the protocol combination

For desktop use, start with v2rayN. On the download page, choose the package for your operating system and device architecture. The package’s interface and the remote protocol are separate choices: the Windows desktop and classic WPF versions differ in interface and distribution, not in whether you need to buy or create a different protocol entry. If you already have a subscription, import it and verify one connection before adjusting the interface or local groups.

On Android, choose v2rayNG for profiles that explicitly require Xray features. If your existing profile targets V2Fly and its features are supported, consider v2flyNG. Don’t overlook associated security settings just because both apps recognize the same link prefix. For long-running background use, also check VPN permissions, battery policies, and per-app scope. If the system revokes permission and disconnects the client, changing the UUID or encryption method won’t fix it.

Your existing server details determine what you can choose

If you have only one valid server configuration, prioritize setting it up correctly rather than choosing another protocol based on a general ranking. If the server offers several entries, compare client support, completeness of the details, real-world app performance, and maintenance costs. For frequent device migrations, a widely supported format and complete field import may matter more than a small protocol overhead. If you need a specific Xray feature, core support is a requirement.

Local network management, web browsing, and sustained transfers have different connection needs. Web browsing often involves many short requests; real-time apps care more about connection stability and the UDP path; long transfers depend more on sustained route capacity. A protocol name can’t replace testing with your actual workload. Run a real task under the same network conditions, then check recovery after disconnects and network changes. That’s more representative than a single test result in a client list.

Troubleshoot by failure stage, not by swapping settings at random

First, check whether the core starts. If configuration parsing fails, a field is unknown, or a port is already in use, fix the local issue first. Next, check whether the server address and port are reachable. A connection timeout may involve the address, route, or remote listener; it doesn’t yet prove the password is wrong. Then check the security handshake, focusing on the system time, server name, certificate, and REALITY parameters. Check proxy authentication and destination forwarding last.

If the logs show an established connection but the app receives no data, confirm that its request actually reached the client, then check DNS, routing destinations, and remote access. If one site fails but others work, narrow the investigation to that domain and app behavior instead of reinstalling the client. If only UDP traffic fails, check the local entry point, protocol support, and server forwarding; a successful TCP connection doesn’t prove everything works.

If you need help, keep the log excerpt for a specific failed attempt and note the client, core actually running, protocol, transport, security mechanism, and failure stage. Remove subscription credentials, passwords, user IDs, and other details that could identify your account. Check screenshots for hidden fields and the full address bar. “It won’t connect” forces troubleshooting to start from scratch; “the security handshake fails” rules out many unrelated settings.

You can narrow the choice down to three questions: What complete combination does the server provide? Can the current core represent it without changes? Does it work reliably in real apps on the target device? Once those answers are clear, optimize routing and background behavior. For your first connection, follow the quick-start guide. For recurring symptoms, check the Frequently Asked Questions. For design trade-offs, return to the relevant section of this reference. Keeping setup, concepts, and troubleshooting separate makes configurations easier to maintain.