Shadowrocket Protocol Guide

How protocols, transport, and routing fit together

First, identify which layer the settings describe

Before choosing a protocol, break a connection into distinct parts. The server address specifies where to connect; the port identifies the listening endpoint; the protocol defines how the two sides recognize requests and verify identity; the transport determines how data is carried; and routing decides which requests use the connection. Confusing these layers can lead to a connection that fails even when the address and password are correct. Check the complete set of settings, not just a protocol abbreviation in the connection name.

For example, two VLESS setups may require different transport types, TLS settings, and additional parameters. Matching type names only means both sides are attempting to use the same kind of request format; it does not mean the connection details match. Importing a subscription usually preserves more fields, but check the imported settings as well. If the app does not recognize a parameter, check which options it actually provides, then ask the administrator of your existing server. Don’t replace a field with a similar-looking one on guesswork.

There is no speed or battery ranking that applies in every setting

Protocol design can affect handshake count, data encapsulation, and retransmission behavior, but actual speed also depends on server load, round-trip time, packet loss, wireless signal, and the destination website. Short web requests are more sensitive to handshake and resolution overhead; large file transfers are more affected by congestion control and available bandwidth. A single latency result reflects only the conditions of that test. It cannot replace a full access test or predict throughput throughout the day. For a useful comparison, keep the device, network, destination, and test time as consistent as possible.

On iPhone and iPad, battery use depends on more than the encryption algorithm. A weak cellular signal, frequent reconnects, sustained background transfers, overly frequent keepalives, and extended use of verbose logging can all increase power consumption. If a configuration works on a stable network but keeps reconnecting after you switch networks, check the connection state and keepalive settings before blaming the protocol. Battery usage statistics are also affected by other app activity during the measurement period.

Protocol guides do not replace server documentation

This guide explains what settings do; it cannot tell you which values will work. Use your existing information for the address, match authentication details to the server, and confirm that both sides support any transport extensions. Before making changes, record the original settings and keep a clearly identifiable copy for testing. Change one variable at a time so you can tell whether it affected the result. If you change the protocol, DNS, and rules all at once, even restoring the connection may not tell you what fixed it.

System permission to add a VPN configuration lets the app create a local network tunnel; it does not fill in remote server details for you. A system status of Connected also does not confirm that remote authentication, DNS, and access to the destination are all working. If setup stops at the permission prompt, see the VPN configuration prompt guide. If the connection is active but sites are unreachable, work through the checks below instead of treating a system permission issue as a protocol selection problem.

Shadowsocks: streamlined design and encryption settings

Designed for encrypted traffic forwarding

Shadowsocks was designed to forward app traffic through a relatively lightweight protocol structure, encrypting and authenticating data between the client and server. It is not a complete network-layer tunnel that brings an entire remote network to your device. The system VPN tunnel shown in Shadowrocket and the use of Shadowsocks on the remote connection are separate layers. The former handles device traffic locally; the latter carries data between client and server. Understanding this distinction helps separate local routing from the remote protocol.

A streamlined design does not mean every configuration is the same. Encryption methods have different data formats and key requirements, while transport extensions can change how a connection works. A basic configuration and one using a plugin or other extension are not interchangeable just by copying the server address and password. When adding a server manually, check that the app supports the exact combination it requires. If the details came from a subscription, preserve the complete imported settings rather than deleting unfamiliar fields to make the screen simpler.

Check the password and encryption method together

The basic fields are the server address, port, password, and encryption method. The encryption method is not a free choice where “longer means more secure”; it is a protocol requirement that must match on both ends. If the server uses one method and the client another, decryption will fail even if the password is identical. Some newer methods require a key in a specific length and encoding, so an arbitrary string used as a password may not be equivalent. Preserve the original capitalization, symbols, and encoding. Don’t add spaces or remove trailing characters.

