Official Manual · Reference Guide

Shadowrocket
Complete User Manual

Check installation and permissions first, then work through servers, rules, connection records, and everyday settings. Instructions use the iPhone and iPad interface; the installation section also covers Mac, Windows, Android, and Linux.

The iPhone and iPad app costs $2.99 as a one-time App Store purchase. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free.

Use this page as a reference; you do not need to read it all before your first session. The setup guide walks you through a working first connection. This manual explains what each step depends on, how to check the result, and where to resume if something goes wrong. If you have already imported your settings, start with Global Routing or connection checks to avoid changing anything that is already working.

The steps below assume you already have your own subscription or server details. Configuration files, server details, and subscription URLs are three different things, with different uses and storage locations. Interface labels remain in English; the items shown on your device may vary with your current version of Shadowrocket.

01 / ACQUIRE

Get and Install: Choose the Right Device and Source

Install the app before setting up servers or configuration. This helps distinguish installation issues from connection problems. Get the iPhone and iPad version from the App Store for a one-time $2.99 purchase; the Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Find links for every platform on the downloads page. Desktop and Android installers are served from this site at /dl/shadowrocket/. Configuration text in a tutorial is not an installer, and a subscription URL is not a download link.

iPhone and iPad: Check the App Store Listing

Open the App Store product link from the downloads page and check the app name, Shadowrocket, the developer, Shadow Launch Technology Limited, and the app ID 932747118 in the product URL. The official icon should match these details; do not rely on the name shown in search results alone. Check the system requirements on the App Store page, and review the price and compatibility shown in your account’s storefront before purchasing. If the listing says your device is incompatible, check your device and OS requirements rather than repeatedly trying to import configuration.

The app is not available in the mainland China App Store. If you cannot find it, first check the storefront region associated with your Apple Account; a missing search result does not mean the app has been discontinued. You can check the region under Apple Account, Media & Purchases, View Account, and Country/Region in system settings; exact labels vary by OS version. Changing regions may affect your balance, active subscriptions, and payment methods, so read the system prompts first. For details, see App Store regions and storefront availability.

Desktop and Android: Choose the Right Installer

On a Mac, check the chip under About This Mac: choose the Apple silicon build for an Apple chip or the Intel build for an Intel processor. Do not identify the version by file size alone. On Windows, choose the appropriate installer on the downloads page. On Android, select the provided arm64 package. On Linux, choose deb or rpm according to your distribution’s package system. For an AppImage, you also need to allow the file to run as a program. A completed download is not an installation; follow your system’s prompts and make sure the app opens successfully.

Desktop and Android installers are not code-signed, so your system may block them on first launch. Only allow files downloaded from this site to run if your device’s policies permit it. If your device is managed by an organization, check with its administrator first. On macOS, if you see “cannot verify the developer,” look for “Open Anyway” under Privacy & Security in System Settings. If macOS reports that the app is damaged, first confirm it is in Applications, then use the command below to clear its quarantine attribute. This command cannot repair an incomplete download.

xattr -cr /Applications/Shadowrocket.app

If Windows SmartScreen blocks the app, select “More info,” verify the file source, then choose “Run anyway.” If that option is unavailable, check your system policy rather than changing organization restrictions. On Android, enable “Allow from this source” for the browser or file manager you use to open the installer; you can turn off this permission after installation. On Linux, grant an AppImage execute permission before running it. Use your system’s package manager to handle dependencies for deb and rpm packages. See the installer permission guide for the full steps.

What to Have Ready After Installation

Before opening the app for the first time, have your existing server address, port, protocol, and authentication details ready, or have your own subscription URL. Do not post sensitive URLs in public comments or screenshots. If reinstalling on an iPhone or iPad, first check Purchased under the Apple Account used for the original purchase. On desktop or Android, you can return to the downloads page for the installer. App access does not include server access: a one-time app purchase is not a service plan. This site does not provide servers or subscriptions; later sections explain how to use details you already have.

Back to section list ↑

02 / PERMISSIONS

First Launch and Permissions: Set Up a Reliable Starting Point

