LINUX DESKTOP CLIENTS · MIHOMO CORE
Get started with client installation, subscription management, and routing rules on Linux.
rules
Five desktop settings worth knowing
The GUI handles controls, configuration lists, and desktop integration; the core handles connections. The sections below explain what each setting changes so you can decide what to enable instead of turning everything on at once.
If your browser connects but the terminal or other apps do not follow the same route, first check whether they respect the system proxy. TUN mode uses a virtual network interface to route more connections, making it useful when you need consistent traffic handling across the desktop. It usually requires a service or additional permissions. Before enabling it, make sure the regular system proxy works, then check routing and DNS one at a time. This also makes it easier to revert if something goes wrong. For browser-only use, the system proxy is often enough. Watch for overlapping routes if you also use another VPN or container network.
tun.enable · tun.auto-route · dns.enhanced-mode
Rule mode does not send every connection through the same proxy. Rules are checked in configuration order and can match domains, addresses, or rule sets; a match is then handled by the assigned policy group. You can route local network services directly and group other connections by purpose. Rule providers help manage large lists separately, but your client must support the relevant fields. When adjusting rules, check the connection list to see which rule matched before changing the order. Switching to Global mode can help isolate a problem, but it is not a substitute for routing rules.
rules · rule-providers · proxy-groups
Closing the window, quitting the client, and stopping the background core are three different actions. Clients with system tray support can keep running when the window is hidden, making it easy to check the current mode. Tray icons on Linux depend on the desktop environment and its extensions, so a missing icon does not necessarily mean the core has stopped. After enabling startup, sign in again to confirm the subscription loaded and service permissions still work, then check the system proxy. If you manage services manually, avoid starting two cores at once to prevent port conflicts.
external-controller · mixed-port
A subscription link retrieves configuration, while the client's auto-update setting controls how often it fetches updates. Scheduled updates usually do not run while a laptop is asleep; whether they catch up after waking depends on the client. If you switch networks often, update manually and check the result before choosing an interval. Direct edits to a remote configuration may be overwritten at the next update, so use the client's override feature for local rules, ports, and policy changes. Keep a copy of the original configuration before switching profiles, and note which settings are specific to the client.
proxy-providers · update-interval
Seeing a protocol name in the interface does not guarantee that the installed core can handle it; actual support depends on the bundled core and its configuration fields. mihomo continues the Clash Meta project lineage and develops support for protocols, rules, and TUN. When choosing a client, check not only whether it can import your subscription, but also whether service permissions, logs, and update options are clear. An existing Clash configuration can be a starting point for migration, but newer fields may not work with older clients. Start with a minimal configuration, then add rule sets gradually to make troubleshooting easier.
proxies · log-level · external-controller
Core fields go in the active configuration; tray behavior, startup, and subscription update intervals are usually client settings. Use the mapping below to find the right place—it is not a recommendation to enable everything.
| What you want to change | Where to look | Check before changing |
|---|---|---|
| Route traffic through a virtual interface | tun.enable | Service permissions, routes, and DNS settings |
| Route traffic by rule set | rule-providers、rules | Rule set source, format, and reference name |
| Proxy listening port | mixed-port | Whether another program is using the port |
| Local control interface | external-controller | Listening address and access permissions |
| Scheduled subscription refresh | Subscription update settings in the client | Whether local overrides are retained |
| Start at login | Startup settings in the client or desktop environment | Whether the background core starts more than once |
Choose the package format before toggling features
The same subscription can be used on different devices, but permissions, installation formats, and background behavior vary. The download page lists clients by operating system. On desktop, check your processor architecture first; on mobile, check the OS version. Start with a client you can install and maintain, then compare interfaces.
Start by comparing Clash Plus with clients such as Clash Verge Rev and FlClash. If you need to route traffic from apps installed through a store, remember that the system proxy and loopback access are separate issues—repeatedly switching nodes will not fix them. Check your system architecture before installation, and quit the old core before migrating to avoid port conflicts.
Go to Downloads →Choose the package for Apple Silicon or Intel. Clash Plus, Clash Verge Rev, and FlClash differ in interface and workflow, so check menu bar controls and how each installs its service. If macOS shows a permissions prompt on first launch, read it carefully; not every permission is required to enable the proxy.
Go to Downloads →Choose Clash Plus, Clash Meta for Android, or FlClash based on your needs. The VpnService permission requested when connecting creates a local virtual interface and generally cannot be used at the same time as another VPN. If the connection drops shortly after starting, check battery optimization and background restrictions before reinstalling the app.
Go to Downloads →Install Clash Plus from the App Store. The official product website is clashplus.io. After importing a configuration, approve the VPN prompt from the system, then choose a policy in the client. If something goes wrong after switching between mobile data and Wi-Fi, check the connection status and confirm the configuration is still selected.
Go to Downloads →For a Linux desktop, compare Clash Verge Rev and FlClash. Debian- and Ubuntu-based systems typically use DEB packages; RPM-based systems should look for a compatible package. After installation, check separately that the app opens, the core starts, and the system proxy works. These checks are more reliable than looking at the tray icon alone.
Go to Downloads →Three steps for your first connection
The client does not include a proxy service. Get a subscription you are authorized to use or prepare a local configuration, then follow the steps below. For your first setup, change only what is necessary and keep a known-working baseline. That gives you a point of reference when you later enable TUN or add rules.
Paste a subscription link on the subscription or configuration page, or import a local YAML file. Once it downloads and parses, confirm that the configuration appears in the list and set it as active. A successful import does not mean it is enabled. If the proxy groups are empty, check that the subscription is complete and uses a format supported by the current core.
Subscription links may contain access credentials, so treat them like passwords. Hide the full link in screenshots, and never post it in a public forum. If an update fails, check the specific error to distinguish an expired link, a failed network request, and a configuration syntax issue.
Start in Rule mode, choose an available policy from a proxy group, then enable the system proxy. A latency test shows how quickly the selected test target responds; it does not predict performance on every website. Open the services you use regularly to confirm. Avoid changing the mode, DNS, and node in the same test, or it will be hard to tell which change made a difference.
If the browser works but other apps still cannot connect, check their proxy settings or the scope of TUN routing. Handle steps that require administrator permission separately so a failed service installation is not mistaken for a broken subscription.
Open a service you want to test, then check the client's connection list for the domain, matched rule, and proxy used. If the logs show an error, note when it occurred and what you were doing; a change in latency alone does not indicate a client fault. Once everything checks out, back up local overrides before setting a subscription update interval and startup behavior.
When you finish testing, turn off the system proxy and confirm that regular connections work again. On Linux, undo any proxy environment variables you set in the terminal as well; desktop proxy controls usually do not clear variables already set in your shell.
Project Lineage and Maintenance
Choosing a client is about more than its interface. Knowing which component reads the configuration, manages desktop services, and provides updates helps when changing devices or migrating an existing setup. This site organizes download links and usage guides; each client and core is maintained by its own project.
Clash popularized a configuration model built around configuration files, policy groups, and routing rules, leading to a range of graphical clients. After the original project stopped being maintained, the community continued development in different directions. Clash Meta later continued under the mihomo name. Many actively maintained clients use it as their core, though update schedules vary between clients.
A client with Clash in its name does not necessarily support the same features as another. Check the current core's capabilities for protocol support, and the GUI client's features for the tray, keyboard shortcuts, and overrides. Keeping these roles separate also explains why the same configuration can behave differently in two clients.
mihomo source code and project documentation are publicly available. For desktop users, open source makes it possible to look up configuration fields, read issue discussions, and understand the limits of a feature; it does not mean everyone needs to build from source. After installing a GUI client, use its bundled core and service management options to avoid troubleshooting complications caused by mixing tools.
Before migrating, keep a copy of your existing configuration, then check protocol types, rule set references, and DNS settings. Client-specific scripts and overrides may not be included in the subscription file, so copying a link alone may not carry over all your settings. For details on core lineages and protocol trade-offs, see the core overview in the technical reference.
Client updates, core updates, and subscription updates are three separate maintenance paths. A client update may change the interface or desktop integration; a core update may change how configuration fields behave; a subscription update may replace nodes, policy groups, or rules. If something changes, first identify which layer was updated, then check the logs and configuration instead of assuming one setting caused it.
Keep a record of configurations and overrides that work well. After an update, test your usual services, then check local network access, wake-from-sleep behavior, and network switching. A restorable setup helps maintain stability better than frequently switching clients; archived clients are best treated as migration references.
The command below only clones the public repository to your computer; it does not install the program or start a service. Most users can simply use a GUI client. If you want to inspect the implementation or contribute, prepare Git and the required build environment first.
Open the mihomo repository →git clone https://github.com/MetaCubeX/mihomo.gitConfiguration Notes and Platform Notes
Once the basic connection works, you can tackle switching between profiles, background operation, and choosing a client. The three latest articles below pair practical steps with decision-making advice, so you can find the right details when a question comes up.
Learn what a Profile is, how subscription-based and local configurations differ, how to set an auto-update interval, and how to switch, merge, and back up multiple configurations.
Read more →Learn what the Android VpnService permission prompt means and where to find battery optimization, auto-start, and background activity settings on different Android devices to prevent the system from disconnecting the client.
Read more →Compare popular Clash GUI clients by core version, interface, TUN support, subscription management, and maintenance status, with recommendations for different workflows.
Read more →