If a subscription update suddenly breaks the connection, first check whether the type or encryption method changed, then see whether the update overwrote the previous settings. When copying a password, line breaks, rich-text spaces, or an incomplete selection can introduce differences. A reachable address and port confirm only that the network endpoint exists, not that the password is correct. Some errors appear as an immediate disconnect; others keep waiting. The stage where the error occurs is more useful for troubleshooting than a single timeout message.

Test TCP and UDP separately

Typical web browsing can test some TCP traffic, but it does not prove UDP works. Real-time audio and video, some DNS queries, and other apps may rely on UDP. Forwarding depends on server capabilities, client settings, and network conditions. If websites work but a real-time app fails, check that path separately rather than repeating a web speed test. Conversely, one app that uses UDP working does not prove that all DNS resolution and TCP requests behave as expected.

When comparing Shadowsocks configurations on a device, focus on connection stability over time, delays on short requests, and recovery after switching networks—not just one large file transfer. Hardware acceleration, actual throughput, and the amount of data transferred all affect processing overhead. A stable, clearly specified, previously tested configuration is usually a better baseline than chasing an unverified algorithm name. Confirm performance issues with repeated tests.

If a test gets a response but websites fail, check address resolution, authentication, UDP, rule matching, and the destination site in turn. If only some domains are affected, see the DNS troubleshooting guide. Don’t keep changing encryption methods to fix a resolution problem, or treat skipping a check as a permanent fix. Make changes only when the source of the settings, support on both ends, and the error stage are clear.

VMess and VLESS: check authentication and transport separately

Similar fields do not make protocols interchangeable

VMess includes mechanisms for user identification, request structure, and data protection. VLESS uses a simpler request and authentication structure; the base protocol does not provide the same data encryption, so it is generally paired with an appropriate secure transport. Both may use a UUID and may be combined with TLS or WebSocket, but those similarities do not make the protocol types interchangeable. If a server provides VMess, selecting VLESS while keeping the UUID still results in a protocol mismatch.

To understand the difference, focus on how each protocol divides responsibilities. Some handle more mechanisms internally; others rely on an outer secure channel for data protection. Fewer fields do not automatically mean faster performance, and more fields do not automatically mean greater reliability. Actual connections also depend on the number of transport layers, handshake path, server implementation, and network conditions. Start by confirming what your existing server supports, then compare the available combinations. Don’t choose a name first and try to make every setting fit it.

There are more transport settings than just the UUID

When adding a server manually, check the type, address, port, and UUID first, then review the transport and security settings. A UUID identifies a user; it is not a server address and cannot replace authentication fields for a password-based protocol. Some VMess configurations also require additional authentication or encryption-related options. Follow the original configuration rather than filling in values from an outdated guide. An incorrect device clock can affect authentication or certificate validation, so check that the system date and time are accurate.

With WebSocket, the path and the Host request header are separate settings. Preserve the path’s leading slash and capitalization; don’t enter the domain in the path field or paste a full webpage URL as the Host. With TLS, SNI is used for server name negotiation and certificate validation. The connection address, Host, and SNI may differ depending on the deployment, but the existing configuration must specify those differences. Don’t make them identical just because that looks more consistent.

Pinpoint the stage where the failure occurs

An endpoint timeout first points to the address, port, or path being unreachable. For a TLS error, check the name, certificate chain, and device clock. If the connection closes right after the handshake, check the identity and protocol fields next. If there is a forwarding endpoint in front of the server, the problem may be between that endpoint and the backend. Changing the UUID repeatedly will not fix a mismatch in the endpoint path. Record the test time, network type, and error summary; this is usually more helpful than changing several fields in a row.

On iOS, multiple transport layers can delay the first request, but connection reuse may reduce subsequent handshakes. Assess both effects under the actual workload. Multiplexing is not a universal speed boost: when several requests share one underlying connection, packet loss or a connection failure can affect them all. If the current configuration offers a related option, confirm server support first, then test the same websites and sustained transfers. Don’t decide based on a single speed test.

