Protocol Guide · Technical Reference

V2Ray Protocol and Core Reference

For first-time setup, importing a subscription, and testing your connection, follow the steps in the user guide. This handbook is a reference for deeper research: when you receive a node, identify its protocol, transport, and connection security, then check core and subscription-format compatibility. If you already have a working configuration, compare first-connection time, sustained transfers, and idle behavior to decide whether a change is worthwhile.

Connection Layers: Protocol, Transport, and Security

A Client Label Is Not a Complete Configuration

When editing a node, first separate its settings into three categories. The protocol defines how the client identifies itself to the proxy, specifies the destination, and transfers data. The transport determines how that data travels. Connection security defines how the endpoints protect and verify the connection. A common subscription combination is VLESS as the proxy protocol, WebSocket as the transport, and TLS as the security layer for the connection. Check each separately: changing the first option in the interface to VLESS does not turn a WebSocket node into a direct TCP connection or supply the path or server name expected by the server.

These layers are a useful way to compare configurations, but not every protocol can be combined arbitrarily. Standard Trojan deployments use TLS as the outer layer, while modern Shadowsocks typically handles encryption and integrity protection within the protocol itself. VMess payload protection is also separate from outer TLS. Some interfaces show options labeled “encryption” and “security” in different sections; similar names do not make them interchangeable. Check whether a setting belongs to protocol authentication, transport parameters, or transport security. Don’t copy a setting from a screenshot of a different node type just because the label matches.

Layer to CheckCommon SettingsTypical Mismatch
Proxy ProtocolProtocol type, user ID, password, encryption methodThe connection is established, but the proxy rejects authentication or closes the session
TransportTCP, WebSocket, path, HostThe port is reachable, but the upgrade request is rejected or routed to the wrong endpoint
Connection SecurityTLS, REALITY, server nameThe handshake fails or the certificate name does not match
Local Traffic EntrySystem proxy, TUN, routing, DNSThe client test succeeds, but a specific app does not use the same route

Addresses, Server Names, and Paths Serve Different Purposes

The remote address and port determine where the client connects first. The TLS server name is used during the handshake and to verify the certificate identity. The WebSocket Host and path may determine which backend a reverse proxy sends the upgrade request to. These values may be the same or configured separately, depending on the server. Changing the address from a hostname to an IP does not mean you should also change the server name to an IP. Likewise, adding the path to the address field does not make up for a missing path setting. If a field is blank after import, compare it with the original subscription and check whether the client fills in a default based on the address; a blank form field does not always mean the original configuration omitted it.

The following snippet shows transport settings in an Xray outbound, using example domain names to illustrate the relationship between plain TCP transport and TLS. It belongs inside an outbound object and is not a standalone configuration. Other fields in the same outbound provide the protocol, remote address, port, and authentication parameters. If the client has not yet established a connection, there is no need to export the entire configuration to an external tool just to inspect these settings.

{
  "streamSettings": {
    "network": "tcp",
    "security": "tls",
    "tlsSettings": {
      "serverName": "example.com"
    }
  }
}

Narrow Down the Problem by Finding the First Failure

A useful troubleshooting sequence is to check whether the domain resolves, whether a connection can be made to the specified port, whether the security handshake completes, whether the proxy request succeeds, and finally whether the app’s traffic enters the proxy. Client DNS, dialing, and connection reuse can change the actual event order, and logs may not distinguish every layer; treat this sequence as a guide, not a fixed log timeline. Distinguish a successful connection test from an app reaching a destination through the proxy. The client may initiate the first test itself, while the second also depends on system proxy settings, app configuration, and routing rules.

When recording a failure, note the error type, the stage where it occurred, and the test environment. Remove subscription URLs and authentication values. If you change the address, path, and security settings at the same time, even a successful connection won’t tell you which change fixed the issue. Copy the configuration or keep the original, then check one field at a time. If the outer handshake succeeds but the destination still fails, check destination DNS resolution, reachability from the proxy, and local routing separately. Don’t keep blaming a port that has already passed testing.

VMess and VLESS: Authentication and Protection

VMess: More Responsibilities Within the Proxy Protocol