On first launch, make sure the app opens, you can find its main screens, and the system allows it to establish a connection. Do not start by changing every setting. Open Shadowrocket and check whether Home already lists any servers, then locate Config, Data, and Settings. Home is where you select servers and manage connections; Config is for configuration files; Data shows connection and traffic records; Settings contains app preferences. Knowing where to find these sections is more reliable than memorizing button positions.

Check Your Existing Network First

Keep Shadowrocket disconnected and use a browser to open a site that normally works. Confirm that your Wi-Fi or cellular connection is available. Hotel, campus, and public Wi-Fi may require you to sign in on a captive portal first; until you do, server tests and web requests may fail. Complete any sign-in prompt from the system, then return to the app. If ordinary web pages also fail, check your network connection, Airplane Mode, and network permissions instead of changing server passwords or rules.

Also check whether another VPN connection is active or your organization has installed a network configuration. Systems generally cannot run multiple standard VPN tunnels at once as expected, and an automatic connection may take over again after you disconnect. First identify which connection is active. If needed, pause other automatic connections that you control. Do not remove an unfamiliar organization profile; device management policies may be restricting installation or connections. Keep the error message and ask your administrator to check.

Understand VPN Configuration Permission

The first time you connect, the system may ask to add a VPN configuration and request your device passcode or biometric confirmation. This allows the app to create a system network tunnel; it does not import a subscription or verify your server account. Confirm the prompt only after you open Shadowrocket and initiate a connection. After granting permission, return to the app and check whether the connection status changes. If you denied permission, the connection will not complete; try again and approve the system prompt.

VPN configuration permission and server authentication are separate steps. Permission only means the device allows a tunnel to be created. Authentication still depends on the remote address, port, protocol, and credentials. A VPN status indicator does not prove that every destination is reachable. Do not repeatedly remove the system VPN configuration to clear connection errors; doing so removes a useful troubleshooting baseline. Note whether the error occurs before authorization, immediately after connecting, or while the connection stays up but requests fail.

Grant Permissions Only When Needed

When you use Scan QR Code, the system may ask for camera access. If you deny it, you cannot scan, but you can still enter details manually or import them from an existing link. To scan a QR code from a photo, grant only the access requested by the system. When pasting details from the clipboard, check that they really are your own server or subscription information before allowing the paste. Grant permissions for the feature you are using; there is no need to enable every permission in advance. Camera access does not mean server setup is complete.

Keep a Record of Your First Test

Before importing anything, note your current network type, whether you granted VPN permission, and whether Home already has any entries. If this is the first launch after migrating from another device, check which file is selected under Config; do not assume everything you migrated is already active. If interface labels or positions differ from the guide, look for the English terms and consult the interface terminology reference. Do not follow an old screenshot by tapping the same coordinates, especially with the different layouts on iPad.

This stage is complete when the app opens reliably, your basic network works, you can approve permission prompts, and you know how to return to Home and Settings. An empty list is not an app failure if you do not yet have a server to connect to. Continue to the next section to add your existing details. If the app quits immediately after authorization, you cannot approve a system restriction, or device management blocks connections, resolve the permission issue first. Checking permissions, servers, and rules separately will save you from starting every troubleshooting session with a reinstall.

Back to section list ↑

03 / IMPORT

Servers and Subscriptions: Identify Your Details Before Importing

First determine whether you have individual server details, a single-server share link, or a subscription URL. A server entry requires protocol parameters; a share link usually starts with a protocol prefix; a subscription URL typically retrieves a set of server details over the network. These are not interchangeable import methods just because they can all be copied as text. If the information came with parameter instructions, check its type and supported protocol first. Do not use a documentation page, account management page, or configuration download URL as a server address.

Add Server: Enter Server Details

In Home, open Add Server and choose the protocol that matches your existing details. Enter the server address and port. The address field is usually a domain name or IP address; do not include a path, query parameters, or page title from a browser URL. Use the port provided rather than guessing from the protocol name. A remark is just a local label and cannot replace the server address. Save the entry, return to Home, and check that it appears. Open it again to verify the protocol, especially if you changed protocols while entering details and may have kept mismatched fields.

