Shadowrocket Protocol Reference

01 · Choosing a protocol: understand the connection layers

Your existing service determines the available options

Selecting a type in Shadowrocket’s Add Server screen tells the client which communication format to use; it does not make the remote server switch to that protocol. The same Address and Port may not accept multiple protocols. Changing the type only makes sense if the server provides a matching entry point. Before you start, note the protocol name, address, port, authentication details and transport settings given by your service. If you import details through Subscribe, keep the imported settings as they are. Don’t change a recognized type just because another name looks more familiar.

A protocol mainly defines how the client and server exchange authentication and proxy requests. The transport determines how those messages travel, while TLS can encrypt the connection and verify the server’s identity. All three may appear in the same set of connection details, but they serve different purposes. For example, VLESS and WebSocket are not mutually exclusive protocol choices: VLESS describes the proxy layer, while WebSocket may provide the outer transport. Understanding these layers explains why a correct UUID may still fail because of a path or certificate issue.

Break a connection into checkable settings

These settings depend on one another. If the address cannot be resolved, changing authentication fields usually won’t help. If the server completes the TLS handshake and then rejects authentication, changing DNS won’t fix a password error. The first log entry directly related to the failure is more useful than a generic timeout message at the end. Note whether the failure occurred during name resolution, connection setup, authentication or access to the destination to narrow down what to check.

There’s no universal ranking for speed or battery life

On iOS, real-world performance depends on wireless signal, latency, packet loss, server load and the destination, among other factors. Protocol overhead is only one part of the picture. A design with fewer handshake steps may make a difference for frequent short connections; for large, sustained transfers, link capacity and congestion control are often more important. Don’t treat a single Connectivity Test result as a measure of throughput across the entire route, or as a prediction of performance for every destination.

Battery use also can’t be judged by protocol name alone. Encryption takes resources, but frequent reconnects, an active wireless radio, aggressive keepalives and repeated retransmissions can matter just as much. For a fair comparison, keep the device, network, screen brightness and task consistent, and observe initial loading, sustained transfers and idle periods separately. Without controlling for these conditions, you can’t reliably conclude that one protocol is always more efficient or faster.

Also distinguish support for a protocol from support for every possible combination of its settings. Whether a particular outer transport, authentication extension or specialized field is available depends on the current Shadowrocket interface and your existing service’s documentation. If the client has no matching field for a setting in your details, don’t put it in a note or another input field at random. First check which layer it belongs to, then ask your service provider if clarification is needed.

02 · Shadowsocks: shared keys and encryption methods

Design goals and connection model

Shadowsocks is designed for encrypted proxy connections and typically uses a shared key to protect communications. The client takes a request from an app, sends the destination details and data to the remote server in the agreed format, and the server connects to the destination. It is not the same as a full IP-layer tunnel: the protocol handles proxy forwarding, but an address alone does not define system-wide routing, internal address assignment or peer relationships. This keeps the settings relatively focused, but the client’s routing policy still determines which requests go through the proxy.

When working with Shadowsocks, treat the encryption method as part of protocol compatibility—not as an adjustable security-strength slider. The client and server must use matching methods, key rules and message formats. Method names that differ by just a few characters may refer to different designs; don’t treat them as interchangeable because they look similar. Newer method families may also require key material in a specific format or length, so an arbitrary text password may not be valid.

How Address, Port, Password and method fit together

Enter the hostname or IP address provided by your service in Address. Don’t paste an entire share link into the address field. Port is the port where the server listens for this protocol, not an arbitrary number from a web address. Enter Password exactly as provided, watching for extra spaces, line breaks or full-width punctuation introduced when copying. Check the encryption method character by character. Don’t select a newer-looking option just because the interface offers it; it must match the server configuration.

Common AEAD methods combine data confidentiality with integrity checks, allowing the receiver to reject messages that fail verification. If the key or method doesn’t match, the connection may simply close, the destination may not respond, or an authentication-related error may appear—there may be no explicit “wrong password” message. A successful connection to the remote port therefore doesn’t prove that every setting is correct. Test whether the client can access an actual destination through the connection. After importing a share link, check its type and fields rather than just confirming that a name appears in the list.

