Shadowrocket Protocol Guide

01 / Model

Protocol layers and choosing a type

A protocol name is not a complete connection setup

In Add Server, choosing Type tells the client which format to use when communicating with the server. It does not switch the same connection to a different performance tier. If the server provides Shadowsocks, changing the client to VLESS will not give it VLESS capabilities. Both sides must agree on the protocol, port, authentication details, and underlying transport. An imported subscription usually includes this information, but a successful import only means the data could be parsed. It does not confirm that the remote configuration is still valid or that the current network can reach the specified port.

A connection can be understood as a sequence of layers: the destination request, proxy protocol, transport, and network path. The request specifies the domain and port to reach. The proxy protocol conveys the request and authenticates the user; some protocols also provide encryption. The transport determines how data travels over TCP, UDP, TLS, or another encapsulation. The network path includes the wireless connection, carrier network, server access link, and the route from the server to the destination. A problem at one layer does not automatically point to the protocol name. Troubleshoot by checking each layer in turn.

Authentication, encryption, and routing solve different problems

Passwords, UUIDs, and keys can all prove identity, but they are not interchangeable. A UUID is not a domain name, and a WireGuard Public Key cannot be used as a password. Encryption protects data in transit; authentication identifies a communicating party or user. One mechanism may provide both, or they may be handled at different layers. TLS certificate verification helps confirm the server’s identity and should not be skipped just because the account password is correct. When field names look similar, follow the server’s protocol documentation to determine what belongs where.

Global Routing is a separate decision layer: Config routes traffic according to the active configuration, Proxy sends eligible traffic through a proxy policy, and Direct connects without a proxy. None of these changes the server’s protocol type. After choosing the right Type, make sure requests follow the intended policy. Otherwise, a successful visit may simply mean DIRECT was used, while a failure may mean the rules selected an unavailable destination. See the Glossary for terminology, and don’t mistake a mode change for protocol tuning.

Choose only among capabilities the server actually provides

Start with what the server actually supports, not whichever protocol name looks newest in the list. Note the available types, UDP support, authentication method, and required transport, then check whether the client has matching fields. The same protocol can be deployed in different combinations; don’t try to make up for a missing field by filling in an unrelated one. If subscription details conflict with manual instructions, ask your service provider to confirm the current settings. Leave unclear extensions unchanged, and avoid changing several variables at once so you can keep a reproducible baseline.

Shadowrocket is a paid commercial app for Apple devices. Check the App Store listing for availability and system requirements. To verify where to buy it, see the App Store purchase verification guide. A one-time app purchase is not a service plan: buying the app does not provide a server address, authentication details, or a subscription. That distinction also defines what choosing a protocol means here: select the right connection type for the details you already have, then use evidence to see whether it suits your network. No protocol is guaranteed to be faster in every situation.

02 / Shadowsocks

Shadowsocks: shared keys and lightweight encapsulation

Design goals and limitations

Shadowsocks was designed to relay proxy requests with a relatively simple protocol. Common deployments use a shared password and a specified encryption method. The client identifies the destination, then encapsulates the request and sends it to the server, which establishes the next connection. It is not primarily modeled as a full virtual network, so it is best understood as a way to forward specific requests, rather than as a remote network interface. Implementations and encryption methods can differ, so not every entry labeled Shadowsocks behaves identically.

Modern deployments commonly use AEAD encryption methods, which provide confidentiality and integrity checks together. Newer protocol variants may also impose requirements on key format, session handling, or replay protection. The key is not to remember which name is longer, but to select the exact method supported by the server. A shared password is not always an arbitrary readable phrase: some methods require a key of a specific length and encoding. Don’t carry a password over from an older configuration to a different method and expect the server to accept it automatically.

Check the fields; don’t fill them in from memory

In Add Server, first confirm that Address and Port point to the server’s actual listening endpoint, then check Method and Password. Address can be a domain name or an IP address, but it must resolve to the right service. Port is the server’s listening port, not the default port used to visit a website. Method is not a local security-strength setting; it is part of the protocol both sides must use. Uppercase and lowercase letters, trailing spaces, and line breaks accidentally copied into Password can all cause authentication to fail. Keep the original entry and compare each field with its source before making changes.

