REFERENCE / PROTOCOLS & CORES

V2Ray Protocol Guide

First confirm that your client and core support the complete connection setup, then compare speed, battery use and maintenance overhead.

Getting Started covers installation, importing a profile and your first connection test. This guide explains protocol fundamentals, compatibility and test results. If you already have a node and just want to connect, follow the tutorial first, then return here to look up the relevant sections.

PROTOCOL LINEAGE / CORE FAMILIES
01 / CONNECTION MODEL

Connection Layers: What Makes Up a Node?

The Client, Core and Remote Server

The client is the management interface. It stores subscriptions, displays nodes, manages routing options and passes settings to the core when connecting. The core opens local listening ports, handles incoming requests, connects to remote servers and implements the protocol. The remote server receives requests according to its deployment configuration. A share link appearing in the list only proves that the client read enough information to create an entry. You still need to verify that the core starts and the remote server accepts requests. Conversely, a missing option in the interface does not necessarily mean the core lacks support; the importer or editor may simply not expose that field.

When troubleshooting, separate the path into three parts: the app to the local proxy, the local core to the remote server, and the remote server to the destination. If an app cannot connect to the local port, the protocol handshake probably has not started. A reachable remote port does not mean authentication succeeded. If authentication passes but only certain destinations fail, check routing, DNS resolution and the destination's response. Logs mean different things at each stage. Do not rely on the status in the client title bar alone: it may only indicate that the process started, not that a connection was established.

Proxy Protocol, Transport and Outer Security

In a node editor, the protocol specifies how requests are encoded and credentials are used; the transport or network type specifies how that data reaches the remote server; security settings specify how the outer connection is protected and how the peer is identified. For example, VLESS is a proxy protocol, WebSocket is a transport, and TLS is an outer security layer. These settings do not automatically match just because the protocol name is the same. A server listening on a common HTTPS port does not prove that it uses WebSocket, a particular path or a particular server name.

Check Connection Fields in a Node
LayerCommon fieldsWhat to check
Network endpointServer address, portA successful lower-level connection does not mean authentication succeeded.
Proxy protocolProtocol, user ID, password or encryption methodSimilar-looking fields are not interchangeable across protocols.
TransportRaw byte stream, WebSocket path, and moreCheck the path, service name and request hostname against the actual deployment.
Outer securityTLS, REALITY, server name, and moreValidate the peer using the selected security mechanism; one security option cannot stand in for another.

The connection address, the server name used in the handshake and the request hostname used by the application transport may all be set to the same domain, but they serve different purposes. The connection address locates the endpoint. The server name is part of the security handshake and is often used to select a site or validate a certificate. The request hostname may be used to route traffic at the transport layer. If the deployment uses separate values for the entry point and site name, do not unify them just to make the fields look consistent. Use the path specified by the deployment behind a reverse proxy; do not guess based on the URL shown in a browser.

Assess Local Traffic Entry Separately from the Remote Protocol

System proxy settings, manually configured local proxy ports and TUN mode determine how traffic enters the client; they do not change the selected remote protocol. With the system proxy enabled, only apps that honor the system setting send requests through it. A virtual network interface also requires attention to routing tables, exclusions and DNS. If an app fails with the system proxy but works after changing the entry method, that points to a change in the traffic path—not necessarily a limitation of the remote protocol. Checking whether the request appears in the core log is more useful than repeatedly switching nodes.

02 / PROTOCOL COMPARISON

VMess vs. VLESS: Authentication, Encryption and Configuration

VMess: Authentication and Data Protection Built into the Protocol

VMess developed as a dedicated proxy protocol in Project V's early ecosystem. It handles user authentication, request headers and data transmission within one protocol. Clients commonly use a UUID as the user ID. Though it looks like an ordinary identifier, it is used for authentication and should be protected like a password. Unlike a channel that simply forwards bytes, VMess has its own message-handling rules. When VMess is also wrapped in TLS, the inner protocol and outer security layer do separate jobs: VMess identifies proxy requests, while TLS protects the connection up to its termination point and verifies the peer.