VMess originated in Project V’s early work on a general-purpose proxy protocol. It does more than verify a password and forward bytes: requests carry destination information at the protocol layer, and the protocol provides authentication and encryption-related mechanisms that have evolved over time. Current configurations often include a UUID, an encryption option, and legacy additional ID parameters. A UUID that looks identical in VMess and VLESS nodes only means they use a similar format for identity values; it does not mean the proxy can interpret requests in the other protocol. When maintaining an existing configuration, first confirm that both implementations support the authentication method currently used by the server.

VMess authentication involves time information, so a device clock that is out of sync is a common and easily missed cause of failure. If the node works on another device but the current device has been offline, asleep, or had its clock changed manually, sync the system clock before retrying the same configuration. Changing the displayed time zone will not fix an incorrect clock. Older subscriptions may include an additional ID field; modern VMess AEAD configurations typically use a zero value, but fixing compatibility between old and new implementations is not a matter of guessing numbers one by one. Check the server configuration and core support before deciding whether to keep the legacy node or migrate.

Also distinguish VMess’s own payload encryption settings from TLS on the outer connection. If a subscription includes both sets of parameters, the importer must not treat them as one option. If a browser can reach a remote site but a proxy session disconnects immediately after starting, that only shows that the browser completed its own connection; it did not authenticate through VMess. When comparing against a working configuration, check the device clock, user ID, and selected transport as well as the address and port. Don’t stop at whether the domain opens.

VLESS: Relying on Other Layers for Connection Protection

VLESS is designed to separate proxy request handling from the secure channel around it. Common configurations use a UUID to identify the user and TLS or REALITY to protect the transport connection. The encryption=none value often found in subscriptions describes a protocol field; it does not mean the entire connection necessarily runs in plaintext. Conversely, seeing VLESS does not guarantee that the outer connection is protected. When checking a configuration, record the protocol encryption field and connection security settings separately. In particular, check whether the client automatically set the latter to standard TLS or left it blank after import.

Some VLESS nodes also include flow, such as xtls-rprx-vision in an Xray setup. This is not a speed preference or a client-side optimization that speeds up any transport when enabled. It is a flow-control option that both endpoints must support and match. If the server offers multiple endpoints for the same account, one may require a particular flow setting while another uses a different transport; similar labels do not make their settings interchangeable. If an older interface lacks this option, check the active core and whether the importer preserves the field. Don’t clear it manually and expect the protocol to negotiate it automatically.

Choose for Maintainability, Not by Age

If you only have one VMess endpoint that you’ve confirmed works, use VMess in the client. Switching to VLESS only makes sense when you have a working VLESS endpoint and have confirmed that all its parameters can be saved end to end. To compare overhead, use the same network path and server environment as far as possible. Comparing a remote VMess node with a nearby VLESS node mostly tells you about the complete configurations, not the protocols alone. For a migration, start with a separate group on one device. Check that the node still works after reimporting and refreshing the subscription, then migrate other devices one at a time. Keep the old configuration until every device that needs the service has been tested. Keeping both endpoints temporarily is easier to manage than declaring one faster without a fair way to test.

Trojan and Shadowsocks: Certificates and Encryption Methods

Trojan: Proxy Requests over a Standard TLS Session

Trojan is designed to carry proxy requests inside a TLS session, using established certificate and encryption mechanisms to protect traffic. The proxy server identifies requests using authentication information derived from a password. Server operators typically need to maintain the domain, certificate, and renewals. A client node needs at least a remote address, port, password, and matching TLS settings. If a compatible implementation adds another transport, check the parameters required by that implementation as well. The original protocol’s design does not tell you how a specific service endpoint is configured. In particular, a share-link prefix alone cannot prove that it uses the simplest transport setup.

Troubleshoot Trojan by checking two stages separately: whether certificate validation succeeds and whether authentication succeeds after TLS is established. If the certificate name does not match, check the server name and certificate coverage. If the certificate is untrusted, check the trust chain, deployment, and device clock instead of changing the password. If the connection succeeds but authentication fails, check which endpoint is in use, whether the credentials changed with the subscription, and whether the importer decoded them correctly. A TLS website opening does not prove Trojan works: ordinary web requests and proxy requests can follow completely different paths on the server.