TCP, UDP and additional transports are separate settings

Web traffic commonly uses TCP, while some apps rely on UDP; the two may behave differently. The server, client settings and intermediate networks must all allow the relevant forwarding for a complete path. Enabling a UDP-related option won’t give that capability to a remote server that lacks it. Conversely, a website opening successfully doesn’t prove the UDP path works. Test each capability against the apps that need it instead of attributing every failure to the server being unreachable.

Some connection details include additional transport or encapsulation settings. These are separate from the Shadowsocks password and encryption method. Enter them only if the existing service specifies them and the current interface has matching fields. If an imported link is missing an additional setting, record the original configuration before filling it in manually, and change one thing at a time. Changing the method, port and transport together makes it difficult to identify what caused a change.

Assessing trade-offs on mobile devices

Shadowsocks has a relatively focused set of settings, making it a useful starting point for understanding how the endpoint, key and method fit together. That doesn’t mean it performs best on every network. Sustained transfers are still affected by server capacity and packet loss; short tasks can also depend on name resolution and connection setup. When an iPhone switches from Wi-Fi to cellular, an existing connection may need to be re-established. Recovery depends on the entire path, not just the protocol name.

To troubleshoot, narrow things down in four steps: confirm that Address resolves, check that the port belongs to the intended entry, verify the method and key, then distinguish between TCP and UDP requirements. If the connection is established but only some domains fail, check the rules and DNS in the Testing and routing section. Don’t keep changing protocol settings that have already authenticated successfully to fix an issue with a single destination.

03 · VMess and VLESS: authentication, transport and security

Similar fields don’t make them interchangeable

VMess and VLESS both commonly use a UUID as a user identifier, so imported profiles may show similar address, port and identity fields. But they are different communication formats; changing the type while leaving everything else untouched won’t make them interchangeable. VMess includes its own authentication and data-protection mechanisms. VLESS has a more minimal base design and does not provide payload encryption equivalent to VMess, so it generally needs a correctly configured secure transport. The available server entry determines which one to use.

These design differences don’t translate directly into a performance ranking. Although VLESS assigns fewer responsibilities to the proxy layer, outer TLS or another security mechanism still has its own overhead. VMess performance also depends on transport, multiplexing and network conditions. A profile that says only “VLESS” without specifying the outer security settings is incomplete. The presence of an authentication field doesn’t mean the connection also verifies server identity and encrypts data.

UUID, time and authentication failures

A UUID is a structured identifier. Preserve it exactly, including its separators; don’t enter a display name, subscription URL or another password in its place. VMess authentication involves time, so a significantly incorrect device clock may prevent a connection. If authentication fails, check that the system date and time are correct. For compatibility fields in imported profiles, follow the server’s documentation and the options available in the current client. Don’t copy a number from an old guide and overwrite a value that imported correctly.

A correct UUID doesn’t guarantee that all authentication requirements are met. The server may have disabled a user, restricted an entry or updated the connection details. If a connection still fails after a subscription update, compare the protocol type, port and transport settings in the old and new records—not just their names. Two entries with the same name may have different settings, while different names may be labels for the same entry. Always check the actual fields.

WebSocket, Host, path and SNI

WebSocket provides an outer transport for proxy data, and its path must match the server’s routing configuration. Paths usually start with a slash; capitalization and other characters may also matter. Host can be used to select a virtual host at the HTTP layer, while SNI specifies the server name during the TLS handshake. They belong to different layers. Even if a profile gives them the same value, that doesn’t mean they must always match.

When Address is an IP, the service documentation may still require a domain name for SNI because the connection address and certificate identity are not the same thing. Use the supplied name if it passes verification; don’t bypass an error by disabling verification. If the outer transport hasn’t connected, the server may not even have checked the proxy-layer UUID yet. That’s why it’s important to distinguish TLS, path and authentication errors.

Check the task, not a protocol ranking