If an existing subscription imports successfully, use the imported settings as your baseline and review the fields one by one. Don’t omit unfamiliar stream settings, security extensions, or transport types and try to connect anyway; don’t assume the app supports them. Keep the original details, check the options actually available in the app, and ask the server administrator if needed. After checking the protocol, use the Getting Started guide to verify Global Routing and actual requests. Successful authentication does not mean traffic is routed correctly.

Trojan: TLS identity and password authentication

The secure channel and proxy request have separate roles

Trojan’s basic design carries proxy requests over a TLS connection, using an established secure channel to protect transport and protocol-level authentication to identify the user. Think of it as two steps: first establish a trusted TLS connection to the server, then have the server recognize the proxy request and user identity. Completing the first step does not guarantee the second will succeed. A valid certificate and the correct password are separate checks; combining them into one switch makes troubleshooting harder.

The server address may be a domain name or another clearly specified endpoint, depending on the existing deployment, but the name used for TLS validation must still be correct. SNI tells the server which name the client is requesting, and the certificate must establish that name’s identity. If the connection address differs from the certificate name, use the corresponding fields specified by the existing configuration rather than removing SNI to bypass the issue. The address locates the endpoint; the name verifies its identity. They serve different purposes and cannot replace each other.

When checking a certificate, look beyond its expiration date

Certificate problems can also stem from a name mismatch, an incomplete certificate chain, an incorrect device clock, or a server deployment issue. Checking the expiration date alone is not enough to verify the whole process. If you see a related error, check the device clock first, then confirm the server name matches the configuration, and ask the server administrator to verify the certificate deployment. Disabling certificate validation changes the trust boundary and does not verify server identity. It is not a fix for password, routing, or resolution errors.

Preserve the password exactly as provided, paying particular attention to line breaks and spaces introduced during copying. You can change the display name, but don’t guess at changes to the password, port, or protocol type based on that name. If TLS is established but authentication fails, check the password and the actual protocol type provided by the server. A basic Trojan setup and one with an additional transport extension differ by more than a note: both ends must support the extension, and its path or other settings must be configured as required.

Assess handshake overhead together with connection reuse

An initial connection usually requires a network connection and TLS handshake; long distances, packet loss, or a network switch can increase the wait. Whether later requests reuse the underlying connection depends on the implementation and settings, not the protocol name alone. Compare the first page load, subsequent visits, and sustained transfers separately. If only the first load is slow, look at resolution and the handshake first. If sustained transfers also keep stalling, check path quality and server load.

TLS encryption is not the only factor in iPhone battery use. Frequent short connections or repeated retries after failures can keep the wireless radio and system networking active for longer. Compare under the same network conditions and with a similar amount of data, distinguishing screen-on time, background waiting, and actual transfers. Don’t compare battery use after a long video session with a few minutes of static web browsing; different workloads do not produce a meaningful comparison.

If a webpage shows a certificate warning, identify which layer reported it: did the client fail to establish TLS with the server, or did the browser report a certificate issue while accessing the destination website? The former calls for checking the current connection settings; the latter may involve the destination site, device clock, or other network settings. Don’t change the Trojan password just because you see the word “certificate.” The error location and time can quickly distinguish the two cases.

Trojan is a reasonable choice when your existing server provides a complete, verifiable TLS configuration, the authentication fields are clear, and access is stable in practice. TLS does not automatically make it better than other options or guarantee that every network path will work. If a previously working configuration has started showing a name or certificate error, check for deployment changes before switching protocols. For purchase or app update issues, see Troubleshooting.

HTTP and SOCKS5: where general-purpose proxies differ

Two common proxy interfaces, with different roles

HTTP proxies originated as a way to forward HTTP requests. The commonly used CONNECT method can also establish a byte stream to a specified destination. SOCKS5 is a more general proxy negotiation protocol that defines destination addresses, connection commands, and optional authentication; it does not require the content to be a webpage. Both are often used as standard interfaces in existing network environments, but “general-purpose” describes their use—not support for every command, authentication method, or type of app traffic.