When maintaining older nodes, it is easy to confuse the relationship between legacy identity options, authentication formats and data-encryption fields. Older importers may retain historical fields, and the interface may show them alongside current options; a field still being present does not mean a new configuration needs it. Modern deployments typically use VMess AEAD authentication. Do not re-enable legacy authentication formats just to make an old share link work. If an old entry is still in use, confirm which format the server accepts and distinguish authentication from data encryption. A longer dropdown list also does not mean automatic selection will successfully negotiate with the remote server.

VMess authentication is sensitive to clock skew. If another device connects to the same endpoint but a device that has just woken from sleep or been offline for a long time keeps failing during authentication, check automatic time sync and the system clock before checking the user ID. A different displayed time zone does not itself cause authentication to fail; what matters is whether both sides' clocks agree. If syncing does not help, check whether the server accepts that authentication format and whether the entry is still valid. Repeatedly changing the transport only obscures the original diagnostic clues.

VLESS: Separate Proxy Requests from Outer Protection

VLESS was initially designed with a lightweight proxy request header. Common deployments identify users with a UUID and rely on TLS or REALITY for a secure channel. In a typical configuration, an encryption field set to none describes only the proxy protocol layer covered by that field. It does not prove that the connection is unencrypted, nor that it is protected. Check the security settings to confirm which outer mechanism is active and what it covers. If an entry uses an encryption feature added by a particular implementation, verify that both sides support the extension rather than relying on assumptions from older configurations.

Keep flow control separate from transport settings. In Xray, for example, xtls-rprx-vision is a flow-control setting for specific combinations, not a universal default for VLESS nodes. If an entry has no value for this field, do not add Vision just because another node uses it. If the entry explicitly includes flow control, do not clear it just to accommodate the editor. The presence of outer security and transport options in a menu only means the interface offers them; it does not prove they work with every flow-control setting.

Keep a Reference Entry When Migrating Older Nodes

Switching from VMess to VLESS is not a rename. The client can establish a VLESS connection only if the remote server actually offers a VLESS endpoint. Request a new node entry from the service operator, keep it alongside the old one and test both cold-start access and sustained transfers. If the entries use different routes, a faster result does not tell you which protocol reduced the time. If your work also depends on per-app routing or remote sessions, confirm that the traffic really went through the new node rather than reaching the destination by another route. After testing, remove the old entry from any automatic selection group so that switching policies do not override the results in the background.

03 / PROTOCOL COMPARISON

Trojan vs. Shadowsocks: Two Models for Protecting Sessions

Trojan: Establish TLS Before Sending Proxy Requests

The classic Trojan setup carries proxy requests inside a TLS session. The client first establishes a TLS-protected connection to the remote server, then sends authentication data derived from a password and the destination address using the Trojan protocol. This gives you a clear troubleshooting boundary: an untrusted certificate, mismatched server name or expired certificate fails before a valid proxy request is sent. Re-entering the password will not fix certificate validation. If TLS succeeds but the server closes the connection, check the credentials and endpoint type, then use the core and server logs to determine what happened.

For long-running deployments that use domains and certificates, certificate renewal and connecting to the expected endpoint often matter more than remembering handshake details. If the same entry works at home but fails on another network, compare the resolved remote addresses and certificate details on both networks. A different endpoint may be out of date even when the hostname looks the same. Fix certificate issues by checking the name, clock or trust chain; do not make disabling certificate verification a routine compatibility setting. A page opening in a browser only proves that the browser's access path works; it does not test Trojan authentication.

Shadowsocks: The Encryption Method and Key Must Match

Shadowsocks is often abbreviated as SS. Early versions focused on providing a lightweight encrypted proxy. A typical configuration consists mainly of the server address, port, encryption method and password or key. Classic deployments protect data at the protocol level and do not require an additional certificate handshake by default. This keeps endpoint configuration relatively simple, but the encryption method must still match exactly. Two algorithm names that look similar are not necessarily interchangeable: they may come from different specifications and require different key lengths, data formats or session handling.