Shadowsocks: The Method and Key Must Match

Shadowsocks, often shortened to SS, is designed as a relatively simple encrypted proxy. It is not another kind of TLS website that the client recognizes. Common deployments protect proxy data within the protocol itself, and modern methods use authenticated encryption for both confidentiality and integrity. Don’t change the “encryption method” field at random: the client and server must use the same method and the correct password or key format for that method. A matching product name does not guarantee that both implementations support all the same methods.

When maintaining an older configuration, distinguish legacy methods from common AEAD methods and the newer Shadowsocks 2022 series. The newer series cannot be enabled by simply adding an algorithm label to an old password; it has different key requirements and protocol handling. If the method changes to a default during import, the node appearing in the list does not mean its configuration is intact. Check any additional parameters too: if the server relies on a plugin or specific UDP support, the client must both read those settings from the share link and have an implementation that can use them. A successful TCP website test does not show that scenarios such as voice calls, which rely on UDP, will work too.

Choose Based on Ongoing Maintenance

Trojan has a clear maintenance path when TLS is fully deployed, certificate expiry is monitored, and every endpoint supports the required configuration. For Shadowsocks, include method support, key format, and the app’s UDP requirements in your acceptance tests. Both may appear to connect after you enter a password, but their failures need different explanations. If a protocol fails on only one device, first check that device’s core and imported settings. If all devices fail around the same time, prioritize server changes, certificate issues, or a migrated endpoint. Keeping retest results in the node group’s maintenance notes makes the next issue easier to investigate than saving only a speed-test screenshot.

REALITY: Connection Security and Matching Parameters

Why It Belongs in a Different Category from VLESS

REALITY emerged from the Xray ecosystem and handles the security handshake for the transport connection; it does not replace the proxy request format. A common client configuration combines VLESS with REALITY: VLESS holds the user ID and, when needed, flow settings, while REALITY holds parameters for its security mechanism. REALITY takes cues from the TLS handshake, but client verification of the actual proxy endpoint differs from standard TLS. Don’t classify a REALITY node simply as “another VLESS protocol,” or assume it can be swapped for any TLS configuration that has a valid domain certificate.

This distinction matters when maintaining a deployment. Standard TLS endpoints are generally maintained around their own certificates and trust chains. REALITY deployments are maintained around matching keys, permitted names, and other handshake parameters. After changing any of these server-side values, confirm when clients will refresh their subscriptions and which old entries may still be in use. A reachable port, an accessible website, or another endpoint working with the same account does not prove that this REALITY configuration is up to date.

Identify the Server Name, Public Key, and Short ID

Common client forms list the server name, server public key, short ID, and handshake fingerprint under connection security. The server name must match a value allowed by the deployment; it is not necessarily the address being dialed. The server public key must match the proxy’s key pair and is not the certificate text shown by a browser in a standard TLS setup. The short ID must be supplied by the service; it is not an abbreviation of the UUID. The fingerprint option affects how the client presents its handshake and is handled by the implementation as configured; it is separate from account credentials. Before entering these values in fields that seem to have the closest matching names, check the current client’s field descriptions and the original subscription.

Handle each security field according to its purpose. The server’s private key is not client-side share data; never copy it into a public-key field to make the handshake work. Although the server public key is not a private key, a complete share link may also contain a user ID and related details, so it still should not be posted publicly. If a software update changes field names, compare the original link with the node editor locally. Screenshots can show where fields are, but cannot replace parameters from the same service. For subscription-managed nodes, fix the upstream export where possible instead of repeating manual edits after every update.

When a Field Is Missing, Check the Source, Importer, and Core

First, confirm that the source explicitly specifies REALITY, rather than merely including the word in a remark; remarks generally do not affect the handshake. Next, check whether the client’s edit screen retains the relevant parameters after import. If the source is complete but fields are missing from the editor, the issue may be the share format or importer. If the editor looks complete but startup reports an unknown security type or flow setting, the generated configuration may not match the active core. These cases need different fixes: use a supported subscription export format for the first; check the core or switch clients for the second.

