For users who already have configuration details from their provider and are ready to add VMess or VLESS to Shadowrocket. This guide explains the differences between protocol authentication, transport, and TLS, then walks through the fields in Add Server and troubleshooting by layer. The key is to match the server configuration—not to treat a protocol name as a guarantee of speed or security.
1. Check your platform and configuration source
Shadowrocket is available across platforms: iPhone and iPad users can get it on the App Store for a one-time $2.99 purchase; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. See the download guide for both options. Getting the app and configuring a server are separate: a one-time app purchase does not include a service subscription.
This guide assumes you already have a provider and subscription. This site does not provide, sell, or recommend servers, subscriptions, or services. Before you begin, obtain the complete server parameters or a subscription URL from your provider. A server domain and UUID alone are usually not enough to recreate the configuration.
- Already have a subscription: Import it through Subscribe where possible to preserve the original protocol, transport, and TLS settings. Subscription updates may overwrite manual changes, so record the original values before troubleshooting.
- Already have a single server configuration: Confirm whether it specifies VMess or VLESS, then check the address, port, UUID, transport, and security layer.
- Only have a screenshot of the parameters: Ask your provider to confirm any obscured fields. Don’t guess the Host, SNI, or Path based on a similar configuration.
The steps below follow this sequence: Home → add server → Add Server. Field order may differ between platforms. Match fields by their meaning rather than assuming their positions are universal.
2. VMess vs. VLESS: Authentication, encryption, and alterId
VMess and VLESS can both use a UUID as a user credential, but they are distinct protocols—not two names for the same protocol. If the server is configured for VMess, select VMess in the client as well; changing Type to VLESS does not migrate the configuration. Migration requires the server to provide a corresponding VLESS endpoint and parameters.
| What to check | VMess | VLESS |
|---|---|---|
| User credential | Usually a UUID; it must match the user record on the server | Usually a UUID; it must also match the user record on the server |
| Protocol-level encryption | Supports encryption at the protocol layer; choose settings as required by the server | Does not encrypt payloads on its own; configure TLS or another security layer correctly to protect the connection |
| alterId | A VMess-specific parameter. Modern AEAD configurations typically use 0; don’t substitute a random value | No corresponding alterId setting; don’t copy it over mechanically from VMess |
| Transport | Can use TCP, WebSocket, and other transports, depending on what both client and server support | Also requires a matching transport; the protocol name alone does not determine the transport |
“VMess has protocol-level encryption” does not mean TLS is unnecessary. Likewise, “VLESS does not encrypt by itself” does not mean every VLESS connection is necessarily unencrypted. Check the proxy protocol and its security layer separately. What TLS protects depends on where it terminates; it does not guarantee the same protection for every subsequent hop.
Bottom line: choose Type to match the server parameters, not assumed performance
If you already have a VMess configuration, keep it as VMess. Add a VLESS configuration only when your provider explicitly supplies a VLESS endpoint. Don’t change Type, port, and transport all at once; otherwise, you won’t know which field caused the failure.
3. What to enter for TCP, WebSocket, and TLS
Think of the configuration in three layers: VMess or VLESS handles the proxy protocol and user authentication; TCP, WebSocket, and similar options carry the data; TLS secures the relevant connection and authenticates the certificate. The options may depend on one another, but they are not interchangeable. For example, enabling TLS does not automatically switch TCP to WebSocket.
Field checklist for two common setups
TCP + TLS
- For Type, select the VMess or VLESS option provided by your provider.
- For transport, select TCP. Enter the address and Port exactly as provided.
- Enable TLS and check the server name used for certificate verification.
- Don’t enter the Path from a separate WebSocket configuration.
WebSocket + TLS
- Select WebSocket as the transport; enabling TLS alone is not enough.
- Keep the leading slash in Path, for example,
/ws. - Enter Host as specified in the original configuration. It is used in the WebSocket HTTP request.
- Enter SNI as specified in the TLS parameters. Don’t assume it matches the connection address or Host.
The connection address, Host, and SNI may be the same or different. Only the server’s deployment details can determine the correct values.
For example, if your provider specifies Port 8443, keep 8443; don’t change it to 443 just because TLS is enabled. A WebSocket Path usually needs to match exactly: capitalization, a trailing slash, and query parameters can all affect routing. The path shown here is an example of the format, not a usable server parameter.
4. Review and save fields in Add Server
When adding a server manually, enter the fields that determine the connection target first, then the authentication and transport settings. This order helps distinguish a reachable port from an authentication or handshake failure, which can otherwise be mistaken for a network issue. If you’re troubleshooting a subscribed entry, keep the original intact so you can compare it later.
- Select Type. Open the add-server option from Home, then choose VMess or VLESS in Add Server. WebSocket is a transport, not a protocol type.
- Enter Address and Port. For Address, enter a hostname or IP without
https://or a web page path. Enter the port separately; it must be in the1–65535range and match the server. - Copy the UUID. Check the hyphens and remove any leading or trailing spaces. Don’t replace the UUID assigned by your provider with one you generated yourself. A valid format only means the value is correctly written; it doesn’t mean the server has authorized it.
- Check protocol-specific settings. For VMess, check the encryption option and alterId. Don’t enter a VMess alterId for VLESS. If the configuration includes additional parameters such as Flow, check whether the current client supports that combination. Don’t simply remove them and assume the result is equivalent.
- Set transport and TLS. Match the original configuration for TCP or WebSocket, then check TLS, SNI, and, where required, Host and Path. Ask your provider to confirm any special parameters that weren’t supplied.
- Save and select the entry. Return to Home and make sure the saved entry is selected, then turn on the connection. When the system first asks to add a VPN configuration, review the prompt and grant permission.
If the imported result differs from the one you entered manually, compare the fields—not just the displayed names. Entries with the same name may use different ports or transports, and the same server domain can host multiple incompatible endpoints. When sharing a screenshot for help, hide the UUID, subscription token, and other credentials, but leave the protocol type and error category visible.
5. Use Global Routing to distinguish protocol issues from rule issues
A successful save only means the entry was accepted; it doesn’t confirm that the server handshake completed. Run Connectivity Test from Home, then try the actual destination you need. Test results reflect only the specific test target and conditions at that time. A single latency value does not prove that every website, UDP traffic, or every rule will work.
Global Routing → Config
RecommendedRouting follows the rules in the current configuration. After confirming the connection, return here to check which rule and policy the destination actually matches.
Best for: everyday rule-based routing and final testing
Global Routing → Proxy
Temporarily route requests handled by the proxy through the proxy path, reducing the effect of rule selection on the test. You still need to confirm which server or policy is actually in use.
Best for: distinguishing server connection issues from Config rule issues
Global Routing → Direct
Use this as a direct-connection baseline. If the destination is reachable, that does not prove VMess or VLESS authentication succeeded.
Best for: checking the baseline direct connection between your local network and the destination
If a destination works under Proxy but fails under Config, check the rules and routing policy first instead of immediately switching protocols. In Config, DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches IP ranges, GEOIP matches using an IP geolocation database, and FINAL sets the policy used when no earlier rule matches. These rules won’t fix an incorrect UUID or TLS setting.
- Timeout: First check the current network and whether the server address and port are reachable, then check transport and the security layer. A timeout alone does not mean the UUID is wrong.
- Port is reachable, but the session fails: Check Type, UUID, VMess settings, TLS, and WebSocket parameters. A successful TCP connection does not mean proxy authentication succeeded.
- Only some destinations fail: Check DNS resolution, matching rules, the destination’s status, and the selected policy. Don’t replace all server parameters at once.
- Connection status changes automatically during testing: Check the existing Settings → On Demand configuration and note whether it triggers a reconnect. Restore the original behavior after testing.
6. Common questions about adding VMess and VLESS
Can I make up an address and port if I only have a UUID?
No. A UUID is a user credential; it doesn’t include the server location, listening port, or transport requirements. Get the complete parameters from your provider. At a minimum, check Type, Address, Port, UUID, and transport and security settings before opening Add Server.
Why can’t I connect even though VMess alterId is set to 0?
0 only applies to one VMess setting; it doesn’t validate any other fields. First confirm the original configuration uses modern AEAD, then check server time synchronization, UUID, encryption settings, port, and TLS in order. Don’t keep trying random alterId values.
Will changing VMess to VLESS make the connection faster?
You can’t simply change it. The server must provide a VLESS endpoint, with a matching port, transport, and security layer. Even when both endpoints are available, speed depends on the route, congestion, and server resources. Test each under the same network and destination rather than judging by protocol name alone.
What should I do if a subscription update reverts a Path I fixed manually?
Keep a record of the fields before and after the update, then confirm whether your provider changed the supplied parameters. For a temporary test, save a separate entry instead of continuing to edit the subscription-managed one. For a lasting correction, ask your provider to update the subscription source.
Can I use a VLESS configuration without TLS?
First confirm whether another explicitly configured security layer is in use and check your provider’s deployment instructions. VLESS does not encrypt payloads on its own, and a website using HTTPS does not prove that all information on the proxy connection is protected. If the security-layer details are incomplete, get them clarified instead of blindly disabling security options.
Get Shadowrocket and configure it
The iPhone and iPad version is a one-time $2.99 purchase on the App Store; check the listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. The download page covers both options and installation instructions for each platform.
The App Store developer is Shadow Launch Technology Limited, and the app ID is 932747118. Once you have your own configuration, follow the guides to import it, connect, and verify the setup.