HTTPS between an HTTP proxy and a destination website is a separate matter from whether the connection between the client and proxy server is encrypted. When CONNECT is used to access an HTTPS site, the website session can retain its TLS protection, but the proxy connection itself must be assessed according to its actual type. The base SOCKS5 protocol does not provide data encryption, and username-and-password authentication is not the same as an encrypted channel. A secure indicator in the browser therefore does not mean all metadata on the proxy connection has the same protection.

Check authentication and destination resolution separately

When adding existing HTTP or SOCKS5 details, check the server address, port, whether authentication is required, and which corresponding options the app supports. Some endpoints use no username or password; others require both. Don’t leave fields blank as a long-term way to guess. If the existing instructions specify a proxy endpoint protected by TLS, confirm that the selected type and security settings match. A basic HTTP field is not a generic label for every secure proxy type.

Which side resolves a domain can affect both access and troubleshooting. SOCKS5 can specify a domain as the destination, but whether the request sends the domain to the remote end still depends on client-side resolution and routing. HTTP CONNECT can also use a hostname or an address. If the remote side can resolve a name but the device cannot, changing where resolution happens may change the result. First understand the current settings, then test. Support for domain names alone does not mean every request will be resolved remotely.

A working webpage does not prove every app function works

Standard HTTP CONNECT is generally for TCP; it does not imply UDP apps will work. SOCKS5 defines UDP-related mechanisms, but many deployments allow only TCP, or network conditions may block the return path for UDP. If text chat works but calls fail, check the transport used by that feature. Trying more website destinations will only test web access; it cannot add missing UDP support or prove that every app request follows the same route.

These protocols may use relatively direct processing paths, but speed and battery use still depend on the encryption layer, connection lifetime, network quality, and server implementation. Fewer protocol fields do not automatically mean less cellular activity. Repeated authentication failures or frequent endpoint disconnects can make the experience worse. On iOS, look at connection retries, destination access, and background activity rather than treating “standard protocol” as a performance guarantee.

Use these proxy types when an existing work or test environment explicitly provides such an endpoint, and stay within its capabilities. For sensitive data, also confirm that the destination app encrypts its traffic and that the proxy connection is protected. If authentication is rejected, check the account fields. If the connection is established but the destination is unreachable, check resolution and remote access permissions. Don’t switch protocol types at random to solve a permissions issue, and never share account credentials when asking for help. See how to add a connection and connect for the first time.

WireGuard: network-layer tunnels and key relationships

From request forwarding to addresses and peers

WireGuard is designed as an encrypted network-layer tunnel, with a fixed modern cryptographic suite and public-key identity model. It aims to minimize protocol options and handshake complexity. Unlike proxy protocols that primarily describe a connection to a destination, WireGuard focuses on the relationships between local tunnel addresses, peer identity, endpoints, and reachable networks. When using it in Shadowrocket, the client still determines how device traffic is associated with the connection. Don’t assume that routing behavior from another environment applies here.

The configuration may have relatively few fields, but each has a specific role. The endpoint address locates the peer on the public network; the tunnel address identifies the local side inside the tunnel; the public key identifies the peer; and the private key proves the local side’s identity. Endpoint and tunnel addresses are usually different kinds of addresses and cannot be substituted. Entering the server’s public address as the local tunnel address can break the address and routing relationship even if the port is correct.

Identify each key by which side it belongs to

Keep the local private key secret. The peer’s public key identifies the connection endpoint; these keys are not interchangeable fields. If the configuration includes a preshared key, it is additional key material that must match on both sides and cannot be replaced by the peer’s public key. If the handshake fails after import, check which side each key belongs to and verify the endpoint before checking network reachability. Generating a new local key changes the identity. If the server still accepts only the old public key, changing the key on the client alone will not restore the connection.

In WireGuard, Allowed IPs contributes to the relationship between peer address ranges and encrypted routing. It is more than a note, but it should not be mistaken for the complete set of routing rules ultimately applied on the device. Shadowrocket’s Global Routing and Config also affect how traffic reaches the selected connection. If the tunnel handshakes but some addresses remain unreachable, check the tunnel address range, remote forwarding, and client routing together. Don’t assume the remote network is reachable based only on the last rule.

