Official Manual / Technical Reference

Shadowrocket Protocol Guide

First identify the protocol from your existing subscription or server details, then check the transport, authentication and routing settings. Compare speed, battery use and maintenance only when the server offers multiple working options.

If you’re opening Shadowrocket for the first time, follow the setup tutorial to import a configuration, select Global Routing and complete the initial checks. If you can already connect and need to check settings or interpret test results, use this page’s contents. Haven’t obtained the app yet? See the download and installation guide for all platforms for platform-specific download options, system requirements and installation notes.

Getting the app and getting a proxy service are separate things. Get the iPhone / iPad version from the App Store product page for a one-time US$2.99 purchase; check the App Store page for the current price and system requirements. The Mac (Apple silicon and Intel), Windows, Android and Linux versions are free, with installers available from this site at /dl/. Buying the app is a one-time purchase; it does not include a proxy service. This manual explains how to use subscription or server details you already have.

Choosing a protocol: check the server first, then compare client performance

A protocol isn’t a connection preference; it defines how the client and server exchange data. The same SERVER and port can be used for different connection methods. An open port only means that a service on the network path accepted a connection; it doesn’t mean that service understands the protocol the client is using. If you have a subscription, keep the imported entry as is. If you have details to enter manually, first confirm the protocol, port, authentication method and transport. If the server offers only one protocol, select it and verify the connection—don’t cycle through other types in the app.

Separate the protocol, transport and security settings

The first layer is the protocol itself: it determines how the destination is specified, how the client is authenticated and how data is delivered. The second is the transport: depending on the protocol and server setup, a connection may use TCP, WebSocket or QUIC over UDP. The third covers connection security and identity checks: for example, a TLS certificate must match the expected server name, while WireGuard identifies a peer by its public key. Some protocols include encryption but can still use an additional transport layer. Some standard proxies only forward traffic, leaving the app’s own HTTPS connection to protect data sent to the destination site. Recording these details by layer is more useful than remembering a vague “encryption switch.”

Don’t infer the protocol from an entry’s display name. Two similarly named entries in one subscription may use different transports; two entries using the same protocol may connect through different ingress and egress points. To investigate, check your existing details to confirm which ingress the test uses, then compare results for the same destination. When sharing troubleshooting notes, include only the protocol, network type, failure stage and redacted field status—never the subscription URL, credentials or configuration screenshots.

Narrow down the options based on your connection details
What you haveCheck firstDon’t assume
A standard proxy address and credentialsHTTP or SOCKS5, as specified in your detailsThe same port number doesn’t make protocols interchangeable
An encryption method and passwordCheck whether it’s Shadowsocks and use the exact encryption method providedA password alone doesn’t mean it’s Shadowsocks
A UUID and transport detailsCheck whether it’s VMess or VLESS, then verify the transport and handshake settingsMatching UUID formats don’t make protocols compatible
A TLS name and passwordIf the details specify Trojan, check its protocol-specific fieldsA valid certificate doesn’t mean the password is correct
A peer public key and tunnel addressWireGuard: check the allowed IP ranges and return pathA successful handshake doesn’t mean the destination network is reachable
QUIC connection and authentication detailsIf the details specify Hysteria2, check the UDP pathHTTPS access at the same address doesn’t prove UDP is reachable

If multiple working connections are available, decide what to compare before testing

If a workplace or home network explicitly provides a standard proxy, first check whether it handles the traffic you need—not just what protocol it uses. To reach a specified internal network, use the WireGuard peer and routes already configured for you. If you need reliable large-file transfers and the current network supports UDP, include your existing Hysteria2 entry in the comparison. For short web pages, time to first response is more useful than peak download speed. If you regularly switch between cellular and Wi-Fi, measure recovery time after switching rather than testing only while stationary.

Decide what counts as a successful test first: for example, the destination loads fully, the connection recovers after waking the device, and name resolution works when needed. If two entries use different servers or egress points, results reflect differences in routing and server load too—even if you only changed the selection in Home. You can’t use that test to rank protocol performance. If you can’t test through the same egress, describe the result as “this entry works better on this network” and note a repeatable check for later.

Shadowsocks, HTTP & SOCKS5: forwarding and security boundaries

Shadowsocks: check the password and encryption method together