When maintaining configurations, distinguish legacy stream ciphers, common AEAD methods and Shadowsocks 2022, which uses a newer session specification. A regular password, a key encoded to the required length and identity information included in a multi-user setup are not interchangeable formats. If an importer shows the address but drops the method name or full key, check its import support before choosing a similar-looking method at random. The same applies to entries with additional transport parameters: support for basic Shadowsocks on both ends does not guarantee support for the extra transport. Start with a supported baseline combination, then decide whether those extra dependencies are worth keeping.

Test Datagram Support Separately

Shadowsocks can carry UDP-based proxy traffic, and classic Trojan also defines a way to forward datagrams, but classic Trojan carries them over an underlying stream connection. These are two separate questions: whether the proxy accepts this kind of request, and how the lower layer transports it. With an ordered byte stream, packet loss may hold up subsequent data until retransmission completes. Datagram transport behaves differently and depends on endpoint policies and current network conditions. A webpage loading successfully does not confirm that voice calls, real-time apps or datagram-based queries will behave the same way.

Choose a short, repeatable real-world task to test and record the entry method, routing result and app behavior. If web pages work but a real-time app drops out with one local entry method, first check whether its requests reach the core, then determine whether the remote server accepts that traffic type. If the app has automatic fallback, it may switch transports during the test; the interface can appear to work without testing the intended path. Compare protocols on the same network where possible. A single success or timeout is not enough to draw a long-term conclusion.

04 / SECURITY LAYER

REALITY: Parameters and Handshake Troubleshooting

Why It Often Appears with VLESS

REALITY is a security-layer mechanism implemented in Xray. A client may show it as a shorthand label for a node, but the most common configuration is still VLESS as the proxy protocol paired with REALITY as the security layer. In this setup, the proxy protocol handles identity and destination requests, while the security layer handles the outer connection's handshake and verification. Do not change an entry that uses REALITY to ordinary TLS, or turn a working TLS endpoint into a REALITY endpoint just by changing the security option. The remote server must be configured for the selected mechanism and accept the corresponding parameters.

Standard TLS deployments typically verify the peer using a domain certificate and trust chain. REALITY configurations also involve verification material supplied by the server and parameters such as a short ID shared by the client and server. For day-to-day setup choices, the key is not memorizing every abbreviation in the interface; it is confirming that the fields came from the same configuration. One address may host multiple configurations, so an unchanged address does not mean the other fields are still compatible. Keep old and new entries side by side during migration; do not combine parameters from different configuration releases into one connection.

Distinguish the Address, Name and Verification Material

The connection address and port determine where the client connects. The server name is part of the handshake and should match the supplied entry, not be inferred from the address. The public key or corresponding verification parameter shown in the client must match the material used by the remote server. The server's private material does not belong on the client. If a field is provided, identify whether it is for the client or server side. Preserve short IDs as strings so that leading zeros are not lost and empty values retain their meaning. If an imported value differs from the original, check how the importer maps fields.

The client may also offer fingerprint and flow-control options. Here, the fingerprint affects the handshake generated by the core; it is not a username sent to a website or a device identity. Flow control is part of the proxy protocol and transport combination. Choose these options based on the overlap between the service's configuration instructions and the core's capabilities. A familiar-looking entry does not mean every field can be ignored; likewise, one successful edit does not prove the setting works with other endpoints.

Narrow Down the Cause by Handshake Stage

First determine whether the core fails to start or starts but cannot connect to the remote server. For startup failures, look for unrecognized options, invalid parameter values or incompatible combinations. For connection failures, check in order whether the lower-level connection succeeded, the security handshake completed and proxy authentication passed. If the log only says that the connection was closed, do not infer from a generic error that the public key or short ID is definitely wrong. Use a verified entry on the same network for comparison to see whether the problem is limited to one configuration. If server logs are available, compare both sides by timestamp.

If the problem started after a subscription update, keep the old entry and compare the updated security type, server name, verification material and flow control. If the old core runs other nodes but the new entry reports an unsupported type, check which core the current client instance actually launches—not just which cores are installed on the machine. When asking for help with logs, share the failure stage and only the necessary field types. Redact credentials, subscription URLs and endpoints that do not need to be public. This leaves enough information to distinguish an import, parsing or handshake problem without exposing a complete node to strangers.

