Shadowrocket Protocol Reference

01 / CONNECTION MODEL

Protocol layers and the order for checking settings

Protocol type is only one part of the connection

A request typically passes through local routing, server address resolution, the underlying connection, protocol authentication and forwarding to its destination. Names such as Shadowsocks and VMess describe how the client and server exchange proxy requests; they don't tell you how far away the server is, how much bandwidth is available or how congested the connection is. Two configurations using the same protocol can perform very differently. Conversely, two different protocols can feel similar on the same network with comparable server conditions.

Check settings by layer: server address, authentication, transport, security and routing. The server address determines where the connection goes. A password, UUID or key identifies the connection. TCP, UDP and any additional transport determine how data is carried. TLS provides encryption and certificate verification where applicable. Rules decide which requests use the connection. Passing one layer doesn't mean the next one works, so a latency result alone can't confirm that a connection works end to end.

Use the supplied details; don't guess defaults

Before selecting a type in Add Server, check the protocol specified in your existing connection details. The same port doesn't mean the same protocol, and using TLS doesn't automatically make a connection Trojan. After importing a subscription, check that the type, server and port make sense, then verify authentication fields and transport options. Field names and order vary by type; refer to what the app currently displays. Don't add a value just because it appears in an online example if your connection details don't include it.

The server hostname, TLS SNI and WebSocket Host may be the same or different, depending on the deployment. The hostname resolves the connection address; SNI selects a service during the TLS handshake and is usually checked against the certificate name; Host routes the application-layer request. Changing one doesn't necessarily change the others. They aren't interchangeable server addresses.

UDP support doesn't guarantee every app will work

“UDP support” depends on at least four things: the client's protocol implementation, server forwarding permissions, the network in between and the destination service. Some protocols carry UDP data over a stream, some use datagrams directly, and others require additional extensions. You can't predict how voice calls, real-time apps or HTTP/3 will work from a protocol name alone. Test the apps you actually use—even if regular web browsing works—so you don't mistake one successful request for full connectivity.

In the following sections, “choosing a protocol” means choosing among configurations you already have and that your server explicitly supports. Switching the type in the client menu doesn't change the server's protocol. If the imported configuration differs from the original details, first check that the share link was complete and that all fields were retained during import. Then reimport or ask the provider to confirm the details instead of repeatedly adjusting the wrong type.

02 / SHADOWSOCKS

Shadowsocks: encryption methods and forwarding limits

Proxy forwarding with fewer protocol layers

Shadowsocks establishes an encrypted proxy connection between the client and server, sending the destination address and app data to the server for handling. It isn't a full virtual LAN protocol and doesn't automatically route every request on the device. Shadowrocket receives traffic on the device and uses Global Routing and the current configuration to decide whether to send it through the selected Shadowsocks connection. The protocol and local traffic routing serve different purposes.

Fewer layers can reduce some handshake and processing overhead, but that doesn't guarantee faster speeds. Actual throughput still depends on the encryption implementation, device load, server performance and network quality. Changing the encryption method usually won't fix an overloaded server. If the connection uses additional transport mechanisms, factor in their overhead too; the protocol name alone doesn't reveal the actual path.

Check Method and Password together

The essential details are the server, port, encryption method and password. Method isn't a performance preset you can choose freely; both ends must use the same algorithm and message format. AEAD methods provide data integrity checks as well as confidentiality, and different methods may use different key lengths and derivation schemes. A correct Password paired with the wrong Method can still cause authentication or decryption to fail. The connection may appear to come up but receive no useful response, rather than showing an explicit “wrong password” error.

For protocol variants that require a fixed-length encoded key, don't enter an ordinary short password as the key. If the original details include multiple authentication parts or a specific format, preserve them in full, including separators. When copying, check for trailing spaces, line breaks and punctuation substituted by the keyboard. Retyping isn't necessarily more accurate: copy from a trusted source, then compare each imported field with the original.

A working TCP connection doesn't confirm UDP