Shadowsocks is designed to pass app traffic through a relatively lightweight encrypted proxy, rather than assign a tunnel address to each device. The client specifies a destination, and the proxy connects to it from its own network. A typical setup provides a server address, port, password and encryption method; these details belong together. Don’t guess the encryption method from the port, or use a password from one method as the key for another. Even options with similar algorithm names may use different key requirements and message formats. If the details specify an additional transport or related settings, verify the whole set rather than borrowing values from another entry.

Keep the imported entry while troubleshooting. Check that the address and port come from the same record, then compare the full encryption method name and the format of the authentication value. If a manually pasted value causes an error, check for trailing line breaks, display separators or extra spaces in the field; don’t “fix” a key by deleting valid characters. If the proxy ingress connects but the destination keeps failing, try another destination you can already access and check whether Global Routing sends the request through the selected entry. If both checks look fine, ask the service provider to verify the ingress and server status rather than mistaking a routing issue for a password problem.

HTTP & SOCKS5: standard forwarding isn’t transport encryption

HTTP proxies were developed to forward web requests. For ordinary HTTP requests, the proxy can receive and forward the requests themselves. For many HTTPS connections, the client first sends a CONNECT request to establish a byte stream to the destination, then negotiates TLS with the destination site through that stream. The certificate shown by the browser is usually the destination site’s certificate; it doesn’t show that the connection between the client and proxy ingress also uses TLS. If your details explicitly say the proxy ingress uses TLS, select the corresponding type and verify the ingress identity. Don’t enable that setting just because the destination uses HTTPS.

SOCKS5 abstracts requests to a destination host and port, without assuming web traffic. It defines operations such as TCP connections and UDP ASSOCIATE, but whether a particular ingress supports UDP depends on its server configuration—and the client’s forwarding path must support it too. Standard SOCKS5 doesn’t provide general-purpose encryption for app data. Username-and-password authentication isn’t a substitute for verified transport security. If your details specify HTTP, don’t configure SOCKS5; even if the authentication fields look the same, the initial handshake is incompatible.

Check coverage with three separate tasks

First, test a commonly used HTTPS destination to verify basic connectivity and certificate handling. Next, test a non-web app you actually need; a successful browser test doesn’t prove that every app works. Finally, if you need UDP, test it with a real task in the app that uses it. If ordinary web browsing works but a real-time service fails, its traffic may not be using the same policy, the server may not forward UDP, or the destination may have different connectivity requirements. Whether the proxy resolves a destination domain depends on whether the client sends the hostname or an already-resolved address to the ingress. Don’t infer the current DNS path from a generic “supports domains” claim.

On iOS, the processing overhead of an encryption method alone doesn’t determine battery use. Repeated short connections, retries after failures and requests made while the device is asleep can all make the same entry appear more power-hungry. If you only access a few services you’re authorized to use, first check whether an existing standard proxy provides the required features. If the connection between the ingress and device needs protection, make that a requirement rather than trading it away for a speed result. Note whether each test involved web browsing, file transfers or real-time tasks; don’t generalize results from one traffic type to every use case.

VMess & VLESS: authentication IDs, transport and security settings

Understand what each protocol is designed to do

VMess is designed for authenticated proxy sessions, handling the user ID and protocol-level message protection within the connection protocol, with an additional transport layer available as required by the deployment. VLESS takes a slimmer approach, handing forwarding requests to the server with a lightweight header and identity ID; common VLESS configurations rely on an outer transport or security mechanism to protect the connection. Both commonly use a UUID as an authentication ID. The UUID identifies an authorized client to the server; it doesn’t determine whether the protocols are interchangeable and isn’t a TLS key or certificate. Don’t copy an authentication value from another entry to fill in a blank.

For VMess, check the address, port and ID, as well as the specified encryption, transport and security layer. If the ingress is reachable and all fields come from the same source but the session is still rejected, check that the device date and time are set automatically. VMess authentication involves time, so an inaccurate system clock can cause valid credentials to be rejected. For VLESS, treat flow as a setting required by a specific deployment, not a performance mode you can switch at will. Use the known server settings and the fields actually shown in the app to decide whether to enter it and what value to use.

Compare transport settings as a group