On mobile networks, extra encapsulation can add handshake and packet overhead or affect how a connection recovers, but the real impact depends on the task. Pages with many short connections, long-lived sessions and sustained downloads have different needs. If a combination works on Wi-Fi but fails on cellular, first check name resolution, outer transport and port reachability for the same entry, then investigate the protocol itself. For an overview of Config, see the feature guide to avoid mistaking a routing issue for a protocol compatibility problem.

04 · Trojan: TLS server verification and password authentication

The separate roles of connection security and user authentication

Trojan uses a TLS-based connection to handle proxy requests and user authentication over a protected channel. Keep server identity and user identity separate: the TLS certificate helps the client verify which server it is connecting to, while Password lets the server check whether the user is authorized. A correct password doesn’t make a connection safe to use if certificate verification fails; a valid certificate alone won’t allow proxy access if the password is wrong.

This distinction means TLS is not an optional feature to toggle while “trying to improve speed.” For a standard Trojan connection, don’t disable TLS during troubleshooting and expect the remote server to continue recognizing the same protocol. If your details include specialized transport settings, check the entire combination rather than assuming every Trojan connection uses just three fields. The base protocol and any additional transport must both match; an error at either layer can block the request.

Address, Port, Password and SNI: what to enter

Address determines where the network connection goes. Use the domain provided by your service, or an IP address if the documentation specifies one. Port must be the port for that Trojan entry; TLS doesn’t imply a fixed port. Enter Password exactly as provided, and check whether copying added an invisible line break. For SNI, use the server name specified by the service. It may match Address, or it may be a separate domain when Address is an IP.

Certificate verification can depend on name matching, validity dates, the trust chain and the device clock. SNI doesn’t make an arbitrary domain’s certificate valid; it tells the remote server which name the client expects, so the subsequent verification can use that name. If the certificate name doesn’t match, check for typos, outdated service details and the server’s certificate configuration. If the device date is wrong, correct the system time first. Disabling verification changes the security of the connection and should not be a long-term fix.

Read connection failures in order

If Address won’t resolve, the problem occurs before the client reaches the server. If the remote server refuses the connection, check the port and whether the service is listening. For a TLS name or trust error, focus on server identity verification. The server can process Trojan authentication and forward traffic to a destination only after the TLS channel is established. Checking in this order avoids repeatedly changing Password before the certificate is valid and cuts down on aimless combinations of settings.

The channel and authentication may both succeed while a website still won’t open. Check DNS resolution for the destination, connectivity from the remote server to that destination, and whether the local request actually uses this connection. If only one website fails, don’t immediately conclude that the entire Trojan entry is broken. Compare with another accessible destination and use request records to identify where the failure occurs, rather than relying only on the connection toggle in Home.

Performance and use on mobile networks

TLS requires a handshake to establish a connection, and its cost is more noticeable at high latency or when connections are frequently re-established. Once a session is active, transfer performance depends more on link capacity, congestion and the destination’s response. TLS doesn’t automatically make a connection slower, and a quick result from one test doesn’t guarantee stable performance later. On iOS, wireless network changes, sleep and wake can affect existing connections, so observe recovery separately.

If you already have complete Trojan settings, focus on whether certificate verification succeeds, Address and SNI are clearly specified, and the connection recovers after a network change—not on piling on unknown settings. For a field-by-field review, see the Trojan settings guide. Keep a copy of a known-working configuration and test changes on a duplicate. After a subscription update, make sure you’re checking the active record, not an older manually created copy.

05 · HTTP and SOCKS5: what general-purpose proxies can and can’t do

An HTTP proxy and an HTTPS website are different things

An HTTP proxy uses a general-purpose proxy access model. It handles requests in its supported format and can establish a connection to a destination using mechanisms such as CONNECT. A common misconception is that if a destination uses HTTPS, the connection between the client and proxy server must also use TLS. These are separate connections to consider. HTTPS primarily protects application data between the client and destination website. Whether the proxy endpoint itself uses TLS depends on its type and configuration; you can’t infer this from the destination URL.

Even when HTTPS protects the destination content after CONNECT, the proxy still needs to know which destination to connect to and forward traffic there. So encryption of the destination content doesn’t mean the proxy credentials and all connection metadata receive the same protection. If your service provides an encrypted HTTP proxy endpoint, use the type and security options specified in its documentation. Don’t change a standard HTTP endpoint to another type at random and interpret a failed handshake as a username error.