Shadowsocks can carry different types of app traffic, but UDP availability still depends on both ends and the network. A web page loading successfully usually confirms only part of the path. If voice calls fail or a real-time app misbehaves on a particular network, first check that the server allows UDP forwarding, the client's related options match the connection details, and the Wi-Fi or cellular network can carry the required traffic. Don't start by changing the password or encryption method.

UDP datagrams don't normally have the same reliable-delivery guarantees as TCP; whether lost packets are retransmitted depends on the application layer. A test can report low latency while a call still stutters: latency reflects the requests that got a response, not whether every datagram arrived on time. Check packet loss, jitter and sustained sessions—not just the lowest latency figure.

How to assess performance on iPhone and iPad

If all existing configurations work, Shadowsocks makes a useful baseline for comparison because its structure is relatively straightforward. For short web requests, check the initial response and repeat visits. For large files, check sustained throughput. For real-time apps, observe jitter over an extended period. Don't compare configurations in different regions or with different egress routes and attribute every difference to the protocol. Server location and load often matter more than the number of protocol layers.

To reduce battery use, first cut unnecessary continuous transfers and repeated failed reconnects, then look at the impact of encryption processing. An idle connection kept open and a sustained high-throughput download drain power for different reasons. The former is more affected by background wake-ups and network keepalives; the latter also involves wireless transmission, encryption and changes in device temperature. One battery percentage reading isn't enough to diagnose a protocol issue.

03 / VMESS & VLESS

VMess and VLESS: authentication, transport and TLS

Similar names, but not interchangeable types

VMess combines proxy request authentication and data handling within its own protocol. VLESS uses a more streamlined request and identity format, relying more on its accompanying security transport for connection protection. Both can use different transports, so if the details mention TCP, WebSocket or TLS, check the specific combination. Changing a VMess entry to VLESS doesn't automatically convert its authentication, message format or server configuration.

VLESS doesn't provide data encryption equivalent to TLS on its own. If a configuration uses VLESS, checking the UUID alone doesn't confirm that the security layer is in place. Verify that the required security mechanism and its settings are enabled. If the details don't specify them, get the deployment information rather than disabling certificate verification based on a guess. Check that the current client and server actually support any relevant extensions.

UUID, time and authentication details

A UUID is a common identity field in these configurations and should be treated as sensitive. It isn't a server hostname and shouldn't be confused with a display name. VMess authentication involves time conditions, so a significantly incorrect device clock can cause authentication to fail. If the same details work on another device, check that automatic time setting is working before reinstalling the app. VLESS uses a different authentication mechanism, so VMess troubleshooting advice doesn't always apply.

If the imported details include additional authentication or flow-control parameters, a UUID alone may not be enough to connect. Some fields in older configurations may not apply to the current combination. Don't fill in arbitrary values just to make the form look complete. Check the server's connection instructions to confirm whether a field applies to the protocol in use; if it belongs to a different transport or security combination, don't reuse it.

What WebSocket adds to the checklist

WebSocket can carry a connection in an application-layer session, often as part of an existing HTTP forwarding setup. That adds conditions such as the path, Host and intermediate forwarding behavior. Paths usually need to match exactly; capitalization, a trailing slash or a missing prefix can stop the server from handing the request to the right handler. Receiving an HTTP response doesn't prove proxy authentication succeeded—it may just be a response from a regular website.

When TLS is used on the outer connection, the security handshake happens before the WebSocket connection and proxy protocol exchange. Certificate, path and UUID errors occur at different stages, so diagnose them by layer. If an intermediary closes idle long-lived connections after a timeout, the connection may drop after sitting unused. That's different from failing authentication at the outset and won't be fixed by making the password longer.

Performance trade-offs and troubleshooting order

An extra transport layer can add handshakes, message overhead or processing by intermediate devices. It may also be essential to the server deployment, so don't disable it on the client just to reduce overhead. Compare complete, correctly configured combinations. Short-lived connections are more sensitive to setup costs; long-lived connections are more affected by bandwidth, packet loss and multiplexing. One latency test can't represent both.