Check the handshake, MTU, and keepalive separately

WireGuard uses UDP, so being able to browse ordinary websites does not prove that the UDP path to the endpoint is working. If the handshake never completes, first check the endpoint domain, port, keys, and network path. If the handshake succeeds and small transfers work but large pages or uploads stall, investigate MTU next. Tunnel encapsulation adds overhead; if the path cannot handle the resulting packet size, some requests may work while larger transfers stall.

Don’t copy a fixed MTU value from someone else’s device. Record the current value, then test changes incrementally under controlled conditions. Check whether web access, uploads, and sustained transfers all improve. Lowering the MTU may avoid fragmentation issues, but it also increases the number of packets needed for the same amount of data. Smaller is not always better. Keep a change only if the symptoms point to packet size and the improvement is repeatable. MTU adjustments cannot fix an identity error.

A keepalive setting such as Persistent Keepalive can maintain mappings in some network equipment, but its interval affects background network activity. Set it only when the existing setup requires it; don’t use a very short interval by default in the name of stability. Verify whether the peer learns a new network location after switching between cellular and Wi-Fi. On iPhone, continuous keepalives, weak signal, and frequent network changes may affect battery life more than protocol processing.

Use WireGuard when you already have a complete, matching peer configuration and know which address ranges you need to reach. Validate in order: handshake, tunnel addresses, domain resolution, then the actual app or service. Don’t treat a successful handshake as proof that everything works. If domain names fail but direct addresses work, check DNS. If only certain subnets fail, check routing and remote forwarding. If the connection behaves differently after sleep, examine mappings and keepalive. This layered approach is easier to interpret than changing keys and routes at the same time.

Hysteria2: QUIC, bandwidth hints, and network paths

Trade-offs of a UDP-based transport

Hysteria2 uses QUIC for transport, drawing on its secure handshake and multiplexed streams, with transport design suited to conditions such as high latency and packet loss. It is not intended to deliver the same speed on every network; it uses a different control approach from traditional TCP-based transport on some paths. QUIC uses UDP, so the network endpoint and intermediate path’s handling of UDP directly affect whether it can connect. Ordinary web access does not prove this path is working.

When considering multiple streams, distinguish their transport independence from the resources they share. A delay on one stream does not necessarily block delivery on every other stream as it would with a single ordered byte stream, but all streams still share the underlying path, congestion control, and available bandwidth. Multiplexing does not create capacity when wireless signal is poor or the endpoint is constrained. If many requests slow down together, examine the whole path before assuming every destination site has failed at once.

Check authentication, TLS, and additional settings separately

Start by checking the protocol type, server address, port, authentication details, and TLS name. Hysteria2 is not interchangeable with other protocols that have similar names; the client type must match the existing server. Preserve the authentication field exactly as provided, and check SNI and certificate requirements separately. If the configuration includes additional options, fill them in only if the app supports the corresponding feature and the server uses the same settings. Don’t guess values based on field names.

Bandwidth-related fields are especially easy to mistake for speed-test results. Where applicable, they provide a reference or limit for sending behavior under congestion control; they do not promise that the client will reach the entered value. Upload and download fields may use different units or conventions, so follow the current field description and existing configuration. Entering a very high number cannot exceed the access bandwidth or path capacity; it may instead cause queueing, packet loss, or interfere with other traffic.

Assess both responsiveness and throughput in performance tests

A high sustained download speed does not mean web browsing, voice calls, and background sync will all work better. While a transfer is running, check how quickly other requests get a response and whether they queue up. Don’t choose only the best result from a single test, or compare protocols using different destinations and networks. Establish a conservative, repeatable baseline first. After changing bandwidth-related settings, check whether throughput and responsiveness both improve or only one changes.

On iOS, QUIC processing, high data throughput, and sustained wireless activity can all increase power use, but UDP alone does not determine battery life. Downloading more data in the same period often makes a device warmer; if the data amounts differ, that does not prove one protocol is less efficient. Compare the time needed to transfer the same amount of data, and background activity over the same usage period. Take signal strength and screen state into account.