If a node works on one machine but fails on another, first confirm that both imported the same endpoint and check which core and security type the target device actually loaded. Once those match, check the handshake error and device clock. If a configuration change caused a widespread failure, keep the previously working node for comparison, wait for confirmed new parameters, and verify the downloaded subscription. Don’t try to fix it by disabling verification or forcing connection security to standard TLS. Conditions that require both endpoints to match cannot be supplied by selecting a similar-looking client option alone.

Xray and V2Fly: Core Families and Compatibility Limits

Shared Origins Don’t Make Configurations Interchangeable

Project V provided the technical foundation for a general-purpose proxy platform, and V2Fly continues the community maintenance and development of V2Ray. Xray has direct roots in the same technical tradition but evolves independently, with its own connection security and flow-control capabilities. The two projects share some protocol, transport, and routing concepts, which helps when understanding their configurations, but identically named fields are not guaranteed to have the same format, defaults, or supported combinations. In particular, don’t assume an Xray-specific combination works in another core just because both support VLESS. Before choosing or maintaining a subscription, check the exact combination you need rather than asking only whether it is “V2Ray.”

Configuration files are another compatibility boundary. A full configuration can describe not only remote nodes but also local listeners, routing, DNS, logging, and statistics. Even if both cores can connect to a basic node, they may handle extension fields, transport names, rule resources, or configuration structure differently. Some implementations reject unknown values; some tools may clean up or convert settings before passing them to the core. No error dialog does not mean every setting took effect. A reliable migration usually focuses on the features and parameters you need to keep, not copying the entire file verbatim.

Check the Interface, Parser, and Runtime Core Separately

ClientPlatformWhat to Check
v2rayNWindows、macOS、LinuxRecommended for desktop; confirm the node’s active core and traffic entry
v2rayNGAndroidUses Xray as its core; check that security, transport, and flow settings are preserved
v2flyNGAndroidV2Fly-based alternative; confirm that each node combination is supported

A graphical client parses a subscription into node objects, then combines them with local settings to generate a runtime configuration. A successful first step only shows that it can read some fields; the second requires it to generate the core configuration correctly; after startup, the runtime core must complete the actual handshake. v2rayN is the desktop recommendation, but check the core shown in the logs and the active configuration rather than inferring the implementation from the installer name. On Android, if you use an Xray-specific combination, check v2rayNG first. Consider v2flyNG when the subscription explicitly provides a compatible V2Fly endpoint. Choose by platform on the download page, and compare the three clients.

Migrate Only What You Need to Keep

Start with a known-working node that has as few settings as possible. Note its protocol, transport, security, and authentication fields, then import it into the target client. Once the individual node works, restore your usual routing, DNS, and local port settings gradually. Don’t move an otherwise working app proxy setup at the same time; if local software still points to the old listening port, the problem can look like core incompatibility. Test new rules with one destination that should use the proxy and one that should connect directly. This checks rule order rather than merely whether a browser eventually gets a response.

If the new setup fails only after rules are loaded, focus on rule resources and actions. If startup fails only after importing a node with a less common protocol, narrow the problem to the configuration generated for that node. Read the first actionable error in the startup log; later errors are often just consequences of the earlier failure. Keep the old configuration for comparison, but don’t include its keys in feedback. Recording the client, core, node’s three configuration layers, and failure conditions is more useful for fixing the issue than labeling an entire core family “supported” or “unsupported.”

Subscription Formats: Fetching, Parsing, and Updating

A Subscription URL Is Not a Single-Node Address

A subscription URL retrieves a set of nodes. It may return share links on separate lines or an encoded list of those links. A single share link describes one endpoint and usually cannot sync updates. When you see an address beginning with HTTPS, first determine whether it is a subscription URL for the client to fetch periodically or something else; don’t paste it as the node’s server address. Some services return different content depending on the selected export format or client request. A page opening in a browser only means the browser made a request; it does not tell you which subscription text the client will receive.

Encoding and format are separate issues. Base64 can wrap text, but it does not identify the format or provide confidentiality. Some widely used VMess share links encode node data in a link; VLESS and Trojan often put connection settings in URI fields; Shadowsocks links also have multiple representations. A list can therefore have an outer wrapper and additional encoding inside individual links. Don’t assume every string should be decoded as a whole, or repeatedly decode escaped characters in query fields; doing so can alter paths, password characters, or separators that should have been preserved.