Check address resolution, port, TLS, transport path, authentication and access to the actual destination, in that order. If all destinations fail, start with the connection layers they share. If only one hostname fails, check the rules, DNS resolution and destination status. If a configuration started failing after a subscription update, check whether its transport options changed and whether the update overwrote manual edits. Don't rely only on your memory of the previous settings.

04 / TROJAN · HTTP · SOCKS5

Trojan, HTTP and SOCKS5: security layers and proxy behavior

Trojan requires a correctly configured TLS connection

Trojan places the proxy protocol inside a TLS connection and uses authentication details for the server to identify proxy requests. Keep the outer TLS layer separate from the inner authentication when diagnosing it. A TCP connection to the server address only confirms that the port is reachable. Even after the TLS handshake succeeds, authentication and destination forwarding must still work. The Password, SNI, port and server deployment must all be correct; a password alone isn't enough.

Certificate verification confirms the identity of the endpoint. For a name mismatch, check the supplied SNI, server hostname and certificate coverage. For an expired or not-yet-valid certificate, check the device clock and server certificate. Routinely skipping verification removes this layer of identity protection and can hide the actual configuration problem. Correct the name, certificate chain or time instead of merely suppressing the warning.

An HTTP proxy doesn't mean the destination website uses HTTP

HTTP proxy describes how the client communicates with a proxy server. For a regular HTTP destination, the proxy can handle the request directly. For an HTTPS destination, the client commonly uses CONNECT to establish a tunnel to the destination, then sends the website's TLS session through it. So “HTTP proxy” doesn't mean the browser can only open regular HTTP sites, nor does it mean the client-to-proxy connection is necessarily protected by TLS.

If the connection details specify an HTTPS proxy, there is also a TLS connection between the client and proxy; check its certificate and name. A username and password are commonly used for proxy authentication, but authentication alone isn't encryption. To understand the security boundary, ask separately whether the device-to-proxy connection is encrypted and whether the app-to-destination connection is encrypted. A secure connection indicator in a browser doesn't mean every layer in between is protected in the same way.

SOCKS5 provides general-purpose destination forwarding

SOCKS5 negotiates the destination address, port and requested operation with the proxy server, and can use either a hostname or an IP address. Basic SOCKS5 doesn't include TLS-level transport encryption, and username/password authentication doesn't replace a secure channel. Use it when the server deployment explicitly provides this interface. Before choosing it, understand the network it will run over and any additional protection in place; fewer settings don't automatically make it a better fit for mobile devices.

SOCKS5 UDP forwarding involves additional negotiation and a datagram path. Whether it works depends on the server implementation, client settings and network reachability. A successful TCP request doesn't confirm that a UDP association was established. Where a hostname is resolved also matters: if it's converted to an IP address locally, the proxy may not receive the original hostname. Consider name resolution and hostname-based rule matching as part of the full request path.

Choosing based on your existing setup

If an organization or your own server already provides a specific proxy interface, configure it to use that protocol rather than switching to a more familiar name. The same listening port can use different handshake formats. For a Trojan configuration with a defined certificate and hostname, check TLS carefully. For HTTP or SOCKS5, confirm the interface's security boundary, authentication requirements and permitted destinations.

During troubleshooting, a rejected CONNECT request, failures on only certain ports or repeated authentication failures may point to server access policies. Destination restrictions aren't a weak wireless signal or an issue common to every protocol. Note the destination type and the stage where the error occurs to distinguish authentication failures, unreachable destinations and requests rejected by server policy. Don't change every setting at once without evidence.

05 / WIREGUARD

WireGuard: keys, tunnel addresses and IP routing

A shift from proxying destinations to tunneling IP traffic

WireGuard works differently from the destination proxies covered above. It carries IP packets through an encrypted tunnel, with the two peers communicating based on their keys and peer details. Its design uses a streamlined protocol and fixed cryptographic suite rather than a long list of negotiable algorithms. For Shadowrocket users, that shifts the focus from proxy credentials and destination formats to keys, Endpoint, tunnel addresses and reachable network ranges.

