Platform note: Ubuntu, Windows, and macOS clients usually label these sections “Configuration,” “Subscription,” or “Proxy,” or use terms such as Profiles and Proxies. Android and iOS clients typically route traffic through a system VPN approval prompt. The button labels below indicate where to look; names vary by client. Keep the steps in order when switching platforms—you don’t need to find an identical interface.

Before you begin, have a compatible client and either a subscription URL from a trusted source or a local YAML configuration. The client provides the interface and system integration; a core such as mihomo reads the configuration and handles connections. Installing the client alone usually doesn’t provide a usable proxy route. This guide doesn’t provide subscriptions or require you to edit advanced settings. If your configuration is ready and your network is working, you can complete the basic setup in about 10 minutes, then adjust settings as needed.

This guide starts with Rule mode and the desktop system proxy—a straightforward setup that’s easy to inspect and undo. Server deployment, protocol differences, and core compatibility aren’t required for a first connection; see the Protocol and Core Reference when needed. If you haven’t installed a client yet, choose an installation method from the Linux downloads page or the page for your platform, then return here to continue.

01 Import Subscription

After launching the client, open its Configuration or Subscription page—not System Proxy. Find an option such as “New,” “Add,” or “Import from URL,” then paste the complete subscription URL into the address field. Give it a recognizable name if you like. Check for extra spaces or line breaks before downloading or importing. Subscription URLs may contain access credentials, so don’t include the full URL in public screenshots, support posts, or online conversion tools.

After the download, the configuration list should show a new card with a name, update time, or status. You’ll still need to click “Use,” “Activate,” or the card’s selection button to make it the active configuration; appearing in the list doesn’t mean the core has loaded it. The client should no longer report a configuration parse error, and the Proxy page should show the groups and routes defined in the configuration.

For a local file, choose “Import from file,” locate config.yaml or another YAML file, and open it. The file extension is only a clue; its contents must still match the configuration format supported by the client’s core. Don’t save a web page as YAML or treat a text file containing only node links as a complete Clash configuration. Select the imported configuration to enable it, then check that its proxy groups appear.

Some providers offer subscriptions in multiple formats. Choose the option labeled for Clash, Clash Meta, or mihomo compatibility. A link opening in your browser only means the server returned content—it doesn’t confirm that the content is a valid configuration. If the client reports a syntax or format error, check the selected format first, then make sure you didn’t copy a login-page URL. Don’t delete unfamiliar protocol fields just to clear an error.

If a download fails, first determine whether the client couldn’t retrieve the file or couldn’t load it. For a retrieval failure, check that the URL is complete, your subscription is active, and your network can reach the address. For a load failure, check the specific field mentioned in the client log. Some clients let you choose whether subscription updates use a direct or proxied connection. Before a proxy connection is working, avoid making updates depend on an unavailable proxy route.

Once the subscription imports successfully, don’t copy the entire configuration into a manual editor and start making repeated changes. Remote updates may overwrite direct edits, and client-specific override, merge, and scripting features work differently. Keep the original configuration for now; learn how to make persistent changes later if you need custom rules. Once the active configuration is enabled and its proxy groups are visible, continue to the next step.

02 Choose Rule Mode

Return to the home screen or Settings and find “Mode,” “Operation mode,” or “Mode.” Select Rule. Requests that reach the core will then be checked against the rules list from top to bottom, and the first matching rule determines the route. This doesn’t automatically capture traffic from every app; system proxy or TUN setup comes next. Set the routing behavior first, then configure how traffic reaches the core—it’ll be easier to troubleshoot later.

The other common choices are Global and Direct. Global mode sends requests reaching the core through the global policy; Direct mode uses a direct route. Global doesn’t mean every app on your computer is using the proxy, and Direct doesn’t mean the client is off. Unless you have a specific testing need, leave Rule mode selected for your initial setup. Changing the mode and traffic routing at the same time makes it harder to identify what caused a problem.

Next, open the Proxy or Proxy Groups page. You may see several groups with names chosen by the configuration author, such as a main group for manual selection and other groups for specific purposes. Expand the main selection group referenced by your rules and choose an authorized, available route. The selection may be marked with a check, a border, or a change in the displayed option. If the group points to another group, expand that one too to find the final route.

Don’t infer a policy from its name alone. DIRECT means a direct connection, and REJECT blocks the connection; neither is a regular remote node. If the main proxy group is set to DIRECT, relevant requests may go out over your local network even when the system proxy is enabled. An automatic selection group chooses a route based on the configuration’s health-check URL and policy, and may not let you pin a specific node. To select one manually, use a selection group provided by the configuration.

The client’s “Connection Test” or “Availability Test” can be useful, but a successful test only means the configured test request received a response. It doesn’t guarantee that a particular website, account login, or every app will work. A failed test may also be caused by the test URL itself. Choose a route that responds, then verify it with real traffic and connection logs. Don’t rely on the test result alone.

If the expected group isn’t listed, go back and check which configuration is active rather than immediately adding an empty group. Group names vary; what matters is that the names referenced by your rules match actual policies. For more on custom rules, automatic selection, and protocol types, see the Protocol Reference. For common interface and selection issues, see Frequently Asked Questions. Once the mode and route are set, you’re ready to route app traffic.