First confirm the transport specified by the server, then check its required fields. For example, with WebSocket, the request path identifies the service at the ingress; the virtual host field may tell the ingress which site to route to. Preserve the path exactly, including its leading slash, letter case and any other details provided. A blank field may reflect a server default or mean that the transport doesn’t use it. Without confirmed details, don’t apply a path from a different transport. If an ingress uses a reverse proxy, a successful TLS handshake still needs to be followed by a valid WebSocket handshake; otherwise, the connection may stop at the outer layer without reaching VMess or VLESS authentication.

The server address, the server name used for TLS and the HTTP host information may look alike but serve different purposes. The address determines where the connection goes. SNI specifies the expected name during the TLS handshake, and the client must also verify the server certificate as configured. HTTP host information routes requests after the connection is established. Making all three the same won’t automatically fix a configuration, and making them different isn’t necessarily wrong. Compare each value with the same server record; don’t rewrite values based on how a domain looks. In particular, changing the address doesn’t mean you should also change the expected certificate name to match it.

Find the failure stage instead of repeatedly changing settings

If the ingress address fails to resolve, first check the address and the current network’s DNS resolution. If the connection times out before a handshake, check the port, network path and server status. For a certificate error, verify the server name, certificate validity period and device clock; don’t disable verification. If TLS succeeds but WebSocket doesn’t connect, check the transport, path and host settings. Only after those stages succeed should you focus on the UUID, protocol settings and remote authorization. Error reporting varies between implementations; a generic “connection failed” is an observation, not a reason to skip these checks and jump to a conclusion.

To compare VMess and VLESS, first test each of two complete, working configurations you already have. If they use different ingresses, WebSocket paths or TLS setups, attribute the result to the specific entry rather than to protocol overhead. For short web pages, connection reuse, DNS caching and handshake round trips are often more noticeable than header differences. Switching entries may rebuild some connections, so record the first visit separately from repeat visits. Otherwise, the first entry bears the cost of a cold start while the next may benefit from cached data, reversing the apparent result.

Trojan: TLS handshakes, passwords and certificate checks

Distinguish server identity from client authorization

Trojan is designed to carry authenticated proxy requests inside a TLS connection. The client first establishes TLS with the ingress and verifies its identity; only then does it send protocol authentication and forwarding details through the connection. The password tells the ingress whether the client is authorized to use the service; it doesn’t prove the server’s identity. The certificate helps the client verify the server; it doesn’t prove the password is correct. Either check can fail independently. An authentication failure reported by the server doesn’t mean its certificate is invalid. A certificate mismatch reported by the client can’t be fixed by changing the password.

When entering details you already have, first confirm the protocol, SERVER and port, then check Password, SNI and the specified transport settings. A port number only identifies where the service listens; using a common TLS port doesn’t prove the service uses Trojan. A domain and an IP address aren’t interchangeable: if the connection details use an IP but require a particular domain for certificate verification, keep the name specified by the service provider. Don’t change SNI to the IP. If the details specify an additional transport, enter the complete set of settings instead of relying on defaults for a basic setup.

When you see a certificate warning, check each possible cause

First, check the device clock. A significantly incorrect date can make a valid certificate appear not yet valid or expired. Next, verify the expected name and address: do they come from the same server record? Does the name include a path or port by mistake? Does the current network resolve the address to the expected ingress? Finally, check the server’s certificate chain and validity period. If the same configuration produces different certificate errors on different networks, note the network, time and error type for the service administrator to investigate. Don’t accept an unknown certificate or mistake a network sign-in page for the destination service.

Allow Insecure isn’t a connection compatibility setting. Skipping certificate checks may leave a TLS session marked as encrypted, but you lose reliable verification of who you’re connected to. The recommended approach is to keep verification enabled and ask the administrator to confirm the correct name and trust chain. If your organization has its own certificate requirements, follow its approved device management process. Downloading a certificate from an unknown page or treating a verification error as a prerequisite for connecting doesn’t resolve uncertainty about identity.

If the connection works but an app doesn’t, change what you test

First test a destination you know is accessible to see whether both the ingress handshake and forwarding work. A response in Connectivity Test alone doesn’t prove that every destination is reachable. Check the app’s actual domain, the port it uses and the active policy, then determine whether the issue is at the destination, with name resolution or with the app’s own certificate checks. If only one destination fails, try another known destination without changing authentication details. If several tasks fail, check ingress authorization, whether the entry has been updated and which proxy entry is actually selected.