ProtocolCheck These DetailsCommon Mix-Up
ShadowsocksAddress, port, Password, MethodThe Method does not match the server configuration.
VMess / VLESSAddress, port, UUID, transport settingsEntering only the UUID and missing transport or TLS settings.
TrojanAddress, port, Password, TLS, SNIConfusing the connection address with the certificate name.
HTTP / SOCKS5Address, port, authentication requirementsUsing website login details as proxy credentials.

Fill in protocol fields to match your existing server configuration. UUID, Password, and Method are not interchangeable authentication methods; TLS, SNI, Host, and Path each serve a different purpose. For example, with Trojan, the connection address locates the server, while SNI identifies a name during the TLS handshake. They may be the same or differ according to the server configuration. Do not disable certificate verification to hide an incorrect name. See Trojan parameter guide for more details.

Share Links and QR Codes

Import an existing single-server share link using the import option provided by the app. Use Scan QR Code for a QR code. Before scanning, make sure it comes from your own server details. After scanning, check the resulting protocol, address, and port. A QR code carries information; it does not verify that a server works. If scanning opens a regular web page, the QR code may not contain a server entry. Check the source instead of entering the page’s domain in Add Server.

When copying, make sure you include the entire link and do not copy any accompanying instructions. Automatic line breaks in chat apps, full-width punctuation, and quotation marks around a link can all cause parsing to fail. After import, details may be hidden in the entry, so the name alone does not confirm that everything is correct. For an explanation of link prefixes, see Share links vs. subscription links. Editing an encoded link by hand can break its structure; it is safer to get the complete original text again.

Subscribe: Add and Update an Existing Subscription

To add your own subscription, open the add option, choose Subscribe, enter the complete URL, and give it a recognizable name. Save it and run an update, then check whether server entries appear under the subscription. Updating a subscription makes a network request, so it can be affected by your connection, the URL’s validity, or the response from the remote service. If the list is empty, check for an update error and make sure the URL was not truncated. Do not create several copies of the same subscription; it will be harder to tell which one is still updating.

Importing a subscription is not the same as importing rules. A subscription usually refreshes server details, while the file under Config controls behavior such as rule-based routing. After an update, the previously selected server may have been renamed or removed, so check the selected item in Home again. Subscription URLs often contain credentials; when reporting an issue, describe the error without sharing the full URL. This stage is complete when you have at least one server entry with verifiable details, or an existing subscription that updates successfully, and you know which entry is selected.

Back to section list ↑

04 / GLOBAL ROUTING

Global Routing: Config, Proxy, and Direct Modes

Global Routing determines how requests are handled; it does not fix server settings. Config, Proxy, and Direct are three routing modes. Use Config for everyday rule-based routing. Use Proxy to check temporarily whether the selected server can handle a request. Use Direct as a comparison to isolate the proxy from the test. After changing modes, make a new request and check its record. Existing long-lived connections from before the change cannot confirm whether the new setting is working.

ModeHow It WorksWhat to Check
ConfigThe rules and policies in the current configuration file.Whether the destination matched the expected rule.
ProxyHandle applicable requests through the proxy.Basic connectivity between the selected server and the destination.
DirectConnect directly over the current local network.A comparison without the selected proxy.

How Config Relates to Configuration Files

Before selecting Config, open the Config screen and confirm which file is currently in use. Downloading a file does not make it the active configuration, and unsaved edits will not take effect. A configuration may include DNS settings, rules, and policy references, so the filename alone is not enough to verify it. The snippet below shows the basic structure. Its example domain is only for explaining the syntax, not a service you need to visit. Do not replace it with a complete everyday configuration that you have not checked.

[General]
bypass-system = true
dns-server = system

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

Rules are checked in order, and the first matching applicable rule determines the result. Put specific exceptions before broader rules and place FINAL at the end as a fallback. An overly broad rule near the top may prevent more specific rules below it from being used. GEOIP matching depends on the destination IP and the relevant database; it does not identify a website’s language or a company’s country of registration. Assuming every Chinese-language page should use the same policy is a common misunderstanding of how rules work.