SOCKS5 negotiation, authentication and UDP

SOCKS5 is a general-purpose connection-forwarding protocol. It negotiates an authentication method and the requested operation, and can specify a destination address and port. It also defines a UDP association mechanism, but the base protocol does not provide channel encryption like TLS. A username and password control access; they are not encryption. After entering credentials, check how the client-to-proxy connection is protected and which capabilities the server actually supports.

The SOCKS5 specification includes UDP features, but that doesn’t mean every service endpoint or network path supports them. The server implementation, access policy, intermediate networks and current client settings all affect the outcome. If TCP web browsing works but a UDP-dependent app fails, first check whether the service allows UDP, then verify the forwarding path. The presence of “SOCKS5” in the protocol name doesn’t rule out limitations in the protocol setup or endpoint.

Fewer fields still need careful checking

Common fields for both types include Address and Port, plus a username and password if the service requires authentication. Follow the supplied settings; a blank username isn’t equivalent to an arbitrary one. If credentials contain special characters, use a reliable import method or enter them in separate fields to avoid encoding issues when manually assembling a share link. The profile name is only for local identification and can’t replace an authentication field.

Name resolution and real-world use

A request may carry a domain name or an IP address resolved locally, affecting where name resolution occurs and how routing rules apply. Don’t assume from the “HTTP” or “SOCKS5” label that every domain is resolved remotely. When troubleshooting, check Shadowrocket’s DNS settings, the format of the destination request and the active rules. If a domain fails but a known address works, investigate the resolution path rather than immediately changing the username or port.

These types can connect to existing infrastructure when you have a configured workplace proxy, a test environment or a clearly specified general-purpose proxy endpoint. They aren’t universal replacements for other protocols. On iPhone and iPad, real-world performance still depends on authentication, connection security, destination reachability and the device’s network. If you need to restore the original routing policy, note the previous Global Routing mode and Config before making changes, so a test doesn’t affect every app afterward. For common issues, see Troubleshooting.

06 · WireGuard: peers, keys and tunnel addresses

From proxy requests to an IP-layer tunnel

WireGuard is designed as an IP-layer tunnel. It identifies peers with public keys and carries network packets over UDP. Unlike a proxy endpoint that may need only an address and password, WireGuard settings also describe tunnel addresses, peer identity and the address ranges to handle. Understanding these fields helps you determine whether the details are complete. A remote IP and port alone aren’t enough: the server must also know the client’s public key and have the appropriate address and forwarding settings.

When using WireGuard in Shadowrocket, distinguish the app’s handling of device traffic from the encapsulation provided by a remote protocol. An iOS VPN status indicates that the client has access to system networking features; it doesn’t mean every outbound connection uses WireGuard. Check the selected server type, Global Routing and Config to determine what happens. The VPN icon alone also doesn’t confirm that the tunnel address and remote peer are communicating correctly.

Private keys, public keys and optional shared keys

The client’s private key identifies the local peer and is used for key negotiation; keep it secure on your device and in your backups. The server’s public key identifies the remote peer. Don’t swap these fields or use the same value everywhere a key is required. The client’s public key is derived from its private key, and the remote server uses it to identify the client. If you change the client’s private key without updating the server, the existing authorization may stop working even if Endpoint stays the same.

Some services also provide a preshared key to add shared key material to the existing public-key mechanism. It is neither the client’s private key nor the server’s public key; enter it in the separate field specified by the service. Don’t post real keys in public screenshots, error reports or article comments. When troubleshooting, you can say whether a field is present and correctly formatted without sharing its value. Also remember that backups during device migration may contain sensitive keys; they aren’t just ordinary rule files.

Endpoint, allowed IP ranges and DNS

Endpoint is the reachable address and UDP port of the remote server. A tunnel address is an identity within the tunnel, so the two belong to different network layers. Entering an internal address as the public endpoint—or entering Endpoint in the tunnel address field—will break the connection. Address-range settings specify which destination or peer addresses may be handled. Their behavior also depends on how the client integrates with routing, so they aren’t simply equivalent to Shadowrocket’s domain rules.