WireGuard uses UDP as its underlying transport, so the outer UDP path must be available. The tunnel can carry IP traffic from different apps, but that doesn't mean the external network allows all UDP traffic. If the same configuration works on Wi-Fi but fails on cellular, check the outer path and address resolution before changing rules for destinations inside the tunnel. TCP working for an app inside the tunnel and UDP being reachable outside it are separate things.

Don't mix up the direction of Private Key and Public Key

The Private Key identifies this device and must be kept secret; the Public Key lets the other peer identify it. The peer public key in the client configuration must match the server's identity, not the client's own public key. If the connection details include a Preshared Key, it must match at both ends too. Keys usually have a fixed encoding format. Missing characters or added spaces can break the connection, while sharing a private key in a public screenshot creates a security risk.

Endpoint is the external address and port used to initiate communication, not an address inside the tunnel. An Address setting describes this device's address within the tunnel and must match the network plan. Putting the public Endpoint address in a tunnel address field, or assigning conflicting internal addresses to the two ends, can allow a handshake but prevent forwarding. Check what each field represents; they may all look like IP addresses, but they serve different roles.

Allowed IPs and local routing rules aren't the same table

In WireGuard, Allowed IPs are used both to associate addresses with a peer and to select an outbound peer. They aren't a list of remote websites and don't directly replace Shadowrocket Rule. Local client rules first determine whether a request enters the connection. Once it enters WireGuard, the tunnel address ranges and server forwarding determine whether it can reach its destination. A broad range on one side doesn't automatically authorize the same range on the other.

To access a remote private network you already have, check the destination subnet, return route and server forwarding permissions. If your local Wi-Fi and the remote network use the same private subnet, their addresses may overlap: the same destination can appear to be both a local and a remote device. Resolve this through network planning and routing rules; changing DNS alone won't fix every conflict. Before making changes, confirm which side owns the address.

Keepalive, MTU and mobile networks

Keepalive can help maintain network mappings when a deployment needs to be reachable from outside or keep a mapping active, but more frequent keepalives increase background network activity. Don't assume an arbitrarily short interval is a general optimization. When a mobile network changes, the external address and mapping may change too. Even when the protocol can update peer information, the current network must still allow data through and the system may need time to restore the path.

MTU describes the maximum packet size that can be carried. Encapsulation adds overhead, and if the path can't accommodate the resulting size, small requests may work while large responses stall. First rule out server and destination issues, then adjust the setting carefully based on the actual path and keep the original value. Not every timeout is an MTU problem. Setting the value too low increases packet count and processing overhead and doesn't guarantee better speeds. Verify changes against a repeatable destination.

06 / HYSTERIA2

Hysteria2: QUIC, bandwidth settings and packet loss

A connection built on QUIC

Hysteria2 uses a QUIC-based transport. QUIC runs over UDP and provides mechanisms for secure connections, stream management and reliable delivery. It can manage multiple streams within one connection framework. Unlike carrying everything in a single ordered byte stream, delivery at the transport layer can be more independent across streams. They still share link bandwidth, congestion feedback and device resources, so each stream doesn't have its own dedicated network capacity.

This design is often discussed for paths with high round-trip times or packet loss, but that doesn't mean “packet loss always makes it faster.” Loss can be caused by congestion, a weak wireless signal, network restrictions or a changing route. Sending behavior needs to adapt to those conditions. If the outer UDP path is unreliable, a protocol built on it can't make the network reachable by itself. Both the protocol's capabilities and the network's conditions must allow the connection.

Check authentication, TLS and the server name

Hysteria2 connection details usually include a server, port, authentication information and TLS settings. Authentication and certificate verification are separate: the first lets the server check the client's access; the second lets the client verify the server's identity. Confirm the relationship between Server, SNI and the certificate name against the deployment details. Using QUIC doesn't remove the need to check certificates or make any arbitrary name valid.