If an existing entry includes extra transport settings, treat them as part of the connection setup. The protocol itself and additional encapsulation are not the same thing: an outer layer can change the handshake, domain name requirements, and network behavior, while adding troubleshooting steps. Configure it only when the server explicitly requires it and the client supports the option. If a manually created entry fails but one imported from the same source works, compare their fields first. Don’t start by changing the encryption method or deleting settings you don’t recognize.

Speed, battery use, and common failure points

On iPhone, fewer encapsulation layers can make problems easier to isolate, but that does not necessarily mean lower battery use. Encryption is only one part of power consumption; the screen, wireless signal, retransmissions, and background activity can matter more. Modern devices handle some encryption algorithms efficiently, while throughput still depends on server load and network congestion. For browsing and short connections, check whether the first request completes promptly. For sustained transfers, observe throughput and device temperature once the connection is stable.

If TCP requests work but UDP traffic does not, check the client entry, server support, and UDP reachability on the current network separately. A working webpage does not prove that all traffic types work. If a domain fails but its IP address responds, consider where DNS resolution occurs and whether the results differ. When a connection stalls after being established, note whether the failure happens while sending a request, receiving a response, or during sustained transfer, then retest on the same network. Separating these symptoms is usually more useful than repeatedly changing Method.

03 / VMess · VLESS

VMess and VLESS: separate authentication from transport

How the two protocols differ

VMess combines user identification, request encapsulation, and related security mechanisms in the protocol. Common configurations use a UUID as the user identifier. It was part of an earlier phase in the evolution of proxy protocols, with a focus on identifiable users and connection handling; different authentication formats have since appeared. For users, the important thing is the server’s actual configuration, not guessing compatibility settings from an old tutorial. Extra fields in a subscription may be needed for legacy compatibility or a particular implementation, so preserve the values provided by the source.

VLESS has a more focused protocol role. The base protocol does not encrypt content, so it must be paired with suitable secure transport. It still requires authentication, but having a UUID does not mean the content is encrypted. To understand where protection comes from, check whether the outer transport uses TLS or another security mechanism specified by the server. Don’t assume VMess and VLESS are interchangeable just because the interface has a similarly named authentication field. Their handshakes and encapsulation differ, and the server must support the selected type.

Match each setting to its purpose

Copy the UUID in full without quotes, extra text, or separators. The server address and TLS Server Name may differ: the address determines where to connect, while the name is used in the TLS handshake and certificate verification. If the source specifies different values, enter each in its corresponding field. Don’t substitute another reachable domain when no such instruction is provided. Also check the device clock: an incorrect time can affect certificate validity checks and authentication that depends on time.

Transport settings determine how protocol requests are carried. With WebSocket, Path identifies the server’s entry point, while Host may be used for routing the outer request. These are not notes fields: slashes, capitalization, and path prefixes can all affect the result. Some deployments use a reverse proxy to route multiple services on one address. If the port is reachable but the path is wrong, the remote server may return a webpage instead of a protocol handshake. Changing the UUID is unlikely to help; check the transport and entry-point fields first.

Extension settings cannot be transferred on their own

Some VLESS entries include Flow or other security handshake settings. These are part of a specific connection setup, not general-purpose speed switches. A combination that works on the server is not necessarily supported by the current client. Check the fields available in Add Server and the source instructions. If a required option is missing, confirm compatibility first; don’t put its value in a notes field or another field that merely looks similar. After importing, open the entry and make sure the client recognized the key settings rather than just saving the name.

Extra handshakes and transport encapsulation can delay the first request, but once a connection is established, the bottleneck may shift to the network or server. WebSocket is not inherently faster than other transports, and VLESS’s leaner design does not guarantee lower battery use than VMess. Reconnecting repeatedly on a weak signal can matter more than the protocols’ processing differences. For a fair comparison, use the same network, similar destinations, and the same task; record cold starts and ongoing use separately. Don’t rank protocols based on a single Connectivity Test.