03 Start the Core and System Proxy

First, confirm on the home screen that the core is running. Some clients start it automatically; others require you to click Start or Connect. If the client reports a configuration error, a stopped service, or a port conflict, fix that before enabling the system proxy. The system proxy points app requests to a local listening address. If the core isn’t listening, enabling it first sends browser and other app traffic to a port with no service.

Desktop clients for Windows and macOS usually offer a System Proxy switch that updates the corresponding OS settings. Ubuntu GUI clients may offer the same switch, but the result depends on your desktop environment and installation method. After enabling it, leave the client running and check that the setting stays on. If another proxy client or VPN is already active, pause one of them first to prevent both from repeatedly overwriting system settings.

In Ubuntu GNOME, open system Settings and find Network Proxy under Network to check the current values; the location varies slightly by version. If the client hasn’t set them automatically, switch to Manual and enter the local address 127.0.0.1, with the HTTP or mixed port shown by the client. If your configuration uses mixed-port: 7890, enter the same address and port for both the HTTP and HTTPS proxy fields.

The HTTPS proxy field is the proxy used when your browser visits HTTPS websites; it doesn’t mean the local proxy endpoint itself must use HTTPS. Don’t change ports just because the field names differ. A mixed port accepts both HTTP and SOCKS5 requests. If the client uses separate ports, enter each one as labeled. 7890 is only a common example; if your configuration uses a different port, update the value in your system or app settings too.

A desktop system proxy isn’t a mandatory route for every program. Browsers usually follow system settings, but some terminal tools, games, and standalone apps use their own network configuration. Get one browser working first, then configure other apps as needed. To proxy just one app, enter the local address and corresponding port in that app. For apps on the same machine, you don’t need to enable allow-lan just to connect, and you shouldn’t expose the control interface without a clear reason.

On Android and iOS, you’ll usually need to tap Connect in the client and approve the system prompt to create a VPN connection. This is the system interface the client uses to route traffic; it doesn’t mean you need to install a separate VPN app. If another app is already using that interface, decide which one to keep. Per-app routing support and menu locations depend on the client and OS version, so the desktop system proxy steps don’t apply directly.

Consider TUN only if an app doesn’t follow the system proxy or you explicitly need more complete traffic routing. Desktop clients may require a service, administrator privileges, or a virtual network adapter. Don’t enable several unfamiliar options at once. Note your working settings, then test TUN on its own. If networking breaks, turn TUN off and return to the verified setup. For related DNS and permission issues, see Troubleshooting.

04 Verify Requests and Routes

A Connect button showing “On” doesn’t prove that an app is using the expected route. Leave the client running, open its Connections page, then open a new browser tab and visit a known-working website you can access. Check for a new connection to that domain and confirm the browser gets a response. Use a fresh request where possible; existing long-lived connections may still be using the previous route.

Open the connection details and check the destination domain, matched rule, proxy group, or proxy chain. Fields vary between clients, but you should be able to tell whether traffic went direct, through a group, or was rejected by a rule. Under Rule mode, some sites connecting directly is expected. To verify a remote route, test a request that your rules actually send through a proxy group—not every connection needs to show the same node.

If needed, use a trusted exit-IP lookup service as an additional check, but compare its result with the connection log. The lookup site is also subject to your routing rules, so seeing your local IP doesn’t necessarily mean the proxy isn’t working. Browser cache, existing connections, and a site’s region display based on account or location permissions also can’t confirm the network path. The key question is: did this request from this app reach the core and use the expected route?

Desktop users comfortable with a terminal can run the command below to explicitly use an HTTP proxy when visiting a standard test site. Replace the port with the client’s actual mixed or HTTP port. This test distinguishes “the core’s proxy endpoint is working” from “the app reads system settings”; it doesn’t prove that every command-line tool is automatically using the proxy.

curl --proxy http://127.0.0.1:7890 --head https://example.com

If the explicit proxy command works but the browser has no corresponding connection log, check whether it uses the system proxy, whether an extension overrides it, and whether the system port is correct. If the connection appears but the request fails, check the matched policy and relevant logs. Repeatedly toggling the system proxy usually won’t help at this point. Don’t disable certificate verification to bypass HTTPS warnings; check the system clock, destination site, and route instead.

If all requests fail, check these items in order: is the correct configuration enabled, is the core running, is the local port listening, is app traffic reaching the core, and finally, is the selected route available? Change one thing at a time and make a new request, rather than changing the configuration, DNS, TUN, and mode all at once. For port conflicts, see Port 7890 in Use: Adjusting mixed-port. Don’t terminate system processes unless you know what they do.

Once verification succeeds, keep the confirmed mode and proxy group selection, then configure subscription updates and launch at startup if needed. A subscription update may change the options in a group, so if something stops working, first check whether the current selection is still available. Running Ubuntu as a service and choosing protocols are advanced topics; see the Protocol and Core Reference. There’s no need to configure an entire service before making your first connection.

Success criteria: the configuration loads, the core is running, new app requests appear in the connection log, and the matched rule and route behave as expected. Before closing the client, turn off the system proxy or restore your previous proxy settings. If you enabled TUN, make sure the client has released the network interface cleanly.