If the deployment uses additional obfuscation settings, check that both ends use the same type and parameters. Obfuscation isn't another name for the authentication password or a performance switch that works with any string. Don't mix Hysteria2 settings with those of another protocol or protocol generation just because their names look similar. If an imported configuration has an unexplained blank field, check the original details instead of copying fields from another type.

A bandwidth setting isn't a speed guarantee

Some configurations include upload and download bandwidth settings for sending behavior or bandwidth negotiation. They describe operating conditions or control inputs, not a purchased entitlement or guaranteed device throughput. Pay close attention to units: bits per second and bytes per second aren't the same. If the app and connection details use different units, convert them before entering a value, following the field's requirements to avoid a mistake by a factor of eight or more.

Setting bandwidth far above the available capacity won't increase the physical link's speed. Sending too aggressively may instead build up queues, increase latency and packet loss for other apps, or cause significant speed swings. Setting it too low can limit throughput. Whether these fields are needed and how they work in a particular setup depends on both implementations and deployment details. Don't treat someone else's values as universal recommendations.

Assessing additional costs on mobile devices

QUIC requires resources for encryption, packet management and recovery. Repeated retries over UDP in a weak-signal or restricted network can also increase wireless activity and battery use. More heat during high-throughput transfers can't be attributed to a protocol name alone; the screen, destination app and sustained data transfer may all contribute. For a fair comparison, keep the task, screen brightness, device temperature and test duration roughly consistent.

If an existing Hysteria2 configuration repeatedly fails on one network but works on another, first compare the networks and note whether the handshake completes. If the handshake succeeds but sustained transfers are unstable, check bandwidth settings, server resources and packet loss along the path. If only one app has a problem, confirm that its requests actually use this connection and that the destination service is working. Don't infer that the entire protocol is unusable from one symptom.

07 / IOS & IPADOS

iPhone and iPad: speed, battery use and network changes

Break speed down into three observable parts

The first is connection setup time: address resolution, the connection to the server and the security handshake. The second is the destination's first response, including the time the server takes to reach it. The third is sustained throughput, which depends on bandwidth, packet loss, congestion control and processing capacity at both ends. Everyday browsing may depend more on the first two; large downloads are more affected by the third. One latency figure can't represent all three or predict video, call or interactive performance.

Interpret Connectivity Test results in light of the test method. Some methods check whether the server is reachable; others may try to reach a destination through the proxy. Without knowing what was measured, don't treat the number as the full round-trip time for an app or service. A region label is just a note, not a substitute for measuring the actual path. For more on interpreting tests and server regions, see Latency, server region and protocol type.

Battery use comes from the whole connection chain

A connection involves app traffic, system networking, protocol encryption, wireless transmission and necessary background maintenance. At high throughput, both processing and wireless transmission use more power. While idle, keepalives, automatic checks and failed reconnects may be more significant. The battery usage percentage also depends on how much other apps are used, so percentages from two different days can't establish which protocol is more efficient.

For a meaningful comparison, let the device return to a similar temperature, keep the network, screen brightness and task consistent, run tests for a similar length of time, and record battery change, data transferred and connection failures. Results are hard to interpret if one test is while charging, another is in Low Power Mode, or background apps are syncing large amounts of data. Look for sustained unusual activity rather than a tiny percentage difference over a few minutes.

Global Routing changes the conditions of a test

Global Routing offers Config, Proxy and Direct modes for configuration-based routing, proxying and direct connections. With Config, rules may send a particular destination directly. When using Proxy for comparison, remember that the client has boundaries in how it handles system and special traffic. Direct mode can't test whether a remote proxy works. Before comparing results, confirm that the same destination takes the same kind of route; otherwise you're measuring routing differences, not protocol differences.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

The rules above show an example: use PROXY for destinations under example.com, DIRECT for the specified private subnet, and FINAL for everything else. The example doesn't include a connection server, so it can't connect on its own. Rules are matched in order, so earlier conditions affect whether later ones are reached. Before editing rules, confirm which Config is active; see How configuration file sections work if needed.

Why check again after switching networks?