Troubleshoot in stages: address and port, outer handshake, transport entry point, authentication, then destination access. For an outer certificate error, check the device time and Server Name. If the server returns an ordinary webpage instead of proxying, check the entry path. If the connection works but a particular service does not, check UDP support and routing. For slow first requests after a long idle period, note whether the connection had to be re-established. For other common issues, see Troubleshooting. Don’t hide an earlier-layer problem by disabling certificate verification.

04 / TLS · Proxy

Trojan, HTTP, and SOCKS5

Trojan relies on TLS for secure transport

A common Trojan setup first establishes a TLS connection, then handles protocol authentication and request forwarding through the protected channel. Its settings may look shorter than those of a layered setup, but TLS still requires proper identity verification. The server certificate, connection address, and Server Name must match appropriately. A correct password cannot compensate for a certificate name mismatch. Separate the problem into two questions—did TLS succeed, and did protocol authentication succeed?—rather than treating every failure as a wrong password.

Address can point to the server, while Server Name must match the server’s requirements and certificate. Even when connecting directly to an IP address, you may still need to provide a domain name for TLS verification. An expired certificate, incomplete certificate chain, incorrect device time, or name mismatch can all prevent the handshake. Skipping verification weakens confirmation of the communicating party and is not a routine fix. If the server uses a special trust arrangement, follow its documented instructions rather than disabling checks on a public network just to get one connection working.

What HTTP and SOCKS5 do

HTTP proxies were designed for application-layer proxying. The CONNECT method commonly asks the proxy to open a tunnel to a destination. HTTP describes the proxy interaction; it does not automatically mean that the connection from the client to the proxy uses TLS. When accessing an HTTPS destination, TLS to that destination and protection of the proxy connection are separate concerns. Encryption to the destination does not mean proxy credentials receive the same protection in every setup. Distinguish a plain HTTP proxy from a proxy connection that uses TLS, and configure it according to the server’s actual capabilities.

SOCKS5 uses a general-purpose request format for specifying a destination address and port, and defines mechanisms for authentication and UDP associations. It does not provide general-purpose content encryption, and username-and-password authentication is not the same as encrypted transport. It may suit a trusted network or a setup with explicit transport protection. Before choosing it, find out what protects data between the client and server. UDP support also depends on more than what the protocol specification allows: verify the server implementation, authentication method, and client support for the actual combination.

Don’t confuse proxy authentication with destination authentication

A proxy username and password are for accessing the proxy service, not an account on the destination website. If the remote server requires authentication, leaving the fields blank may result in a rejection. If the server does not use that authentication method, entering arbitrary credentials adds no protection. For an authentication-related error, first determine whether the response came from the proxy or the destination website. If a webpage works but a particular app does not, the cause could also be the app’s request method, destination port, UDP requirements, or routing. That does not mean the credentials only work for some websites.

On iPhone, actual power use for these protocols depends on handshake frequency, connection reuse, and wireless activity. Establishing TLS involves extra processing and round trips, but an established connection can carry subsequent requests. Repeatedly disconnecting and reconnecting can use more resources than keeping a suitable connection open. Conversely, frequently waking the wireless link to keep a connection alive also has a cost. Don’t assume TLS always uses more battery or that an unencrypted option is automatically worth choosing; first meet security and compatibility requirements.

First confirm which proxy type the server provides, then check its TLS, authentication, and UDP requirements. For Trojan certificate errors, troubleshoot the TLS layer. For an HTTP proxy rejection, check authentication or CONNECT permissions. If SOCKS5 establishes a session but a particular service fails, check supported commands and the datagram path. For an existing work network proxy, follow the network administrator’s requirements and don’t change authentication methods or destination port restrictions arbitrarily. Test performance only within permitted use; don’t mistake access restrictions for protocol speed problems.

05 / WireGuard

WireGuard: keys, addresses, and tunnel routing

Think in terms of a virtual network, not individual requests

WireGuard is based on an encrypted Layer 3 tunnel, unlike the proxy types above, which establish sessions for destination requests. It uses public and private keys to identify the parties and carries encapsulated network packets over UDP. Its design keeps the protocol surface small and uses a defined cryptographic suite instead of asking users to negotiate among many algorithms. This means fewer algorithm choices, but more attention is needed for key ownership, tunnel addresses, peer endpoints, and routing scope. An error in any of these fields can affect access.

