Clash for Linux Installation Guide (clashctl)

Use the open-source clashctl script to deploy the Mihomo core on a Linux server or desktop in one step, then manage subscriptions, the proxy, TUN mode, and the web dashboard from the command line.

clashctl (formerly clash-for-linux-install) is an open-source set of command-line scripts for Linux. It deploys the Mihomo core in one step and adds subscription management, a terminal proxy switch, TUN mode, and a web dashboard. It's ideal for headless servers and for desktop users who prefer the command line.

Runs on	Core	License	Price
Mainstream Linux distributions and containers	Mihomo (default) / Clash	MIT	Free

On a Linux desktop with a graphical interface, you can also install Clash Verge Rev or FlClash.

Install

Check dependencies

The installer needs curl, tar, gzip, unzip, and sha256sum. Install any that are missing:

sudo apt update && sudo apt install -y curl tar gzip unzip coreutils

sudo dnf install -y curl tar gzip unzip coreutils

sudo pacman -S --needed curl tar gzip unzip coreutils

Run the installer

curl -fsSL https://raw.githubusercontent.com/nelvko/clashctl/HEAD/install.sh | bash

The script downloads the project, deploys the core, and registers the clashctl command. Both regular users and root can install it, and it supports systemd and OpenRC. Open a new terminal afterwards so the command is available.

You can pass your subscription during installation:

curl -fsSL https://raw.githubusercontent.com/nelvko/clashctl/HEAD/install.sh | bash -s -- --sub "<subscription link>"

If your server reaches GitHub slowly, use --gh-proxy <address> to set a GitHub mirror you trust.

Setup

Get your subscription link

clashctl is only a management tool and does not include any servers. Sign in to your provider's dashboard and copy your subscription link.

Need a subscription? See these subscription plans (third-party affiliate link; check the details before you buy). Treat your subscription link like a password and don't share it.

Add the subscription

clashctl sub add --use "<subscription link>"

Subscription links contain special characters such as &, so always wrap them in double quotes. --use activates the subscription right after adding it.

Turn on the proxy

clashctl on
curl -I https://www.google.com

clashctl on starts the core automatically and sets the proxy environment variables for the current terminal. If the second command returns an HTTP status code, the proxy works.

Common commands

Command	What it does
`clashctl on` / `clashctl off`	Turn the proxy on / off for the current terminal (`off` keeps the core running by default)
`clashctl start` / `clashctl stop`	Start / stop only the core
`clashctl status`	Show core status, terminal proxy status, and proxy addresses
`clashctl sub ls`	List subscriptions
`clashctl sub use <name>`	Switch subscriptions
`clashctl sub update`	Update the current subscription (`--all` updates all of them)
`clashctl node`	Switch servers
`clashctl log`	View logs
`clashctl upgrade`	Upgrade the core
`clashctl update`	Update the clashctl scripts

Advanced settings

Web dashboard

clashctl ui                  # print the dashboard address
clashctl secret              # show the access secret
clashctl secret "<new secret>"   # change the secret

Open the dashboard address in a browser to switch servers and view connections. Don't expose a server's dashboard directly to the internet; use SSH port forwarding instead.

TUN mode

clashctl tun on      # enable
clashctl tun off     # disable
clashctl tun         # show status

TUN mode captures all system traffic, including Docker containers, so you no longer depend on terminal environment variables. Some minimal kernels and container environments don't support TUN. See Advanced Settings for background.

Mixin custom config

Mixin is merged with your subscription config and takes priority, which makes it the place for custom rules, DNS, and proxy groups:

clashctl mixin       # view the Mixin config
clashctl mixin -e    # edit Mixin; changes apply on save
clashctl mixin -c    # view the original subscription config
clashctl mixin -r    # view the config the core is actually running

Uninstall

clashctl off
bash "$CLASHCTL_HOME/uninstall.sh"

Run clashctl off first to clear the proxy variables in the current terminal; the uninstall script can't do this. Uninstalling deletes the install directory and its data, so back up any configs you want to keep.

FAQ

Clash Verge Rev

A graphical client for Linux desktops.

OpenClash

Proxy every device at home from an OpenWrt router.

Troubleshooting

A checklist for import failures and connection problems.

Edit this pageorReport an issue