Rule Keywords and Policies Are Different

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix, and DOMAIN-KEYWORD matches a keyword in a domain. IP-CIDR and IP-CIDR6 match their respective address ranges. These describe what to match; PROXY, DIRECT, and REJECT at the end describe what to do with a match. Policy keywords do not belong in the domain field, and a protocol name cannot replace a policy name. When editing, keep the English commas and check that no explanatory text or extra spaces have slipped into key fields.

PROXY sends applicable requests through the proxy and still depends on a working server; DIRECT uses your local network and does not guarantee that the destination is reachable; REJECT blocks matching requests, which may be why some requests fail as expected. If the configuration references a custom policy group, check its members and selected option too. A rule match does not mean the entire connection succeeded; DNS, the connection, or the remote response may still fail afterward.

Use the Three Modes to Isolate the Problem

If the same destination works in Proxy but fails in Config, compare the matched rule, policy group, and DNS behavior in the configuration first; do not immediately re-enter your server details. If Direct works but Proxy fails, check server connectivity and the remote route. If all three modes fail, revisit your basic network, the destination service, and DNS. For a useful comparison, keep the device, network, and destination the same, and test close together in time. Otherwise, a network change can make the results incomparable.

Back to section list ↑

05 / VERIFY

Connection and Verification: Separate the Tunnel, Server, and Request

Connection checks involve at least three layers: whether the system allows the tunnel to start, whether the selected server can communicate, and whether the destination request completes as expected. An enabled switch in Home is only a clue about the first layer; it does not prove the other two are working. First confirm the selected server, then check Global Routing, and finally make a specific request. Change one variable at a time and record the before-and-after results; this makes it easier to find the cause than changing the server, DNS, and rules all at once.

Final Checks Before Connecting

In Home, check that the selected server is the entry you just imported, especially after a subscription update, a name change, or when you have several groups. Do not rely on the top entry; check which one is actually selected. Then check Global Routing. If you are testing rules, select Config and confirm the current file. Switch to Proxy only when you need to temporarily isolate the effect of rules. Turn on the connection switch, approve the VPN permission prompt, and wait for the status to settle before opening a browser. Do not keep tapping the switch while the status is changing.

If the connection drops as soon as you turn it on, first check for an app configuration error or a system permission error. Browser testing is not very useful yet because requests may not have entered the expected tunnel. Check whether you denied permission, whether the configuration file contains something the app cannot parse, and whether another connection is taking over automatically. If the switch stays on but requests time out, focus on the server, DNS, and rules. Record these as different symptoms instead of calling both “connection failed” and reinstalling immediately.

What Connectivity Test Can Tell You

Connectivity Test shows connectivity using the test method provided by the app. Different methods may check different destinations and connection stages. Check the selected method first, and do not treat one displayed time as the actual speed for every website. A successful test means the test path received a response; it does not guarantee that a destination website’s certificate, login, content, or requests to other domains will work. If the test fails, compare it with actual website requests rather than concluding from one result that the entire subscription is invalid.

Reopen a familiar, ordinary website and check whether its main document and required resources load. If text appears but images fail, the resources may use different domains or existing connections. If you can sign in to an app but one feature fails, that feature may use a separate destination. Record the specific failed request rather than just the product name. Browsers may reuse connections and cached content. After changing a setting, reopen the page and, if needed, close it before trying again to reduce interference from old connections.

Troubleshoot by Symptom

If domain requests fail while your basic network works, check the current DNS settings and errors in the connection records. DNS resolves names to addresses; a resolution failure is different from a timeout after connecting to an address. Do not enter an unfamiliar DNS address or assume that changing the resolver will improve access. For TLS or certificate errors, check the device’s date and time, the server name, SNI, and the requirements in your server details. Disabling verification can hide the problem and should not be a routine fix.