05 / IMPLEMENTATION BRANCHES

V2Fly vs. Xray: Feature Overlap and Migration Limits

Shared History Does Not Mean Configurations Are Interchangeable

Project V provided an early framework for combining proxy, transport and routing modules. V2Fly continues community maintenance of the V2Ray core; Xray forked from that codebase and has developed its own features for transport, security and flow control. The two cores therefore share some concepts and protocol names, but their implementations and release schedules differ. Lines in the lineage diagram above indicate that a corresponding implementation exists in a core family; they do not mean historical versions, transport combinations and protocol extensions are interchangeable. For VLESS entries in particular, the protocol name alone does not tell you whether flow control and outer security are both supported.

Both cores often have inbound, outbound, routing and transport settings, but the default behavior of a field with the same name, the available enum values and the field's position in the configuration all depend on the current implementation. Different versions may also parse configurations differently: one may report an unknown option, while an outer tool may omit unrecognized fields when generating the configuration. The interface can save successfully but produce a different runtime result. So a JSON file passing a syntax check does not prove that migration is complete. Check the settings actually in effect and verify that the same request uses the intended outbound.

Choose a Client by Platform and Core Requirements
ClientPlatformWhat to check
v2rayNWindows、macOS、LinuxDesktop pick; check which core the current entry actually selects and launches.
v2rayNGAndroidUses Xray; confirm transport, security and flow-control settings were all imported.
v2flyNGAndroidUses V2Fly; suitable for nodes confirmed compatible with this core.

Start Migration with a Minimal Node, Then Move the Policies

Once you have a node entry, choose a package for your system from the Get a Client page. Keep the original configuration as a rollback option; do not overwrite the new client's data directory with the entire old configuration. First import a basic node supported by both cores, check the remote address, user details, transport and security mechanism, then test a single outbound. Only after that should you migrate domain rules, IP rules, default outbound, DNS policies and resource files. For options specific to one core, look for equivalent functionality first. If the semantics do not match, keeping the original core is safer than deleting settings at random.

A domain rule may look identical but match an IP rule first in the new core because DNS resolution happens at a different stage. Or it may route to the default path because an outbound tag was renamed. Migration checks should confirm not only that requests succeed, but also which outbound they actually use. If multiple rules share resource files, verify that those files exist and have loaded; a missing file should not lead you to blame every error on the node. With a large configuration, add rules back gradually around a repeatable request to identify which change altered the behavior.

Track Client and Core Updates Separately

A client update may change subscription parsing, default options or how it generates configuration. A core update may change supported features or parameter validation even if the interface looks exactly the same. When behavior regresses, record the client and core versions separately, along with the platform, entry mode and actual core shown in startup logs. Comparing against the original entry from before import can help distinguish a parsing regression from a runtime change. Once you have confirmed that the old combination still works and can be safely restored, test the updated capabilities one at a time. Avoid combining a subscription refresh, client upgrade and core switch in a single operation.

06 / MEASUREMENT

Connection Speed, Resource Use and Mobile Battery Life

Break Speed Down into at Least Three Metrics

A slow first visit may be caused by DNS lookup, the remote connection, the security handshake or the app's response time. Page reloads can also benefit from connection reuse and caching. Measure cold-start time to first byte, sustained throughput and recovery after interruptions separately. A single latency number is just one measurement. A regular ping shows some aspects of network round-trip time but does not test proxy authentication or return a response body. Even a real connection test that uses the proxy path does not prove long-term transfer stability. For measurement details, see How Latency and Speed Tests Work.

VMess's internal protocol processing, Trojan's TLS handshake, VLESS's outer security and Shadowsocks encryption each serve different purposes; they do not provide a basis for ranking protocols across different routes. An extra round trip has a greater effect on first-byte time over a high-latency link. During sustained transfers, bottlenecks may instead come from server throttling, device performance, retransmission behavior in the transport or the destination site. For a fair comparison, use the same device and access network, similar remote endpoints and the same test target. If endpoints are not comparable, say that one route works better for this use case rather than generalizing to the protocol as a whole.

Run a Short Test Through a Known Local Proxy