Verify Imports by Checking That Fields Are Preserved

When you get a new subscription source, create a separate group, fetch it once, and open a representative node in the editor. Check the protocol, transport, path, security type, and flow in addition to the address and port. For Shadowsocks, note the method to make sure the importer hasn’t silently replaced it with a default. For REALITY nodes, confirm that the security type and essential parameters are present. Seeing a remark in the node list may hide the fields that distinguish one endpoint from another. If there are several export options, choose a format explicitly supported by the target client. A complete app-specific configuration and a list of share links are not interchangeable formats.

For on-the-spot troubleshooting, sort the symptoms into three groups. If fetching fails, check the device’s connection to the subscription service, whether the URL is complete, and whether the source has expired. If fetching succeeds but no nodes are recognized, check whether the response is in the expected format rather than a login page, error page, or other content. If nodes appear but fail at runtime, then check imported fields and core support. Some clients may import only part of a list, so review one node from every required protocol combination. A simple node connecting successfully does not mean the entire subscription has passed compatibility testing.

Keep Subscription Nodes Separate from Manual Tests

Group names are for local organization; they do not make nodes more compatible. After a subscription refresh, the client may replace every entry in the group, overwriting manually edited paths or security settings. To test import differences, copy a test node into a separate manual group and keep one entry from the original subscription for comparison. If the source format is the problem, fix the source or use the right export format rather than treating manual edits after every refresh as standard procedure. Setting a very short update interval will not restore expired credentials and may obscure what happened during the initial update failure.

Subscription links may contain access tokens and should be treated as credentials. Don’t send the original URL, raw share links, or QR codes to untrusted online conversion services, and don’t paste the full response into a support request. If the same subscription behaves differently across devices, you can share the export format, the failure stage, and field categories without authentication values. First determine whether the issue occurs during fetching, parsing, or runtime; then decide which endpoint to test next.

Performance and Battery Use: Meaningful Comparisons

Separate First Connection, Warm Connections, and Sustained Throughput

The first request may include DNS resolution, connection setup, the security handshake, proxy authentication, the proxy’s connection to the destination, and the destination’s response time. Later requests may reuse an existing connection, so a page loading faster the second time does not mean the protocol performs better only on the second try. WebSocket may require an application-layer upgrade unlike plain TCP transport; TLS session resumption and a pre-warmed connection also affect first-connection time. A single number from a client’s node list rarely isolates protocol overhead; differences in the test target or cache state can look like protocol behavior. Recording whether a connection already existed before the first test is more useful than keeping extra decimal places.

Sustained throughput also depends on line capacity, congestion, packet loss, server resources, and rate limits at the test destination. To compare proxy protocols, use the same device, network, approximate time, and test target. If nodes use different routes, describe the result as a comparison of those endpoints in that scenario, not a ranking of protocols. For a cold-start test, fully disconnect the relevant session before trying again. For a warm-connection test, confirm that the method actually reuses the connection. Alternating several test rounds can reduce time-of-day bias; record typical results and the slowest run instead of deciding based on one unusually high score.

Separate CPU Overhead from Connection Management

Protocol overhead does not come from encryption algorithms alone. Traffic may pass through TUN capture, protocol framing, outer-layer protection, and buffering before leaving the client; incoming traffic must then be unwrapped, verified, and delivered. Hardware acceleration for different encryption algorithms also varies by device. When assessing resource use, compare idle behavior with a consistent workload. If the same configuration uses more resources only after enabling TUN, first check the traffic scope and local routing rather than blaming the remote protocol. Apps that bypass that entry after switching to the system proxy should not be included in the same throughput comparison.

Memory use often depends on concurrent sessions, buffers, and loaded rules, not just the node type. For example, a workload that keeps many idle long-lived connections may use memory differently from a single continuous download, even with little traffic. Multiplexing can reduce repeated connection setup, but packet loss or blocking on a shared underlying connection can affect multiple requests. Reproduce the app’s real usage first, then check for many short-lived connections, retries, or sessions that are never closed. Changing every variable at once makes the results impossible to interpret.