If the issue occurs only on one Wi-Fi network and cellular works, check whether the Wi-Fi requires sign-in, restricts the relevant protocol, or has different local DNS or network policies. After switching networks, reconnect and test the same destination. Do not treat results from different network conditions as the only evidence that a server is unreliable. For UDP, real-time audio, and video, confirm that the server and protocol support the required transport. A working web page does not prove those features will work too.

Save a Baseline After Verification

A useful connection test leaves a clear baseline: the network used, the server selected by its local remark, the routing mode, the destination tested, and the result. Do not record passwords or share full addresses. Once everything works, enable automation gradually so you can return to a known-good state if a new issue appears. If you still cannot isolate the problem, use the Troubleshooting guide and gather the error text and tests you have already tried before asking for help. A screenshot showing only an enabled switch is not enough.

Back to section list ↑

06 / DATA

Data and Connection Records: Trace Symptoms to Individual Requests

Data and related connection records help narrow “a page failed” down to “which destination, which policy, and which stage failed.” The available statistics and fields vary by screen; use what the current app actually shows. Read the field names before interpreting the numbers. Device-wide traffic, traffic through the tunnel, requests recorded by the app, and server-side usage are not necessarily the same thing. Records help locate problems but do not replace checks of the server or the destination service.

Start with One Repeatable Test

Before testing, note the current time and destination, then perform one specific action, such as reopening a page. Return to Data or the connection records and look for entries around that time. Background sync, push notifications, and other apps can also make connections, so the newest entry may not belong to the page you just opened. Filter by destination domain, time, and what you did. A single failed request does not prove the main page failed, and a single successful one does not prove the whole page is working again.

A page may use separate domains for its main content, images, scripts, login API, and analytics, each matching different rules. Look for the destination related to the main function first, then check supporting resources. If you are unsure, compare new records before and after the page action instead of changing every domain you see. Requests may reuse an existing connection, so they do not always create a new entry. Make a fresh test and, if needed, reconnect; the absence of a new entry does not mean the app is not handling the traffic.

Match Policy Results to Rule Order

If records show a policy or rule, first check whether the request used PROXY, DIRECT, REJECT, or a custom policy group. Then find the corresponding entry in the current configuration. If you expected PROXY but see DIRECT, check whether an earlier, broader domain or IP rule matched first. If you see REJECT, confirm whether a reject rule in the configuration was applied. Save the original text before editing. Reconnect and generate a new request after the change; historical records do not update when you edit rules.

[Rule]
DOMAIN,account.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-SUFFIX,ad.example.net,REJECT
FINAL,PROXY

The order above shows how exceptions relate to broader matches: the exact account.example.com match comes before the suffix rule for example.com, so other matching subdomains can fall through to the suffix rule. This example only illustrates rule order; it does not mean these domains belong in your everyday configuration. If a record shows only a destination IP, you cannot assume a domain rule matched based on a guessed name. Consider DNS, how the request was made, and the information actually available; do not treat unobserved details as confirmed facts.

What Traffic Numbers Can and Cannot Tell You

Upload and download statistics can show whether data was exchanged, but data transfer does not mean a task completed. Failed TLS handshakes, repeated retries, or loading only an error page can still use traffic. Conversely, cached content may make a page appear normal with little new traffic. Before interpreting the numbers, check whether they show the current connection, a cumulative total, or a summary for a particular screen. Network changes and reconnects can also affect the measurement window. Do not use a short interval to estimate long-term usage or to judge whether server-side billing is accurate.

To investigate unusually high usage, first stop unrelated large downloads and background tasks, then observe the change caused by one specific action. System, app, and remote statistics may use different time periods and measurement methods. Protocol overhead, retransmissions, and connection maintenance also create differences. Align the observation period before comparing trends; numbers from different screens do not need to match exactly. If traffic continues while the device is idle, check background apps and automatic updates before assuming a rule or server is at fault.

Prepare Diagnostic Details You Can Share