If the core exposes a SOCKS proxy on the loopback address, use the command below to test a complete web request. The example uses port 10808; check the client and replace it before running. This command works with curl versions that support the option. In Windows PowerShell, you can call curl.exe. With socks5h, curl sends the destination hostname to the SOCKS proxy for resolution. The example makes one small request. Its output is the total time as seen by curl, not the isolated duration of any protocol handshake.

curl --proxy socks5h://127.0.0.1:10808 --max-time 20 --silent --show-error --output example-response.html --write-out "HTTP %{http_code}\nFirst byte %{time_starttransfer}s\nTotal time %{time_total}s\n" https://example.org/

The command writes the response to example-response.html in the current directory, so run it somewhere you can create that file. If it cannot connect to the local port, check the core's listening settings first; there is no need to change the remote entry. If a response comes back, check the client log to confirm that the request used the outbound you intended to test, rather than going direct under the default routing rules. Repeat the test a few times and record results for both a cold connection and an existing session. To compare download throughput, use files of the same size from a fixed source. Do not switch nodes during a speed test, or a single run may use different paths.

Separate Idle Power Use from Workload

Core CPU use depends on the encryption implementation, device hardware, number of concurrent connections and packet-processing path. Memory use is also affected by buffers, rule sets, connection reuse and apps running in the background. On mobile devices, distinguish power use during active transfers from standby drain. Weak signals cause more retransmissions on cellular connections, while frequent probes, heartbeats and background requests can keep the radio in a higher-power state. Even if two protocols have similar processing costs per unit of data, different wake-up frequencies can produce noticeably different standby results.

When comparing on a phone, keep the network type, screen use, client entry mode and background app state consistent. First compare the same length of screen-off standby, then test a common foreground task separately and record reconnections. If traffic pauses with the screen off, check background permissions and network switching before blaming the protocol for poor battery life. If battery use rises only with rapid checks or automatic switching enabled, reduce unnecessary probes and test again. This produces a repeatable result for your device, not a battery-life ranking inferred from protocol labels.

07 / DATA EXCHANGE

Subscription Formats: Importing Does Not Guarantee Compatibility

Subscription URLs, Response Bodies and Node Entries

A subscription URL is an address that a client periodically fetches; it is not the server address used for a proxy connection. The response may contain multiple share links, text with those links encoded in Base64, or a structured document containing rules and groups. A single share link usually describes one entry. Base64 is an encoding, not a way to protect credentials; treat authorization data recoverable from a subscription response as you would the original link. Do not post subscription URLs or node text containing access credentials in public forums.

A URL beginning with HTTPS may return a subscription, a login prompt, an expired page or download instructions. Opening the URL in a browser only proves that the server returned a page; it does not verify that the response is in a format the client can read. If a refresh reports success but adds no nodes, check whether the subscription has expired, whether the server returned the expected format and whether the response was redirected to a login page. Some services return different content depending on request details, so the page shown in a browser may not match what the client receives. Ask the service operator to confirm the delivery format.

Identify Common Delivery Formats
Delivery formatTypical useCommonly missed details
Single share linkAdd one nodeNot a way to update an entire group.
Plain-text or encoded list of linksBulk import and refresh entriesDecoding the text does not guarantee that every protocol or extension field will be recognized.
Structured configuration documentDescribe nodes, groups or a complete runtime policyExtracting nodes does not mean routing, DNS and selection policies are portable.

Four Checks for a Successful Import

First confirm that the response was retrieved, then that it parsed into the expected entries. Next check key node fields, and finally verify a live connection. The first two checks concern the subscription and interface; the last two involve the core and remote server. Spot-check the protocol, transport, security layer, server name and flow control in the editor, paying special attention to whether empty values were present in the original. Do not blindly decode percent-escaped paths, parameter values separated by symbols or non-ASCII node names a second time. A readable name after import does not prove that security settings were preserved exactly.

Desktop v2rayN and Android v2rayNG organize subscription groups and update controls differently. See How to Import Subscription Links. If the same URL can only be used on one client at a time, compare the same entry first rather than importing mixed subscriptions and judging by node counts. Differences may come from filtering, deduplication or unsupported link types. Even matching counts do not rule out missing extension fields in individual entries. View full credentials only on your own devices; when reporting an issue, focus on field names and behavior.

