Deploying Clash on Linux: Desktop Client Setup and mihomo CLI Configuration

Pick a Path: GUI Client or Command Line

There are two ways to run Clash on Linux. The first is a desktop client: apps like Clash Verge Rev and FlClash come with a full GUI, so subscription import, node switching, latency testing, and rule viewing all happen in a window — a good fit for everyday desktop use. The second is the mihomo core plus the command line: mihomo is the continuation of the Clash Meta core, free and open source, containing only the proxy engine with no interface. Everything is configured in a single YAML file, which suits servers, NAS boxes, and routers running custom firmware, as well as desktop users who want the proxy to run like a persistent background service.

The two paths aren't mutually exclusive. The same machine can run the GUI client at home and have systemd bring up mihomo on the road instead. The table below lays out the trade-offs — figure out which fits before diving in.

Installing the Desktop Client

Head to this site's Download Center and open the Linux section, then pick the package format that matches your distro. Debian, Ubuntu, and Deepin use .deb packages; Fedora and openSUSE use .rpm packages; if you'd rather not install anything system-wide, grab the AppImage instead. Clash Verge Rev ships both deb and rpm builds, and FlClash ships deb — both bundle the mihomo core, so they're ready to use right after installation.

# Debian / Ubuntu family
sudo dpkg -i clash-verge_*_amd64.deb
sudo apt -f install    # fix missing dependencies

# Fedora / openSUSE family
sudo dnf install ./clash-verge-*-1.x86_64.rpm

AppImage needs the FUSE runtime. Ubuntu 22.04 and later don't ship it by default, so install libfuse2 first (on 24.04 the package is named libfuse2t64); Fedora's equivalent is fuse-libs. After that, just make the file executable and run it.

sudo apt install libfuse2
chmod +x FlClash-*-amd64.AppImage
./FlClash-*-amd64.AppImage

Two things to watch for. First, pick the right architecture: amd64 (x86_64) for a regular PC, arm64 for Raspberry Pi and ARM laptops — the wrong build simply won't start. Second, after the first launch, go to the subscription page and paste the Clash subscription link from your proxy provider, refresh to pull the node list, then switch to the proxy page to pick a node and flip on the system proxy toggle in settings. If you want full traffic takeover, enable TUN mode — the client will prompt for a one-time kernel elevation, after which every app's traffic routes through the proxy automatically, no per-app setup needed.

Deploying mihomo via Command Line

The CLI route breaks down into three steps: install the core, prepare the config, and verify it manually. Once it's working, hand it off to systemd for management.

Step 1: Install the Core

Grab the Linux archive from this site's Download Center or mihomo's GitHub Releases — the filename looks like mihomo-linux-amd64-v1.18.9.gz (use whatever the current version is). If your CPU is older and lacks the x86-64-v3 instruction set, use the build with compatible in the filename instead. Extract it and put it on your system PATH:

gunzip mihomo-linux-amd64-v1.18.9.gz
chmod +x mihomo-linux-amd64-v1.18.9
sudo mv mihomo-linux-amd64-v1.18.9 /usr/local/bin/mihomo
mihomo -v    # prints the version number if installed correctly

Step 2: Set Up the Config Directory

sudo mkdir -p /etc/mihomo
sudo curl -L -o /etc/mihomo/config.yaml "your Clash subscription link"

Most providers give you a Clash-format subscription URL directly, so pulling it down gives you a ready-to-use config.yaml. If your provider only offers a generic subscription, import it into a desktop client first and export the config, or run it through a subscription converter to get Clash format. GeoIP and GeoSite data files (geoip.metadb, geosite.dat, etc.) download automatically to the config directory on first launch; if network access is limited, copy the same files over from a machine that already has the client installed.

Three fields in config.yaml matter most for day-to-day use:

mixed-port: 7890                        # combined HTTP/SOCKS inbound port
allow-lan: false                        # whether to allow LAN devices to connect
external-controller: 127.0.0.1:9090     # controller address, local-only by default

• mixed-port: the combined HTTP/SOCKS entry port — this is what your system proxy should point to.
• allow-lan: whether other devices on the LAN can connect; keep it false for single-machine use.
• external-controller: the address for the external controller, which panel-style tools use to manage the core.

Step 3: Start Manually and Verify

mihomo -d /etc/mihomo

Once the terminal prints the mixed inbound listener log, open a second terminal window to verify the egress:

curl -x http://127.0.0.1:7890 https://api.ip.sb

If the returned exit IP matches the region of your selected node, the proxy chain is working. Press Ctrl+C to stop the process, then move on to setting it up as a service.

Registering Autostart with systemd

Once it's confirmed working manually, hand mihomo off to systemd for boot-on-startup and automatic recovery from crashes. As root, create /etc/systemd/system/mihomo.service:

[Unit]
Description=mihomo proxy daemon
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Reload the unit files and enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo     # active (running) means it worked
journalctl -u mihomo -f     # tail the core's logs in real time

If status shows active (running), the service is up; when troubleshooting, check the journalctl output first — error messages usually point straight to the offending line.

If you need TUN mode for full traffic takeover, first enable the tun block in config.yaml:

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

Then add two capability lines under the [Service] section of the unit file, granting the core permission to create a virtual network interface:

AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE

After making the change, run systemctl daemon-reload and restart mihomo to apply it.

Subscription refresh can be automated too: use cron to re-fetch config.yaml weekly, then systemctl restart mihomo — or call the controller's API to hot-reload without a restart:

curl -X PUT "http://127.0.0.1:9090/configs?force=true" \
  -d '{"path": "/etc/mihomo/config.yaml"}'

Routing the Desktop Environment Through the Proxy

Getting the core running is only step one — system traffic still needs to be pointed at it. On GNOME: Settings → Network → Network Proxy → Manual, set both HTTP and HTTPS host to 127.0.0.1 with port 7890, and point SOCKS to the same 127.0.0.1:7890. KDE uses the equivalent Network Proxy page in System Settings. The command-line equivalent:

gsettings set org.gnome.system.proxy mode 'manual'
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 7890

For a temporary proxy in a single terminal session, environment variables are more direct:

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

Add these three lines to ~/.bashrc to make them persistent. If TUN mode is already on, skip all of this — traffic is intercepted at the routing layer and apps need no configuration at all.

Frequently Asked Questions

In short: the desktop client handles day-to-day usability, while mihomo plus systemd handles always-on reliability. Follow this guide in order and a Linux machine gets a stable proxy chain running from the moment it boots. Clients and cores for every platform are listed by system in the Download Center — grab whichever fits.