For iOS users, Trojan performance differences often show up during the initial connection and connection reuse. If short requests can’t reuse an existing connection, the extra handshake wait accounts for more of the total time. Longer transfers are more affected by egress bandwidth, destination throttling and signal quality. Don’t infer long-file speeds from a single first-byte result, or conclude that TLS itself is draining the battery just because you see activity while idle. For a field-by-field guide, see Trojan settings explained. To continue troubleshooting, check server identity, client authorization and destination access in that order.

WireGuard: peer public keys, AllowedIPs and keepalive

Think of WireGuard as a network tunnel, not a web proxy

WireGuard is designed to create encrypted network-layer tunnels using a relatively compact mechanism. Peers are identified by public keys and exchange packets over UDP; the tunnel carries IP packets, not individual web requests. So you need to check not only which peer is authenticated, but also which destinations are routed to it, which address the tunnel uses to send data, and how the remote end returns responses. A server address and port alone aren’t enough to recreate a working configuration. Don’t enter a standard proxy password in a key field.

If your details include PrivateKey, it belongs to your device and should be stored on a device you’re authorized to use. The peer’s PublicKey identifies the remote end; it isn’t the private key your device uses to prove its identity. Endpoint is the remote address and port used to send encapsulated packets, not the address assigned to your device inside the tunnel. If your details include a preshared key, it’s an additional value both sides must share. You can’t derive it from the public key and shouldn’t fill it in yourself. If you find that two devices are unexpectedly sharing the same access identity, ask the administrator to check how the configuration was assigned rather than assuming different connection results are caused by device hardware.

Understand the relationship between AllowedIPs and routing

AllowedIPs is used both to select a peer for outgoing traffic and to check the source range of incoming traffic. Adding a network range associates those addresses with that peer; it doesn’t guarantee that the remote end has a route or authorize access there. Whether Shadowrocket sends a request through this entry also depends on higher-level settings such as its routing policy. So check separately whether a rule matches the entry and whether the entry can send the destination IP to an appropriate peer. If you only need to access specified private networks, don’t expand the allowed range to all addresses to mask a specific missing route.

If a known IP is reachable through the tunnel but an internal domain isn’t, first check the specified DNS service and the network it’s on; don’t rush to change keys. If two sites use overlapping private address ranges, your device may treat an address as local on the current Wi-Fi network even though the organization uses the same address. Record both ranges and the test destination so the administrator can check the routing policy, the network ranges inside the tunnel and the remote return path. If short requests work after the handshake but larger ones are unreliable, check the path’s permitted packet size and any specified MTU requirement. Don’t lower it arbitrarily based on one failed webpage.

Keepalive maintains reachability after idle periods; it’s not an always-on speed boost

On networks that expire idle mappings, PersistentKeepalive can periodically send small packets to maintain the necessary UDP mapping, as required by the service setup. This is mainly for cases where traffic needs to arrive from the peer after a long idle period. It won’t fix an incorrect remote route or restore a blocked UDP path. First check basic connectivity during active use, then test whether the connection recovers after the device has been idle with its screen off. If idle recovery is required, keep the configured keepalive setting. If it isn’t required, don’t shorten the interval as your default troubleshooting step.

On iPhone, frequent, short background transfers can repeatedly wake network activity. Small packets don’t necessarily mean the wireless radio stays active for only a short time. When comparing battery use, also note whether On Demand is enabled, whether the network switches frequently and whether there was ongoing data transfer before the test. If the handshake fails only on cellular or a particular Wi-Fi network, first check UDP connectivity and the ingress on that network. If both networks complete the handshake but a specific subnet fails, check AllowedIPs, the return route and access permissions for the service.

Hysteria2: QUIC, bandwidth settings and network requirements

Check the UDP path before assessing high-latency performance

Hysteria2 is designed for networks where latency, packet loss and available bandwidth can vary, using QUIC over UDP to carry proxy traffic. QUIC combines encrypted handshakes, reliable transport and management of multiple streams. Retransmitting data on one stream typically doesn’t block delivery on other streams as directly as it can over a shared TCP byte stream. However, the streams still share network capacity and are all affected by congestion, wireless signal and server load. “Uses UDP” doesn’t mean the data is unreliable: reliable transfers still use acknowledgements and retransmissions, handled by the transport layer.