Decide What to Preserve Before Converting

Subscription conversion maps data between two formats; it cannot add protocol capabilities that the target core does not implement. If the target format describes only nodes, you will need to handle policy groups, DNS rules and local traffic settings from the source separately. Before converting, identify which fields must be preserved and request a delivery format supported natively by your client whenever possible. If conversion is unavoidable, verify a small set of representative entries locally first and confirm each can connect on its own before applying the conversion in bulk. Avoid sending access URLs to online conversion services of unknown origin.

If an update overwrites manual changes in a subscription group, copy an entry into a separate group as a reference and clearly label its source after testing. When old and new entries share a name, compare the endpoint and complete connection settings; a display name is only a human-readable label, not a reliable long-term identifier. After a bulk update, test one basic node and one with extension settings to check that both standard and special fields were preserved. Do not change conversion rules and local routing in the same troubleshooting pass.

08 / CHOOSING A SETUP

Choose Protocols for Your Use Case and Verify the Configuration

Using an Existing Service: Prioritize a Complete Match

When using an existing service, list the connection setups it actually provides, then choose a client for your platform. For desktop, start with v2rayN. On Android, check v2rayNG support first if you need Xray-specific security or flow control; consider v2flyNG for entries confirmed to work with V2Fly. If you receive several entry types, you do not have to choose the one with the most fields. Shortlist combinations that meet your protocol, transport, security and datagram requirements, then test them on the target device. If only one combination works, a complete configuration verified by the service operator matters more than theoretical performance.

If you already have stable VMess nodes and a new subscription adds VLESS, that does not mean you need to migrate the entire old group. First check whether the new combination meets a real need, such as compatibility with a particular device or an upgrade plan confirmed by the service operator. If the only change is the name and the existing nodes are still maintained, keeping a known-working setup reduces migration risk. Conversely, if the server operator stops maintaining an older configuration, test the newly issued entry rather than carrying over fields from the old one.

Self-Hosting: Factor in Ongoing Maintenance

If you manage the service yourself, list the devices and cores you need to support before deciding what the server side can maintain long term. If you already have a reliable certificate renewal and domain management process, consider Trojan over TLS or a compatible VLESS setup. To keep configuration dependencies limited, consider a Shadowsocks method supported by both ends and verify datagram requirements. REALITY or specific flow control requires an Xray environment and a repeatable way to distribute configurations. Every setup has its own maintenance work; fewer settings in one part do not necessarily make the whole system easier to manage.

When using both desktop and mobile devices, keep a baseline setup that you can verify on both. It helps distinguish a general remote service outage from an extension that fails on a particular device. If one deployment serves different purposes, keep a small number of clearly tested entries rather than making every node handle every role. For web and document use, prioritize first-visit performance, recovery and consistent DNS resolution. For sustained transfers, add throughput and reconnect tests. For real-time apps, include datagram support and recovery after network switching in your evaluation instead of relying on speed-test results alone.

Keep Test Results Reproducible on Another Device

Record the platform, client, actual core, node connection settings, how the app enters the proxy, and the network and time period used for testing. In the first round, confirm the connection with simple routing. In the second, restore your usual rules and background settings and check that the app uses the intended route. Where needed, also test recovery after the screen locks, switching between Wi-Fi networks and refreshing the subscription. Define success in observable terms: for example, key fields remain unchanged after a refresh or a new request succeeds after the network recovers—not just a vague “connection works.” Record the test conditions so you can compare them with a new configuration later.

When something fails, classify the problem instead of guessing: no relevant log entry points back to app traffic routing; a dial error means check the endpoint; a security handshake failure means check the verification fields; if the connection is established but only some apps fail, inspect routing, DNS or the datagram path. For setup instructions, return to Getting Started. For common system proxy, installation and permissions issues, see Troubleshooting. If the issue began after an update, retest the saved baseline first, then compare one change at a time. This produces a setup decision you can use now and verify again after changing devices or updating the core.

Download V2Ray Client