Private Key identifies the local side and must remain private; Public Key identifies the corresponding peer. When entering settings, be clear about which side the source configuration calls local and which it calls peer. Never enter the server’s public key as the local private key. An optional Preshared Key is additional shared material, not a regular password that replaces the key pair. Preserve these values if they’re provided in a subscription or configuration. When sharing troubleshooting details, remove private keys and other authentication material; hiding only the server name is not enough.

Endpoint, Address, and Allowed IPs

Endpoint is the actual address and UDP port used to reach the peer. The tunnel Address is the device’s address inside the tunnel; the two belong to different network layers. Putting a public server address in the tunnel address field, or using an internal tunnel address as the Endpoint, can prevent a connection. If Endpoint uses a domain name, it also relies on DNS being available before the tunnel starts. If the endpoint cannot be resolved as soon as the tunnel is enabled, check for a DNS dependency loop before changing the keys.

Allowed IPs specifies address ranges associated with the peer. In WireGuard, these ranges are involved in routing decisions and validating source addresses. They are not a website allowlist, and expanding them at random will not improve the chance of success. Check how the current configuration combines these ranges with its own routing policies. A range that is too narrow may exclude required destinations; one that is too broad may send unrelated traffic through the tunnel. Even a successful handshake cannot provide access if the server does not route traffic for the requested destination.

Network changes on mobile and keepalive trade-offs

When a mobile device switches between Wi-Fi and cellular, its external address and NAT mapping may change. WireGuard can update the peer endpoint when authenticated packets arrive, but that does not mean every network switch completes instantly. The new network must still allow UDP, and the server must receive valid traffic. A slow first request after a long idle period may be related to an expired mapping or renewed communication. Track ongoing use, resuming after idle, and recovery after a network switch separately instead of combining them into one stability score.

Persistent Keepalive can maintain a network mapping when needed, at the cost of sending packets periodically. More frequent keepalives are not necessarily better, and a fixed value should not be applied to every entry. Even small packets can trigger wireless activity on a weak cellular signal and affect standby battery life. If inbound reachability does not need to be maintained, extra keepalives may not help. Set them according to server requirements and real network conditions, then compare recovery after the same idle period. Don’t judge power use from the moment the setting is enabled.

If the handshake works but some pages stall, consider routing, DNS, and MTU. Tunnel encapsulation adds overhead, and a path that cannot handle larger packets properly may allow small requests while larger responses stall. Keep a baseline and adjust MTU in small steps; an extreme value chosen by guesswork can reduce throughput. WireGuard suits setups with complete tunnel settings that need network-layer connectivity. If you only have server details for another protocol, you cannot turn them into a WireGuard service just by generating a key pair.

06 / Hysteria2

Hysteria2: QUIC and lossy connections

What QUIC changes

Hysteria2 uses QUIC for proxy transport. QUIC typically runs over UDP and combines a secure handshake with stream management and congestion control. Its potential benefits depend on network conditions: when latency is high, packets are lost, or available bandwidth varies, transport recovery and pacing can significantly affect the experience. It is not simply TCP repackaged in UDP for an automatic speed boost, nor can it overcome physical bandwidth limits. Server access, wireless quality, and destination response time still set the limits.

In designs that multiplex several tasks over a single TCP connection, lost data at the transport layer can delay later delivery. QUIC’s streams can reduce blocking between streams caused by reliable, ordered delivery, but data within a reliable stream still needs to be recovered, and congestion control still affects the shared connection. Applications that rely on reliable transport may also involve multiple layers of feedback after encapsulation. So “based on QUIC” does not mean packet loss has no cost, and a protocol description alone cannot predict how long a particular webpage will take to load.

Authentication, certificates, and bandwidth settings

When checking settings manually, start with Address, Port, the authentication string, and the TLS Server Name. The server must actually support Hysteria2; another entry with a similar name is not interchangeable. Certificate verification still matters: a name mismatch, expired certificate, or incorrect device time can prevent a connection. If the source provides extra settings such as obfuscation, confirm that both sides use the same values. These settings are not backup password fields; a missing or mismatched value can prevent communication before authentication.