If Hysteria2 works on Wi-Fi but consistently fails on cellular, first verify actual UDP support on each network rather than changing authentication. If the problem is brief after switching networks, see whether reconnecting resolves it. If it continues, check the stage reported in the logs. The cause may be path MTU, server resources, or endpoint restrictions; confirm with the administrator of your existing server. A single timeout in the app cannot identify which layer rejected the request.

Continue using Hysteria2 when your existing server explicitly supports it, the app can express all required settings, and repeated tests on your target network show stable benefits. It does not need to replace every existing configuration. If a TCP-based option already meets your needs and UDP is unreliable on your network, keeping the tested configuration is more practical. The right choice depends on the use case, not on whether a protocol name is newer or older.

Choose for your use case and validate in layers

Meet configuration requirements before comparing performance

Start with the information you already have: confirm the protocols and required fields your server supports, identify the apps or services you need, and check whether the current network supports the required TCP or UDP traffic. Web browsing, long transfers, real-time apps, and remote subnet access put different demands on handshakes, throughput, jitter, and routing. No single metric covers every use case. Rule out combinations with missing fields or unsuitable network paths before comparing the remaining options. This is more efficient than trying every type one by one.

For everyday browsing, keep an existing configuration that is stable, clearly specified, and responsive enough on the first page load. For real-time services, also test UDP, jitter, and continuity. For remote subnets, confirm address ranges and the return path. If several configurations work, compare them repeatedly on the same device, network, and destination. Don’t change DNS, rules, and transport settings at the same time. A test result applies to that scenario; it should not be generalized to every device and network.

Global Routing determines how requests are handled

Even with the correct protocol, rules can send traffic down the wrong path. Config applies the current rules; Proxy can temporarily reduce the influence of rule matching; Direct provides a view of the original network path. Switching modes is a diagnostic step, not an automatic fix. If Proxy works but Config fails, check the rules, policy names, and DNS before re-entering the password. After testing, restore the intended mode so temporary settings do not affect other traffic.

The following short rule snippet from a Shadowrocket configuration shows the order of domain, address, and final rules; it is not a complete configuration. Rules are generally matched from top to bottom, with FINAL after the preceding rules. PROXY and DIRECT here refer to policies; don’t enter a server password as a policy. If you use a named policy, confirm that the current configuration defines that name.

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

DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches address ranges, GEOIP uses address-location data, and FINAL handles requests that did not match earlier rules. These are not protocol settings and do not change remote authentication. Domain rules also depend on the request processing path preserving the relevant domain name; if only a destination address is available, the matching conditions may differ. Consider rule order, resolution results, and request type together. For details, see rule syntax and matching logic.

Follow a consistent order to narrow down the cause

First, confirm that the app has system permission and the intended connection is selected. Next, check that the endpoint address resolves and is reachable. Then verify protocol authentication and TLS, followed by DNS, rules and policies, and finally the destination app itself. If a failure occurs at an earlier layer, fix that layer before changing later settings. Assess Connectivity Test results alongside actual web access, uploads, and the services you need; one successful test does not validate every path.

When documenting the issue, include the network type, Global Routing mode, selected connection, failure stage, and whether the problem is repeatable. Don’t record public authentication values. For stalled long transfers, check MTU, packet loss, and server status. If latency is normal but domain names fail, see DNS troubleshooting. For issues with the system connection switch, see Troubleshooting. Change one setting at a time, and restore the baseline if it fails so unverified changes do not accumulate.

The goal is a configuration whose behavior you can explain, not just one that happens to connect. Record effective settings separately from the scenarios they suit, check key fields after updating an existing subscription, and repeat the same checks when network conditions change. For everyday setup, return to the Getting Started guide. For App Store purchases, restoring purchases, and device compatibility, see Getting the App and verifying the official listing; there’s no need to troubleshoot purchase issues while diagnosing a protocol.