First check whether the current network can reach the UDP port used by the ingress. Opening a webpage on the same domain only shows that the webpage’s connection worked; it doesn’t prove the required UDP port is reachable. If testing both Wi-Fi and cellular, record the results separately. If one network consistently fails and the other works, distinguish a network path issue from a service issue before changing authentication settings. If both fail, don’t immediately assume UDP is blocked: an incorrect ingress address, authentication details or certificate issue can also prevent the session from starting.

Check authentication, certificates and rate settings separately

Use your existing details to check the address, port and authentication value, then verify the name and trust requirements for TLS. Don’t use the subscription URL as an authentication value or fill in Hysteria2 settings with fields from another protocol. If your details include upload and download bandwidth values and the app provides corresponding settings, first confirm the units and direction of each field against the service administrator’s requirements. Upload and download refer to different traffic directions, so don’t set both to the same number just because a speed test reports one peak. Before changing a value, check whether it declares available bandwidth or limits transfer speed; behavior also depends on the implementation and server policy.

Bandwidth settings don’t add network capacity. Setting a sending rate above actual capacity can increase queuing and packet loss: download numbers might briefly rise while web interactions slow down. Settings that are too conservative can also prevent long transfers from using stable available bandwidth. Peak speed often differs from stable speed on mobile networks, and an office Wi-Fi result shouldn’t be copied directly to cellular use. If your service details don’t require a setting, keep the imported values and default congestion control. Don’t use a single speed test as the basis for a change unless you can repeatedly measure the current path’s stable capacity.

Test sustained transfers and the first request after idle

For a short webpage, note the time from name resolution to the first response and whether repeat visits differ from visits after idle. For a large file, record completion time, speed variation and any retries. If you have two working entries, alternate the same task to the same destination; compare transport behavior only if the egress and network paths are sufficiently similar. Run another short test after switching between Wi-Fi and cellular. Even if a transport supports connection migration or fast recovery, whether a specific session continues depends on the app, ingress and network conditions. Don’t assume it will be uninterrupted based on protocol features alone.

If UDP is unreliable on a network you use often, compare it with another authorized entry that uses a transport suited to that network. Record three outcomes: whether the task completes, how quickly it recovers after a failure, and whether the device shows unusual activity over time. Higher peak speed doesn’t make up for everyday short requests that repeatedly time out. If the issue happens only after switching networks, first check which network iOS is currently using. Then determine whether the ingress is unreachable, the old session failed to recover or the destination app is waiting for its own retry interval.

Global Routing: distinguish protocol connections from rule matches

Three modes, three different questions

The entry selected in Home answers “Which ingress should I use if traffic is sent through a proxy?” Global Routing answers “What determines where this request goes?” In Config mode, rules in the selected configuration determine the policy. Proxy mode lets you check access through a proxy; Direct mode provides a comparison without the proxy. Switching modes doesn’t change the protocol or server settings. Keep other settings unchanged when comparing the three modes, and try to trigger a new connection; existing connections may continue using the path they were established with.

Compare routing to the same destination
ModeUseful for checkingWhat the result doesn’t prove
ConfigWhether the expected rules and policy are appliedIf it fails, check rule order and the destination actually matched
ProxyWhether the selected proxy entry can complete the same taskSuccess doesn’t mean Config mode will send this request through the proxy
DirectWhether the destination is reachable directly on the current networkSuccess doesn’t mean the proxy ingress address and authentication are correct

Start with domain rules, then check whether the request matched an IP rule

The three lines below are examples of rule entries in a Shadowrocket .conf file. They illustrate matching order; they aren’t a general-purpose replacement for your existing configuration. DOMAIN-SUFFIX matches domain suffixes; the example shows how a root domain and its subdomains can use the same policy. GEOIP matches based on IP address location data, not browser language, account region or device location. FINAL is the fallback when none of the preceding conditions match. The uppercase PROXY and DIRECT in the example are rule policies, not the same settings as the mode labels shown in the app.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