Some configurations allow upload and download bandwidth to be specified for particular congestion-control behavior. These values are inputs to transport scheduling, not promises of a target speed once a limit is removed. Setting them far above the actual capacity of the network can cause sustained congestion, packet loss, and retransmissions, and may make other apps perform worse. Congestion-control methods use the declared values differently, so follow the source instructions and the options actually available in the client. Start with conservative, explainable settings, then decide whether there is a reason to adjust them based on sustained observation.

UDP reachability is a prerequisite, not a guarantee

Some networks restrict UDP or handle it differently from TCP, with variable quality. Working direct access to an ordinary webpage at the same location does not prove that a QUIC path will work; a port that shows no obvious error does not prove that the protocol handshake completed. If Hysteria2 fails only on a particular Wi-Fi network, first compare its path with another type you already know works, then check whether the server received the request. Don’t change authentication, Server Name, and bandwidth settings all at once, or you won’t know whether the issue is a network restriction or a field mismatch.

On iPhone, high throughput keeps the wireless radio and processor active and may increase power use. But completing the same task faster can also reduce active time. Compare both temperature during transfer and total battery use after the task, along with how quickly the device returns to idle. More aggressive sending on a lossy network may improve throughput but use more power. Draw conclusions only for the tested device, network, and task; don’t generalize that Hysteria2 always uses more or less battery.

Hysteria2 is worth testing if you already have a Hysteria2 service, UDP quality on the current network is acceptable, and your workload is affected by high latency or packet loss. If the network is stable and you mostly make short requests, the benefits may be less noticeable than during sustained transfers. For more background, read Hysteria2 and QUIC: Technical Notes. For intermittent stalls, record the network type, whether you switched networks, and whether the issue occurred just after resuming from idle. Then check packet loss, congestion, and server load instead of assuming the bandwidth setting is too low.

07 / Measurement

Testing speed and battery use on iOS

Define the task first

“Fast” includes at least three things: first response, sustained throughput, and interactive stability. First response affects how long a new page takes to open; sustained throughput matters for large transfers; interactive stability affects real-time activity and whether short requests repeatedly stall. Connectivity Test results reflect only the parts of the path involved in that test, not every destination, UDP task, or long session. Before comparing, define the task—for example, browse the same set of pages or transfer the same existing test file—so you don’t compare different activities based on feel alone.

To isolate protocol differences, use servers with similar locations, resources, and routes to the destination where possible. If two entries use different servers, any observed difference is between the two connection setups, not necessarily the protocols themselves. Even at the same address, the server may allocate different resources to different entry points. If you cannot control these factors, practical testing is still useful, but frame the conclusion as “this entry works better on this network” rather than claiming that one protocol has a universal performance advantage.

Use a repeatable test sequence

Use the same device, network, location, and approximate time of day, and pause background transfers that could affect the results. First check that the base network works, then test one entry with the chosen task and repeat with another. Alternate the order to reduce bias from network changes over time. Repeat each condition several times and record the range, not just the fastest result. Keep cold and warm connections separate: a cold connection includes name resolution and handshakes, while a warm one may benefit from connection reuse and caching. Don’t average them together.

Record Wi-Fi and cellular tests separately; signal changes while moving can easily distort results. Don’t adjust settings while changing locations. If you need to test recovery after switching networks, treat it as a separate task and record how long requests take to resume and whether a manual reconnect is needed. If a failure happens occasionally, repeat it under the same conditions before changing anything. A connection that completes the task reliably is usually a better everyday choice than one that occasionally reaches a high peak but often stalls.

Compare power use during activity and standby separately

Battery percentage is a coarse reading; small changes over a few minutes are not proof of a protocol difference. Screen brightness, temperature, signal strength, and background apps can outweigh protocol overhead. For active power use, keep the screen and task consistent and compare the overall battery cost of completing the same workload. For standby, keep idle time and network conditions the same, then check for ongoing traffic or frequent wake-ups. Don’t compare a long video task on one connection with standby on another and conclude which uses less power.