Switching from Wi-Fi to cellular can change the local address, default route, DNS and network mappings. Even if the old connection still appears enabled, its transport path may need to be re-established. QUIC and WireGuard have mechanisms for handling some path changes, but success still depends on both implementations and the current network. No session is guaranteed to stay uninterrupted. Wait for the path to settle, then test with a new request; this is easier to diagnose than switching repeatedly in quick succession.

On Demand controls when a connection is triggered under specified conditions; it won't fix an incorrect password, an invalid certificate or an unreachable server. If a connection keeps restarting after a network change, check the automatic trigger separately from protocol retries, and see whether the rules changed or the network is still connecting. For related Settings, see Features and settings. Avoid changing every automatic connection condition to address a temporary drop.

Also distinguish IPv4 from IPv6 paths. A hostname may resolve to addresses in different families, and the address used can change after a network switch. If only some destinations fail, check the resolution results, server egress and relevant routing conditions instead of immediately disabling an address family. DNS only affects name resolution; it can't fix certificate, protocol authentication, server permission or destination service issues.

08 / SELECTION & DIAGNOSTICS

Choosing a protocol and troubleshooting by layer

Check which options can work before comparing performance

Start by checking what your existing server supports, not by ranking protocols. If you have one valid configuration, get it working correctly first. If you have several, rule out options with incomplete authentication, unclear security settings or incompatible network requirements. Then compare the remaining configurations against the tasks you actually use. A protocol name can't compensate for an unreachable server, congested egress or incorrect routing, and the client can't make a server use a protocol it wasn't set up for.

Use repeatable tasks for a fair comparison

Choose two or three destinations you actually use, then test short requests, sustained transfers and real-time tasks where relevant. Keep the network, device and approximate time of day consistent for each round. Confirm that the destinations take the same route before switching between existing configurations. Record typical results and failures rather than saving only the best run. If the configurations use different server regions or servers, describe this as a comparison of the overall connection experience—not proof of protocol performance alone.

If battery life matters, compare idle maintenance and active transfers while keeping the connection stable. A configuration that repeatedly fails and reconnects may be a poor choice for long sessions, even if it's occasionally fast. For interactive tasks, observe responsiveness under load; for remote subnet access, check addressing and permissions first. Different tasks have different priorities, so there is no protocol ranking that fits every network, device and destination.

Narrow down failures by checking four layers

First, check the local network: is the device connected to Wi-Fi, does a regular direct connection work, and has the network switch finished? Second, check the server connection: the Server resolution result, Port and required TCP or UDP path. Don't change the UUID yet; authentication details can't fix an incorrect address. If the configuration only fails on one network, leave it unchanged and compare against another network first.

Third, check security and authentication: TLS name, certificate, device time, and whether the Password, UUID or key is complete. If logs distinguish the handshake from authentication, troubleshoot the stage where the failure occurs instead of calling every error a “connection timeout.” Fourth, check forwarding: Global Routing, the active Config, destination DNS, server permissions, UDP conditions and return routes. If the handshake succeeds but the destination fails, the problem is usually beyond the server port checked at the first step.

Updates, rollbacks and troubleshooting notes

A Subscribe update may change server fields or entry contents, and manual edits may not be kept. If something changes after an update, compare the actual fields rather than just the display name. Don't paste a subscription URL into a public discussion; it may contain access credentials. For troubleshooting notes, record the protocol, network, failure stage, destination type and redacted error details. Private keys and full authentication details aren't needed for public diagnosis.

If a change doesn't help, restore the original value before testing another theory. When asking for help, “what network, which destination, when it failed, and what you've ruled out” is more useful than a pile of unorganized screenshots. For first-time imports, follow the full process in the Getting Started guide. For purchases, reinstalls and restoring a previous purchase, see the Getting the App guide. Keep App Store access issues separate from protocol connection troubleshooting.

Keep a tested baseline configuration and know its protocol, authentication method, security layer and routing mode. Understanding these boundaries is more useful than memorizing one set of parameters: the configuration must match the server, tests must reflect real tasks, and conclusions must stay within the network conditions you actually observed.