On Mobile, Test Idle Use and Network Switching First

On a phone, battery drain with the screen off is often related to the wireless radio waking up. Automatic subscription updates, scheduled tests, persistent connections, repeated reconnects after signal loss, and background app requests can all consume power independently of protocol encryption. Compare the same phone on the same network type with similar signal strength. Keep the screen state and test duration fixed: first measure background behavior without active transfers, then test a consistent task separately. Don’t attribute differences in starting charge, screen use, or cellular signal to the protocol. Check the system’s battery stats alongside whether the client spent long periods reconnecting or running frequent tests.

For commuting, more useful measures include how quickly apps recover after a network switch, whether retries continue during an outage, and whether there is a noticeable delay between the port becoming reachable and apps reconnecting. If one strategy frequently wakes background tasks, changing the protocol while keeping that strategy may make little difference. Reduce unnecessary polling and fix repeated connection failures before comparing real end-to-end use. When reliability is similar, a combination that stays stable and has predictable maintenance costs is more valuable than a small lead in a short test.

Choosing for Your Use Case: From Available Endpoint to Acceptance Testing

Narrow Down Your Client Choice Based on the Server Endpoint

For most people, the protocol is determined by the available server endpoint, not chosen from a performance ranking. If you already have a stable VMess node and a well-maintained subscription, keeping it avoids migration costs. If you have a VLESS endpoint that explicitly uses REALITY and a particular flow setting, choose a client and core that can represent that combination correctly. If the service uses Trojan, confirm how the domain and certificates are maintained. If it uses Shadowsocks, check the method and the UDP capabilities your apps need. In every case, both endpoints must match; don’t change the existing node’s type in the client just to use a preferred protocol.

For desktop, consider v2rayN first; on Android, check whether the endpoint calls for v2rayNG or v2flyNG. If a team uses multiple devices, choose an endpoint that every required device can import and reproduce. If different devices need different configurations, name them by purpose and record their subscription exports rather than relying on one file to meet different clients’ assumptions. For a quick check, manually import a single share link. For long-term use, also verify that the configuration still works after a subscription refresh. This covers both initial setup and later changes or rollback.

Choose System Proxy or TUN Based on the Apps

Apps such as browsers that follow the system proxy can be tested with it first. Some command-line tools and standalone network apps ignore system settings and need an explicitly configured local proxy or another suitable traffic-capture method. If the browser works but a terminal app doesn’t, check the browser and terminal troubleshooting steps to verify the local entry point before changing the remote protocol. Consider TUN virtual adapter only if you need to capture traffic from apps that ignore proxy settings. Check permissions, routes, and conflicts with other network components. TUN is not a remote protocol and cannot make an unsupported flow setting work.

Voice, interactive use, and continuous transfers require different tests. For voice, verify the UDP path and recovery after network changes; a website test is not enough. For short interactions, observe cold starts and retries. For continuous transfers, check sustained throughput, reconnects, and resource use. For LAN sharing, whether another device can reach the computer’s listening port is independent of whether the remote node supports the selected protocol. Share only on trusted networks and limit inbound access. If the local machine connects but other devices cannot, check the listening address, firewall, and port entered on those devices.

Test in a Fixed Order and Record a Rollback Point

On the target device, first verify the imported subscription fields and core, then test one app with as few local rules as possible. Once app traffic is routed, test one destination that should use the proxy and one that should connect directly, making sure a global proxy is not being mistaken for correct routing. Then restore the required DNS and routing settings and check subscription updates, app restarts, and network switching if needed. Record whether a connection succeeds, which apps use the proxy, and the earliest layer where a failure occurs. These details are more useful for diagnosis than a “connected” status in the interface.

If you can’t complete a step, keep the last working group and return to the layer where the failure first occurred: check the source if it fails before import, the core and local listener if it fails before startup, the remote handshake or proxy request if it fails after startup, and the traffic entry if only certain apps fail. Don’t delete the old entry immediately after making a change; wait until the new setup has survived at least one subscription refresh and one restart before making it your default. To repeat the import or connection steps, follow the user guide in order. This handbook helps identify which settings to investigate; it does not replace testing each step in practice.