Consider IPv4 and IPv6 separately. A configured path for one address family doesn’t prove the other has the same connectivity. If a domain resolves to IPv6 first but the tunnel or remote forwarding doesn’t support it, some destinations may fail. The DNS server also has to be reachable. If you specify an internal DNS address, confirm that it can be accessed through the existing tunnel. A DNS setting in the profile doesn’t mean the resolution path will work automatically.

Keepalives, MTU and mobile network changes

Keepalives can preserve a network mapping when needed, especially on networks where intermediate devices discard idle UDP state. More frequent keepalives can wake the wireless radio more often, so don’t shorten the interval just to “stay online.” Whether to use one, and which value to use, depends on the service details and network. A mobile network change can alter the client’s visible external address. WireGuard is designed to adapt to address changes after authenticated traffic, but recovery still depends on the new path carrying data.

MTU affects how much data a single packet can carry. Too large a value can cause fragmentation or packet loss on some paths; too small a value increases encapsulation overhead and packet count. If small requests work but larger pages or sustained transfers stall, check path MTU as one possibility—but it’s not a universal explanation for timeouts. First verify the keys and handshake, then check tunnel addresses, DNS and destination forwarding. Adjust MTU only when there’s evidence to support it. For backups and device migration, see the configuration migration guide.

07 · Hysteria2: QUIC, UDP paths and congestion trade-offs

Design goals and compatibility limits

Hysteria2 uses QUIC-based transport over UDP, with authentication and TLS-related mechanisms for proxy connections. Its design focuses on data transfer and congestion handling over challenging network paths, but that doesn’t guarantee higher speeds on every network. The protocol needs a working UDP path. If the current network can’t reach the remote port, changing bandwidth settings or the password won’t overcome that basic limitation.

The “2” in Hysteria2 is part of the protocol name, not the Shadowrocket app version covered on this page. When importing a profile, confirm that the service actually provides Hysteria2 instead of selecting a type based on a similar-looking name. Protocol generations, transport formats and optional settings can have compatibility limits; don’t assume the same address and credentials work across different types. Check the current interface and your service’s documentation to see whether a particular additional option is available.

Check the endpoint, authentication and certificate separately

First check the remote Address and UDP port, then verify the authentication details and TLS server name. Address points to the actual connection endpoint; SNI declares the expected server name for certificate verification. They may use different values depending on the service, but don’t guess. If you connect by IP and need domain-based verification, use the domain supplied by the service. Disabling certificate verification isn’t a substitute for missing connection details.

Some connection profiles include obfuscation or other additional settings. These don’t replace the authentication password and aren’t universal options that must always be enabled. Enter them only if the server is configured for them, using matching values. Missing, misspelled or unnecessarily enabled settings may prevent traffic from being processed before authentication. Compare each field against the supplied details; don’t change authentication, security and extra settings all at once and hope for the best.

A bandwidth value doesn’t set the connection’s actual capacity

If the current configuration offers upload, download or congestion-related settings, understand them as transport-control inputs—not promises about the server’s capacity. Some control modes use bandwidth estimates; others may determine values automatically. Check the documentation for the specific setting to learn when it applies. Entering a large number won’t improve the wireless signal, server capacity or destination. It may instead increase packet loss, queuing or interference with other tasks on the same network.

When entering a value, distinguish bits from bytes and check the units shown in the interface. A home broadband plan’s advertised speed isn’t the same as the iPhone’s stable Wi-Fi throughput at a given moment, and it says even less about cellular upload capacity. If you don’t have reliable measurements, keep the service’s recommended value or use an explicitly supported automatic option rather than basing it on a brief peak. Compare completion times and failure rates, and check whether other apps are affected; don’t focus only on a momentary maximum.

Packet loss, network changes and battery use

QUIC handles connections and reliable delivery over UDP, with its own management for different data streams, but it can’t eliminate packet loss on the physical network. Retransmissions and congestion control still matter when network quality declines, and changing wireless conditions can make previous estimates inaccurate. Some networks handle UDP differently from TCP, so a working TCP endpoint on the same device doesn’t prove that the Hysteria2 UDP path is available.