Before submitting troubleshooting details, redact subscription URLs, server addresses, authentication fields, and domains that could reveal personal activity. Keep only the error type, policy, timing, and steps needed to reproduce the issue. If you need to clear records, first save the essential details in a redacted form, then use the cleanup option in the current interface. There is no need to keep detailed debug records indefinitely after finding the cause. For routine checks, it is enough to know whether requests are being routed as expected; keep sensitive records only as long as necessary.

Back to section list ↑

07 / SETTINGS

Common Settings: Automate Only After the Connection Works

Adjust Settings one at a time to meet your needs; you do not need to enable every switch. Keep a verified baseline, then configure On Demand, test methods, subscription updates, and record-related options as needed. Some network behavior may also be controlled by the current Config file, so check it if a setting does not behave as expected. Similar labels in different parts of the app may have different scopes. Confirm whether you are changing a global setting or a parameter for a specific server.

On Demand: Choose When to Connect Automatically

On Demand starts connections when specified conditions are met; it cannot make incorrect server details work. Before enabling it, connect and verify manually. Then decide which network conditions should trigger a connection and which should leave it off. If the current screen offers network-based conditions, read each one carefully and avoid overlapping conditions that make the result hard to understand. After setting it up, test both a condition that should trigger and one that should not. One successful automatic connection does not prove every condition is correct.

If the connection comes back after you turn it off manually, check On Demand and other automatic connection settings in the system instead of repeatedly tapping the switch. Automatic connections can make it harder to sign in to public Wi-Fi. Temporarily disable the relevant automation and complete the network sign-in first, then restore your settings. Before disconnecting for a comparison test, make sure automation will not reconnect during the test; otherwise, Direct and disconnected results can be confused.

Connectivity Test: Keep Test Conditions Consistent

Before changing the test method, find out what it checks. A response from one method does not mean every protocol or service will work, and times from different methods are not directly comparable. To track changes on the same server, keep the method, network, and destination consistent. Note any test-setting changes in your troubleshooting record. Do not recreate a subscription just because one test took longer, and do not change DNS, server, and routing mode all at once to chase a lower number.

Tests generate requests and are affected by the device’s current state and the remote response. Results may be unusual while the device is downloading, the network has just changed, or public Wi-Fi sign-in is incomplete. Wait for the network to settle, run a few tests, and check actual websites and app features too. If tests keep failing but your destinations work, check whether the test target itself is reachable. If tests pass but an app feature fails, find the specific domain used by that feature in the connection records instead of repeatedly tapping the same test button.

DNS: Check Where the Configuration Comes From

Read DNS settings together with the current configuration. If the configuration file already includes entries such as dns-server, understand what they do before changing related settings. The example dns-server = system uses the system resolver as the source; it does not specify a particular public resolver. DNS problems may appear as a name that cannot be resolved or as a different address that affects the connection afterward. Distinguish the resolution stage from the connection stage instead of judging only whether the final page opens.

Do not pile on DNS changes from several places when you do not know what they do. Your router, system network settings, organization policies, and app configuration may all affect name resolution. After changing one, test again and check the result. For internal hostnames, consider whether the name can only resolve on the relevant local network. Using an external resolver for an internal destination may make the name unresolvable. Blaming a public DNS issue on rules can also lead to more and more irrelevant routing entries. Keep the original settings so you can restore them quickly.

Updates, Records, and Sensitive Features

If the current screen offers automatic subscription updates, set them according to how often you use the app. There is no need to refresh every time you switch apps. If an automatic update fails, check the reason; enabling the option does not guarantee that remote details stay valid. Enable log or record options only as needed for troubleshooting, then restore an appropriate level afterward. HTTPS decryption, certificates, and scripts are not required for a basic connection. Research them separately after understanding their purpose, privacy implications, and configuration source. Do not copy and run a complete set of instructions from an unfamiliar source.

After changing a setting, test only the behavior it directly affects and record the original value. If something goes wrong, undo the latest change and see whether you return to your baseline instead of adding more workarounds. Treat Settings, the current Config, the selected server, and Global Routing as one combined state. Backing up only some of them may not reproduce the same behavior on another device. If you are unsure where to find an option, return to the setup guide to review the main workflow, then work through this section one setting at a time.