System battery statistics and Shadowrocket’s Data can help, but they use different measurement methods. Data transferred cannot be directly converted into battery use, and how iOS attributes activity to extensions and apps may not accurately show the independent cost of a protocol. If usage looks unusual, first check for repeated retries, periodic requests, keepalives, or frequent disconnections, then review the On Demand triggers. Reasonable automatic connection settings can match your needs, but more complex rules do not necessarily save power. Verify their effects in practice.

Keep troubleshooting records to the necessary evidence: network type, protocol type, time of failure, request stage, and outcome. Before sharing logs, check for subscription URLs, authentication details, visited domains, or personal network information. A subscription link can function as an access credential; don’t post it in full. If you need to organize multiple sources, see Organizing and Cleaning Up Multiple Subscriptions. First make sure each test is tied to a clearly identified server, then compare performance; duplicate names can otherwise change what you think you’re testing without you noticing.

08 / Decision

Choose by use case and verify the result

First rule out combinations that don’t meet your requirements

Choose in this order: availability, security, compatibility with your use case, then performance and battery use. Start by listing the types your server actually supports, and rule out combinations the current network cannot carry or the client cannot configure with the required fields. Next, confirm authentication and certificate verification, and check whether the destination task needs UDP or access to an internal tunnel address. Only then is a speed comparison meaningful. A shorter settings list is not automatically more reliable, and a more complex setup is not automatically more secure. Every layer should be understood and verified.

For everyday browsing and general app use, keep a setup that already works reliably and has clearly sourced settings; there is no need to rebuild every entry just because the protocol name changes. If you need a Layer 3 tunnel and access to specific internal networks, a complete WireGuard configuration fits that model. If you already have a Hysteria2 service and face high latency or packet loss, it may be worth testing. If you only have HTTP or SOCKS5 details, first understand the transport protection and supported use cases. A simpler name does not mean it suits every sensitive task.

Verify routing as well as the protocol

After importing, check the selected server on Home, then review Global Routing. Temporarily using Proxy can help determine whether a problem is related to routing, but it does not replace final verification in Config. Back in Config, make sure the intended file is active and check which policy handles the destination request. Rules are evaluated from top to bottom; the first match determines what happens. If an earlier broad rule matches, later, more specific rules are never reached. Protocol availability and correct routing are separate checks.

The following Shadowrocket text configuration snippet only illustrates rule behavior. It is not server information and should not replace an existing complete file. The example domains are for explanation; PROXY, DIRECT, and REJECT represent different handling policies. IP-CIDR can specify a local network range, while FINAL handles connections that did not match earlier rules. Before using these snippets, check that the policies in your existing configuration fit your actual needs. Don’t mask proxy failures by broadly expanding DIRECT, or send every local request to a remote server.

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

Include DNS in the final checks. Domain rules and address rules depend on different information; resolution results, cached data, and IPv4 / IPv6 reachability can all affect which rule matches. A domain resolving to different addresses at different times does not necessarily mean the protocol settings changed. First check the requested domain or address in the logs, the rule that matched, and the policy used; then decide whether to adjust the rules. For a more detailed explanation, see Rule Priority and the FINAL Fallback. Don’t treat a connectivity test in this protocol guide as a routing configuration tutorial.

Keep a daily setup you can roll back

Keep a verified baseline: the protocol type and key settings have clear sources, everyday destinations work, and the connection recovers as expected after idle periods and network switches. When trying a new setup, duplicate the entry and give it a clear name; don’t overwrite your only working option. Check the selected entry after subscription updates, since the server address or settings may have changed. Duplicate names can also lead to selecting the wrong entry. Before changing devices, keep a backup of the configuration you need. After restoring it, verify access, the active Config, and the actual routing policy; don’t assume all local state is restored along with the app purchase.

If the issue is still unclear, work through these checks in order: is the base network working, is the endpoint reachable, did TLS succeed, did authentication pass, and did the request match the intended policy? Then see Troubleshooting. To repeat the import and first-connection steps, return to the Setup Guide. The outcome should be a configuration you can explain, retest, and roll back—not a protocol ranking detached from network conditions. Check the App Store listing for the client’s availability and system requirements, and confirm server settings with your service provider. Don’t confuse these separate sources of information.