Rules are usually checked in order. To create an exact exception for a domain, check whether a more specific DOMAIN rule already exists and appears before a broader suffix rule. With DOMAIN-KEYWORD, consider that the string might appear in unrelated domains. For IPv4 and IPv6 address ranges, check IP-CIDR and IP-CIDR6 separately; adding an IPv4 condition won’t cover an IPv6 address for the same destination. If an app connects directly to an IP, a domain rule may not have a domain to match. Before editing, note which request you’re trying to fix; don’t change unrelated rules as a group.

A destination can load even when it takes the wrong route

Test a known destination in Config mode and check the domain or address actually used, the matching rule and the resulting policy. If connection logs are available, you only need to extract those three details. A webpage can load content from several domains, so the main page opening doesn’t prove that its static assets or app APIs use the same rule. If Proxy mode works but Config mode fails, first check whether an earlier rule routed the request to DIRECT or REJECT, and whether the actual request used a domain or a resolved address. If both modes fail but Direct works, focus again on the ingress, transport and authentication.

If both direct and proxy connections fail, don’t start by changing the protocol. Test a known working destination on the same network to rule out a problem at the destination. Check for a network sign-in page, DNS issues or connection reuse within the app. If the result is still unclear, restore the original settings, keep the minimum steps needed to reproduce the problem, then look up the symptom in Frequently asked questions. To review the initial setup steps, return to the setup tutorial. For everyday switches and modes, see the settings guide.

iOS testing: record response time, throughput, recovery and battery use separately

Speed isn’t a single number—define the task first

Web browsing involves several stages: name resolution, connection setup, waiting for the destination to respond and loading resources. Large files depend more on sustained throughput and retries, while messaging and real-time tasks may be more sensitive to jitter and recovery after a disconnection. Before testing, record the device, network type, proxy entry, Global Routing mode and task. Alternate tests on the same device in the same location to avoid comparing a Wi-Fi test with a cellular test. Use the same destination too. If you can’t keep the egress the same, describe how the entries performed rather than ranking the protocols.

Test each entry with an initial task and a repeat task. The first test can reveal connection setup costs; the repeat may benefit from existing connections and system caches. Record these results separately. For a short webpage, note whether the main content finished loading; for a large file, note whether it completed. If a test fails, record whether a retry succeeded instead of deleting the slow result. Connectivity Test is useful for a quick comparison, but its destination, route and request may differ from those of a real task. Don’t treat the latency from a single test as the whole picture.

Compare battery use during equivalent idle periods

On iOS, background activity, wireless signal and retry frequency can all affect battery use, in addition to protocol processing. Downloading a file with the screen on and leaving the device idle with the screen off are different workloads; don’t combine them into one conclusion. To compare idle periods, use the same network, similar signal conditions and the same screen state at similar times of day. Avoid running large syncs at the same time. Record the starting and ending battery level, elapsed time and any notable background activity in battery statistics. Don’t extrapolate from a tiny change over a short period; repeat the test across several comparable time periods.

System battery statistics can help identify activity sources, but they don’t measure the power use of one protocol in isolation. A weak wireless signal can trigger more retries; frequent network changes can also cause connections to be re-established. WireGuard keepalives, Hysteria2 retransmissions and repeated reconnects by TCP-based entries are all possibilities to investigate, not conclusions you can draw from battery drain alone. First identify whether the issue happens during active use, while idle or after a network switch, then test under the same conditions. If another app is mainly responsible for activity while idle, isolate that variable before comparing entries.

Test On Demand as a separate variable

On Demand connects when specified conditions are met. For a device that only needs a connection in certain situations, compare on-demand connection with keeping the connection active. Frequently meeting the trigger conditions can cause repeated session setup, so one option isn’t inherently more power-efficient. Keep the protocol, server and task fixed while changing only the connection trigger, then observe idle activity and recovery time. Next, keep the trigger fixed while comparing entries. If you change the server, configuration mode and on-demand conditions all at once, you won’t know which change to keep—even if the result improves.

State your final choice in terms of concrete conditions: which existing entry reliably completes the tasks you need on networks you use often, when you need another configured ingress, and how to get a timely recovery after idle. If the main issue is repeated reconnects after the screen turns off, see Troubleshooting On Demand and background battery use. If the issue occurs during initial import or when switching Config, check the app’s state against 10 common beginner questions. For follow-up tests, record only the protocol, scenario, result and failure type. Don’t include authentication details or internal destination addresses.