Back to section list ↑

08 / MAINTENANCE

Routine Maintenance: Updates, Backups, Migration, and Rollback

The goal of maintenance is to preserve a working setup and understand what changed. App updates, subscription updates, and configuration file updates are separate: an app update changes the program, a subscription update refreshes server details, and a configuration update changes network behavior such as rules. They do not necessarily happen together, and you should not apply all of them without keeping a record. When something breaks, identifying the layer you changed most recently is often more useful than reinstalling and can preserve valuable records.

Handle Each Type of Update Separately

Update the iPhone and iPad app through the App Store. For Mac, Windows, Android, and Linux, visit the downloads page to get the appropriate installer again. Before updating, save your own configuration and other essential details, especially before freeing device space, interrupting an installation, or migrating to another device. Reinstalling on desktop or Android may trigger system permission prompts; check the source as described on the downloads page. An app update does not refresh a subscription, and an invalid server entry in a subscription does not mean the app needs to be reinstalled.

After updating a subscription, check for changes in the number and names of servers and confirm which entry is selected. More entries do not mean a better update. If a server was removed, you may need to select another one; an entry that keeps the same name may still have different underlying details. If an update fails, first check your basic network and whether the subscription URL is valid. Keep the error details, and do not delete the existing subscription before confirming that you have saved its URL. For servers you manage yourself, use their current configuration as the source of truth.

Before updating a configuration file, save a copy of the current working version and note any exception rules you added. Do not assume a newly downloaded remote configuration will preserve local edits or become selected automatically. Return to Config to check which file is active, then verify the behavior of DIRECT, PROXY, and reject rules against consistent destinations. If only one feature fails after an update, compare the relevant rules and DNS entries and roll back only the affected parts. Do not immediately overwrite every device with the entire old configuration.

Separate Configuration from Credentials When Backing Up

A backup should include at least the current configuration file, essential server details, the subscription source, and notes about settings you changed. What an export contains depends on the app’s current export options; do not assume one file includes every password, subscription, and preference. After backing up, make sure you can open the file and identify its purpose from its name, then store it somewhere you control securely. Configuration files may contain sensitive details. A text-file extension does not make them safe to publish or forward as a regular attachment.

Subscription URLs, UUIDs, Passwords, and some server links can grant access; hiding only the remark is not enough when sharing them. If credentials have been exposed, revoke or replace them in your own service management account and update the entries on your devices. Deleting a chat or changing a local remark does not invalidate old credentials. Before saving a screenshot of an issue, check the title, detail fields, and full URL for sensitive information. You can describe the error and steps without including details that would allow someone to recreate the connection.

Restore in Order After Switching Devices or Reinstalling

On a new device, install the app and grant the basic permissions first. Restore your existing details next, then configure automation last. On iPhone and iPad, check Purchased under the Apple Account used for the original purchase. The iPhone and iPad app costs $2.99 as a one-time App Store purchase; the Mac, Windows, Android, and Linux versions are free. Purchase history and local configuration are separate, so restoring the app does not necessarily restore servers and rules. After restoring, check the selected server, Config file, and Global Routing. Complete a connection test before enabling On Demand.

Do not test migration with only one website. Choose several types of destinations you use regularly, and check that local resources intended to connect directly, requests intended for the proxy, and destinations intentionally blocked by your configuration behave as expected. Networks differ between devices, as can local addresses and DNS conditions. A working old device does not mean you can skip network checks on the new one. Keep the working configuration and backup on your old device until the new device is stable; do not erase the original details at the start of migration.

Build a Maintenance Routine You Can Roll Back

Make one type of change at a time, save the previous state, and verify afterward using the steps in section five. If needed, check the records in section six. When something goes wrong, undo the latest change first, then check for changes to the basic network or remote service. When describing the issue to someone else, include the device type, network, routing mode, symptom, and tests already performed; remove all sensitive details. Use Troubleshooting for common symptoms and the blog for individual concepts. Return to the relevant section of this manual to review the full workflow.

Back to section list ↑
Shadowrocket Official Downloads