Before you begin, install a client and have a subscription URL or YAML config file from your provider ready. The client reads the config and routes connections; installing it does not provide a working exit by itself. Allow about ten minutes for the first setup. If you don’t have a subscription, account access, or a working network connection, resolve that first instead of repeatedly changing client settings.
Close any other proxy or VPN tools that are currently routing traffic to avoid conflicts between proxy addresses, virtual adapters, and routes. Keep a copy of your original config and note the system’s current proxy settings. Change one type of setting at a time and confirm the result before moving on, so you know exactly where to roll back if something goes wrong.
01 · Import a Subscription and Enable the Config
Open the client and go to the Config, Subscription, or Profiles page. Choose “New,” “Add,” or “Import from URL.” If prompted to select a type, choose a remote subscription or remote config—not a single proxy. Give it a recognizable local name, then paste your provider’s full URL into the URL field. The name only affects how it appears on your device; it does not determine the exit.
Check the start and end of the URL before pasting. Text copied from a messaging app may include instructions, line breaks, or trailing punctuation. Keep only the URL itself, but don’t remove or change any parameters after the question mark. Subscription URLs may contain credentials, so don’t post the full link in public forums or share unredacted screenshots. When asking for help, include the error text but hide sensitive parts of the URL.
Click Save, Import, or Download and wait for the client to finish. A successful import usually adds an entry to the config list with a name, update time, or download status. Then click “Use” or “Activate,” or select the entry, to make it the active config. Some clients don’t switch automatically after saving. Seeing the entry in the list does not mean the running core has loaded it.
Check That Proxy Groups Are Available
Open the Proxies page and check for selectable proxy groups and their members. Group names are set by the config provider and may not include “PROXY.” If you see only built-in options such as DIRECT or REJECT, return to the config page to confirm the active selection, then review the import status. Remote proxy providers may need to download separately, so a successful main config import does not guarantee that all remote resources have loaded.
For a local file, choose “Import File” on the same page, locate the actual .yaml or .yml file, and enable it. Simply changing a file’s extension to YAML won’t make it a valid config—a web page, login prompt, or error page won’t work. The file must contain actual proxy details or a proxy-providers definition that can load proxies. A fragment containing only ports and rules is usually not enough to establish a proxy connection.
If the import fails, start by checking the error type. A connection timeout means the request did not complete; an authentication error means you need to check your subscription access; a parse error means the provider’s config format may not be compatible with your core. Don’t paste a private subscription into an unfamiliar online converter. For URL formats and conversion limitations, see Subscriptions and Config Files in the Glossary. For help with specific errors, visit the Help Center.
02 · Choose Rule Mode and an Exit
Keep the config you just enabled active. Open the Proxies or Mode page and find the Rule / Global / Direct options. For a first-time setup, choose Rule, corresponding to the core setting mode: rule. The config’s rules determine whether each connection goes direct, to a policy group, or is rejected. Mode controls routing decisions; it does not send traffic from other apps into the client.
Next, find the policy group that selects an exit in your config. It may be labeled “Proxy Selection,” “Node Selection,” or something else. Open the group and choose an available proxy. If the selected member is another policy group, check which exit that group currently uses. For your first test, choose a specific proxy manually so you can tie the result to that exit. Don’t change several traffic-routing groups at once.
Some configs select an automatic test group by default. You can leave it selected, but note that its test result only measures the client’s connection to a specific test address; it doesn’t guarantee that a particular website will be accessible. If the client has a connectivity test, run it and check for a timeout or clear error. You’ll still need to verify access in the next steps—a test result alone does not prove that all apps are being routed through the client.
Mode vs. Traffic Capture
| Mode | How Connections Are Handled | Recommended for First-Time Setup |
|---|---|---|
| Rule | Routes connections according to the rules in the config. | A good starting point for everyday use and this guide. |
| Global | Routes all connections that reach the core through the global policy. | Use briefly only to compare the effect of rules. |
| Direct | Connects directly to the destination for connections that reach the core. | Useful for specific comparisons; it does not disable traffic capture. |
Global mode does not send apps into the core if they bypass the client in the first place. If your browser doesn’t use the system proxy, switching to Global alone usually won’t solve its traffic-routing issue. Likewise, Direct mode does not remove the system proxy setting or virtual adapter. To stop routing traffic entirely, turn off the relevant toggle instead of just changing modes.
If a destination takes an unexpected route in Rule mode, note what happened instead of deleting rules right away. The Connections page later in this guide shows match details, which can help you tell whether the issue is rule selection or traffic capture. For now, confirm that Rule mode is selected and the exit group has a clear choice, then continue to the connection step. For details on rule order, nested policy groups, and how MATCH works, see the configuration section of the full documentation.
03 · Enable the System Proxy or VPN Connection
Return to the client’s home or overview page and make sure the core started after the config loaded. If “Start Core” and “System Proxy” have separate toggles, start the core first, then enable the system proxy. If there’s only one Connect button, follow the client’s prompts and check the logs for startup errors. Don’t enable multiple traffic-routing tools at once or disable the system firewall to troubleshoot.
Desktop: Verify the System Proxy First
Windows, macOS, and desktop Linux clients typically have a System Proxy toggle. When enabled, apps that follow the operating system’s proxy settings send requests to the local listening port. Check the actual address and port in the client settings, for example 127.0.0.1:7890. That’s a common setup, but use the value shown in your client. Don’t change the port just to match the example.
If the client reports that the port is already in use, quit other proxy clients and restart the core. If the startup log shows address already in use, the local proxy service may not be available even if the System Proxy toggle appears to be on. Once the listener starts successfully, open a new browser window and test again. Some apps keep existing connections open; if needed, quit and relaunch the app instead of just refreshing the old page.
Whether Linux desktop proxy settings are honored depends on the desktop environment and the app. Terminal programs may not use the system proxy either. For your first test, use a browser that supports proxy settings rather than judging by every command-line tool. Server, router, and systemd deployments are outside this desktop setup guide; see the Linux installation and deployment section for those options.
Mobile: Approve the System VPN Request
On Android and iOS, tapping the client’s Start or Connect button usually prompts the system to create a VPN connection or add a VPN configuration. Make sure the request comes from the client you just installed and are using, then approve it as prompted. Return to the client and check the connection status. If you cancel the permission request, the client won’t route traffic even if a config is selected. A VPN icon in the status bar only shows that the tunnel is enabled; it doesn’t prove the remote exit is working.
If another VPN is already running, disconnect it before starting this client to avoid competing for the system VPN connection. Keep the client in the foreground during your first test and verify that a page loads. If it only disconnects when sent to the background, check battery management and background permissions. Don’t mistake background restrictions for an invalid subscription and repeatedly re-import it.
When to Enable TUN
On desktop, start with the system proxy and get a repeatable test result. Consider TUN only if you need to route apps that ignore system proxy settings or other specific traffic. TUN typically involves a virtual network interface, routing, and DNS, and may require administrator permissions or client service support. Follow the client’s instructions for installing any required service; a toggle changing color does not confirm that setup is complete.
When enabling TUN for the first time, note the original system proxy setting and follow the client’s guidance on using the two together. Don’t change TUN, DNS, routes, and mode all at once. If enabling TUN breaks your network connection, turn it off and return to the system proxy setup you already verified. Desktop TUN and mobile VPN permission screens may use similar names, but the underlying implementations differ. For more, see Network Traffic Capture Modes in the Glossary.
04 · Verify Access and Check Connection Records
Check both the app and the client. First, disable traffic capture and make sure your current network can reach a site you normally use. If the network is already having trouble, resolve Wi-Fi, mobile data, or network sign-in issues first. Then restore the proxy connection and open the page you want to test. Use a fresh request rather than relying on cached page content.
As soon as the page loads, return to the client’s Connections page and look for the destination domain. New requests may disappear quickly, so refresh the page if needed and check the logs as well. Verify three things: whether the destination appears, which rule matched, and which policy or exit handled it. In Rule mode, some sites going DIRECT is expected and does not mean the client as a whole is broken.
Narrow Down the Issue by Symptom
If there’s no connection record for the destination, first check whether the app uses the system proxy, whether the core is listening, and whether the mobile VPN is still connected. Don’t change exits first—the request may never have reached the client. If a record appears but takes an unexpected route, check the current mode, matched rule, and policy group selection instead of reinstalling the software.
If the expected policy matched but you get a timeout, connection refusal, or handshake error, check whether the selected exit is available, your subscription is active, and your device’s clock is correct. Change one exit at a time and retry the same destination, keeping track of the results. If only one site has trouble, the site itself may be at fault. One site’s success or failure does not represent every network connection.
Optional: Test by Specifying the Local Proxy
On desktop, you can use the command below to distinguish a working local proxy service from an app’s proxy settings. It explicitly uses a local HTTP proxy, regardless of whether your browser follows system settings. Before running it, replace the port with the client’s actual HTTP or mixed listening port. If only a SOCKS listener is enabled, don’t use this HTTP proxy option.
curl --proxy http://127.0.0.1:7890 --head --max-time 15 https://example.com/In Windows PowerShell, start the command with curl.exe to avoid older environments interpreting the same name as an alias and changing its arguments. An HTTP response header shows that this request received a response through the specified local proxy, but check the client’s connection records to confirm whether it used a remote exit; a rule may route the destination directly. If the local address can’t be reached, check the listening port first rather than changing DNS.
If the command works but the browser doesn’t, check the browser’s proxy extensions, custom proxy settings, and existing connections. If the browser works but other apps don’t, check whether those apps support the system proxy; consider TUN only if needed. An external IP lookup is only a supplementary check: with rule-based routing, different lookup sites may use different exits, so an unchanged IP alone does not prove the proxy is broken.
Save a Working Setup You Can Reproduce
Once the test page loads and the connection records match your expectations, keep the current mode and traffic-capture method. Note the active config name, actual listening port, and selected policy group for easier troubleshooting later. Before quitting, turn off the system proxy or VPN connection, then exit the client. If you manually set a system proxy, make sure it no longer points to a port that has stopped listening.
When your subscription changes, update it from the config page. Once the update finishes, confirm the config is still active and repeat the checks in this section. Don’t add complex rules before basic testing is complete. For update failures, UWP apps that bypass the proxy, or apps that can’t connect, troubleshoot by symptom in the Help Center. If you need to maintain a config over time, continue with the full documentation.