On iOS, sustained traffic, retransmissions and keeping the network active can all affect battery life. Observe sustained transfers and idle periods separately, and try to account for screen use, background syncing and device temperature. A Wi-Fi-to-cellular switch doesn’t guarantee a seamless session just because QUIC has general migration capabilities; the server, client implementation and new network path all affect the outcome. If your main use is brief browsing and another connection is already stable, there’s no need to replace everything just because another protocol name sounds promising.

Test basic connectivity on the same network, to the same destination and at similar times before comparing repeated tasks. If only the UDP endpoint fails, prioritize checking port reachability and path details. If every endpoint fails, check the device’s network and the destination. Treat “the transport won’t connect” and “the connection works but tasks are slow” as separate problems. This helps avoid masking the real cause with unrelated setting changes.

08 · From protocol to request: testing, rules and troubleshooting

Start with a repeatable test

After checking the protocol settings, return to Home, select the connection to test and review Global Routing. Config mode applies the rules in the current configuration. Proxy mode sends relevant traffic through the selected proxy path, while Direct mode connects directly. These are routing modes, not different remote protocols. A website working in Direct mode doesn’t prove that the Trojan or Shadowsocks settings you just entered can connect.

Before testing, note the original routing mode and current Config. Choose a specific task, such as opening the same webpage and confirming that it loads completely. Connectivity Test can provide a clue, but its results depend on the method, destination and network at the time; it doesn’t replace a real task. An enabled system connection switch only means the client is handling network traffic, not that every request successfully passed through the remote server. Verify three things: the correct profile is selected, the request uses the expected policy, and the destination is reachable.

Rule order changes what you observe

Rules in Config are evaluated from top to bottom. The first match determines the policy. PROXY sends a request to the proxy policy, DIRECT connects directly, and REJECT blocks it. Even with correct protocol settings, a destination that matches DIRECT won’t use the proxy as expected. If it matches REJECT first, a later PROXY rule won’t be considered. When troubleshooting, check which rule actually matched before changing a connection that has already authenticated successfully.

This Shadowrocket .conf snippet illustrates rule order and contains no server details. Put domain exceptions before broader rules, use DIRECT for private address ranges, and end with FINAL to catch requests that matched nothing earlier. The domains in this example are for illustration only; these lines aren’t a complete configuration for every environment.

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

If DOMAIN-SUFFIX comes first, ads.example.com matches the broader rule, leaving the later exact reject rule with no chance to apply. Whether an IP rule is evaluated also depends on the address information available for the request and on resolution behavior. Don’t assume from the rule text alone that every domain will match a particular address range. For more on ordering rules, see Rule order and FINAL. For your first setup, follow the quick-start guide.

Choose the next step based on the failure layer

Change one setting at a time and record the specific results before and after. If records change after updating Subscribe, first confirm that you’ve selected the expected endpoint; a manually created copy may not update with the subscription. When reporting an issue, you can share the protocol name, failure stage, network type and a redacted outline of the settings, but remove the full subscription URL, Password, UUID and private keys. Logs may also contain destination details, so review them before sharing.

Choose based on the task and available connection details

For an existing general-purpose proxy setup, check the authentication, connection security and capabilities required for HTTP or SOCKS5. For an existing Shadowsocks, VMess, VLESS or Trojan endpoint, focus on matching the method, transport and TLS settings. For WireGuard details, check the peer, tunnel address and allowed ranges. For Hysteria2, start by verifying the UDP path and transport-control settings. These are areas to check, not a performance ranking.

Keep a connection only when its details are complete, identity verification works as expected, common tasks succeed repeatedly, and performance remains acceptable during real-world network changes and idle periods. Don’t sacrifice proper certificate verification or keep changing a stable configuration just to get a lower number in one test. For app purchases, system compatibility and restoring access, return to the App Store purchase and download guide. For connection issues and interface help, see Troubleshooting. This page explains how to assess a connection; the tutorial turns those checks into a step-by-step first setup.