From config.yaml to TUN proxying, follow the steps to set up a persistent systemd service.
01 / CLIENT DOWNLOADS
Choose a GUI client for desktop use; on servers and routers, choose the mihomo core for your architecture.
Clients handle subscriptions, GUI controls, and system integration; the core handles connections and rule processing. First identify your operating system, CPU architecture, and package format, then follow the relevant installation steps. Back up existing configuration before importing to avoid overwriting local rules.
Choose a client such as Clash Plus or Clash Verge Rev. For your first connection, set up the system proxy and check that your browser uses the same port. Configure TUN and service permissions only if you need to route traffic from other applications.
Go to downloadsChoose a package for Apple silicon or Intel. The Clash for macOS download page lists GUI clients and archived projects. Before downloading ClashX Meta, check its maintenance status and compatibility with your current macOS version.
Go to downloadsChoose an Android package for your device architecture. On first launch, approve the system VPN permission, then check background activity restrictions after connecting. If the proxy disconnects when you switch apps, review battery optimization and background activity settings; there is no need to repeatedly reimport your subscription.
Go to downloadsVisit the download page for Clash Plus on the App Store and its official site, clashplus.io. After installation, import a compatible configuration, then add a VPN configuration when prompted. Rules and proxy groups depend on what the client supports.
Go to downloadsFor a graphical desktop, choose Clash Verge Rev or FlClash. Select the appropriate package format for Debian-based or RPM-based distributions; on a headless server, run mihomo directly. Check the architecture with uname -m, then configure the directories and service.
Package format and CPU architecture are separate considerations. A distribution may support a package format, but you still need to confirm that its binaries match your device. When using a GUI client, don't also start a standalone core that listens on the same ports.
Browse all clients02 / CONFIGURATION WORKSPACE
Start with the local listener, then add configuration layers as needed.
The examples below are field snippets, not complete subscriptions. First get the local proxy port working, then configure traffic routing and rule references. Change one type of field at a time and check the logs before continuing. This makes it easier to tell configuration errors, permission issues, and upstream connection failures apart.
mihomo parses configuration, listens on ports, and applies routing rules; GUI clients add subscription management and system integration. Set mixed-port first so applications that support HTTP or SOCKS can connect to a local endpoint, then run a config check to confirm the YAML parses correctly. Unlike relying solely on GUI toggles, managing files directly suits servers and remote terminals, but means handling directories, permissions, and logs yourself. Keep the control interface bound to localhost rather than exposing it to the network.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090Check the local listening address first.
TUN routes traffic through a virtual network device, making it useful for applications that ignore system proxy settings and environment variables. Unlike specifying a proxy port manually, TUN involves device permissions, routing tables, and DNS, so enable it only after basic proxy tests pass. On Linux, first confirm that /dev/net/tun exists, then grant the required capabilities for your chosen run mode. After enabling automatic routing, check that local network access still works. If you use another VPN, a container bridge, or custom policy routing, save the current settings first to avoid competing traffic-routing components changing the routes at the same time.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: trueCheck permissions before changing routes.
Rules are evaluated in order, and the first matching rule determines where a connection goes. Start with specific domain rules and LAN exceptions, add rule sets next, and finish with MATCH. Policy names must exactly match existing proxy groups. Unlike Clash global mode, which sends everything to one policy, rule mode can route direct traffic and proxy connections separately. When troubleshooting, check the domain, destination address, and matched rule in the logs; a page loading successfully doesn't prove the rules are correct. For remote rule sets, also confirm that downloads succeed, the format is valid, and the sets are referenced in rules.
# The Proxy policy group must be defined in the full configuration
rules:
- DOMAIN-SUFFIX,example.org,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,ProxyRules are matched from top to bottom.
Providers keep node sources separate from local policies, which is useful when you want to preserve custom rules. proxy-providers supply nodes; rule-providers supply rules, and they are not interchangeable. Unlike replacing the entire configuration with a subscription, separating providers lets you update sources independently and reduces the risk of overwriting local changes. First confirm that the response is compatible YAML, then configure the path, refresh interval, and proxy group references. Subscription URLs often contain access credentials, so keep them local and remove sensitive query parameters before sharing logs or configuration.
proxy-providers:
local-nodes:
type: file
path: ./providers/nodes.yaml
proxy-groups:
- name: Proxy
type: select
use:
- local-nodesThe provider name must match the use reference.
systemd turns a manual terminal launch into a service you can inspect and restart. First create a user service unit, specifying the absolute binary path and configuration directory, then run the config check and start the service. Unlike launching a process in the background, a service unit centralizes logs and defines what happens after a process exits. A user service is not a system service; running it outside a login session also depends on linger. Enabling the service does not grant TUN permissions. After updating the binary, check its capabilities again, then verify the service and listening ports.
mihomo -t -d ~/.config/mihomo
systemctl --user daemon-reload
systemctl --user enable --now mihomo
systemctl --user status mihomo
journalctl --user -u mihomo -bCreate the service unit before enabling it.
Configuration fields depend on one another: nodes feed into proxy groups, which are referenced by rules; DNS and routing also determine whether traffic reaches the core as expected. Passing a config check only means the file is accepted—you still need to send a real request to verify it works.
See the config.yaml reference03 / FIRST CONNECTION
Establish a testable connection before enabling transparent proxying.
GUI clients and direct core deployments use different controls, but the verification steps are the same: confirm the configuration source, check that the core starts, then verify that application traffic actually reaches the proxy. Importing a subscription successfully does not mean the connection works.
STEP 01
Desktop users can install a GUI client and import a configuration through its interface. For a command-line setup, place the file at ~/.config/mihomo/config.yaml. Back up any existing file first, then check whether the subscription provides a complete configuration or only nodes for a Provider. These use different import paths and cannot be swapped just by changing the file extension.
Get the configuration URL from your subscription provider. Downloads on this site are software only and do not include proxy nodes. On a remote server, also check directory ownership to ensure a regular user can read files created by an administrator.
STEP 02
For a command-line setup, run the config check first to confirm that indentation, fields, and policy references are valid, then start the core. Keep info logging enabled at first and check that the listening address matches your configuration. If a port is already in use, identify the process holding it before making changes. Don't keep changing ports while leaving applications configured with an old proxy address.
mihomo -t -d ~/.config/mihomo
mihomo -d ~/.config/mihomoIn a GUI client, the equivalent steps are usually to enable the configuration and start the service. The exact controls vary by client.
STEP 03
Start with an explicit proxy request to confirm that the application can reach the local port and that the connection appears in the logs. Then enable the system proxy and test your browser; enable TUN last if needed. Repeat the request test each time you add another traffic-routing layer to pinpoint where a problem occurs.
curl -I -x http://127.0.0.1:7890 https://example.orgAn HTTP response confirms that the request received a response; it doesn't mean every domain or rule is working. Test the sites you actually need to use as well.
For a Clash Verge Rev guide, follow the GUI setup to import your configuration, then use the field reference to understand how it works under the hood. Environment variables affect only processes that read them, and the system proxy does not route every connection. If the terminal works but the browser doesn't, check each application's proxy settings separately instead of immediately switching subscriptions.
Read the full guide04 / SOURCE & OPERATIONS
Check project sources to understand the software; check runtime logs to verify deployment.
Clash for Linux curates client downloads and deployment resources; it is not the development team behind every client. Commands on this site show common Linux usage, but check your distribution, desktop environment, and permissions before running them. Check each project's license, feature support, and maintenance status separately.
The Clash ecosystem includes proxy cores, GUI clients, and configuration tools. Similar names don't mean they're the same project. mihomo continues the work of the Clash.Meta project, retaining Clash-style configuration while adding protocol and runtime features. When migrating an older configuration, check each section rather than assuming every client supports the same fields. If you encounter an unknown field, identify the core actually running instead of relying on the window title.
This site focuses on deploying mihomo on Linux, with GUI client guides to help you choose an installation option. A client's subscription, override, and service modes may add their own configuration layers, so the configuration ultimately passed to the core may differ from the imported file. When troubleshooting reference errors, distinguish between the original subscription, local overrides, and the active runtime configuration.
You can browse mihomo source code in the MetaCubeX/mihomo repository. The project is licensed under GPL-3.0. Reviewing the source, build instructions, and issue history can help establish whether a field is supported and whether a behavior change comes from the core or client integration. Open source does not mean you can run a download as-is: cloning gives you project files, and building requires the toolchain described upstream.
Copy the command on the right to clone the repository and review the implementation or prepare a build. Most desktop users can simply choose a client from the download page. Third-party GUI clients maintain their own release schedules; the license and update history of one core project do not apply to every client.
The core, GUI client, subscription, and rule sets are separate update targets. Before upgrading software, save the configuration and service unit in use, review relevant changes, and run a config check. Updating a Provider replaces its source data; it does not upgrade the core. Local rule changes are not automatically synced to the subscription server. Know who manages each file to avoid having your changes overwritten on the next refresh.
After replacing a Linux binary, check that it is executable and that the service path and TUN capabilities are still correct. Test it in the foreground before restarting the persistent service. If it fails, keep the error output and troubleshoot configuration, file access, and network connectivity separately.
For single-machine use, bind the proxy listener and control interface to loopback, and keep allow-lan: false. To serve your LAN, explicitly configure the listening address, firewall scope, and access controls. The control interface manages the core and should not be exposed just because the proxy works. Don't post subscription URLs in public issue reports.
When using systemd, start troubleshooting with the logs. A service can be running while subscription retrieval or DNS is failing; conversely, a single website failing doesn't necessarily mean the service has stopped. Check the listening port, send an explicit proxy request, and review its corresponding logs. This is usually more effective than repeatedly switching modes.
Does installation include proxy nodes?Software and subscriptions are provided separately; import your own compatible configuration. Access, format, and expiration for Clash subscription services are managed by the provider. Installing a client does not mean your subscription is ready to use.
Will global mode fix every connection issue?No. It doesn't replace checks for ports, DNS, or permissions. First verify that traffic reaches the core, then switch modes to help determine whether rule matching is the issue. Restore your intended mode after testing.
Should I use TUN or the system proxy?Start with the system proxy to establish a verifiable baseline. Enable TUN only if an application doesn't read proxy settings. They route traffic at different points, so success with one doesn't confirm that the other is configured correctly.
05 / DEPLOYMENT NOTES
Explore guides for your deployment needs instead of configuring every option during initial setup.
After your first connection works, move on to scheduled updates, configuration structure, and mobile background behavior. Use article snippets with your existing configuration: confirm the field's correct section before copying, check the active configuration after editing, and compare results using the same requests.
Follow the configuration file's natural order, with explanations of common ports, run modes, DNS, proxies, proxy-groups, and rules, including how sections reference one another. Each section includes a copyable example.
Read articleExplore why a persistent mobile proxy can drain the battery, including health-check frequency, log levels, manufacturer-specific background restrictions, battery optimization settings, and power-saving tips for VPN mode.
Read articleUnderstand errors such as subscription timeouts, certificate failures, rejected user agents, and incompatible formats. Learn how to use proxy-providers interval settings and health checks for automatic subscription updates.
Read article