Deploy mihomo on a Linux Server with systemd Autostart

A Linux server is where the mihomo core feels most at home: no GUI to install, just a single binary, a config directory and a systemd unit that keeps it alive across crashes and reboots. The result is an always-on proxy that your machine — or your whole network setup — can rely on.

This tutorial goes end to end: pick the right binary for your CPU, install it to /usr/local/bin, create /etc/mihomo with a validated config, wire up systemd with auto-restart, verify the proxy with curl, and update (or roll back) safely later.

You need a distribution with systemd, an account with sudo, and a config in Clash/mihomo YAML format. Nothing else: mihomo ships as one self-contained executable.

Download the right binary

First check the server's architecture:

uname -m

x86_64 means you want the amd64 build; aarch64 means arm64. Both are provided as mihomo v1.19.29 single-file .gz downloads in the download center's Linux section.

Downloaded it on your laptop? Copy it across first:

scp mihomo-linux-amd64-*.gz user@your-server:~/

Install it to /usr/local/bin

gunzip mihomo-*.gz
chmod +x mihomo-*
sudo mv mihomo-* /usr/local/bin/mihomo
mihomo -v

The wildcard covers the versioned filename; after the move, the core is on your PATH under the plain name mihomo, and mihomo -v printing a version confirms the binary matches your architecture. An answer of cannot execute binary file means you took the wrong build.

/usr/local/bin is the conventional home for hand-installed software: on the default PATH, never touched by package managers. Dropping the version from the filename keeps the unit below valid across upgrades.

Create /etc/mihomo and your config

sudo mkdir -p /etc/mihomo

Place your configuration at /etc/mihomo/config.yaml — either a Clash/mihomo-format file exported from your provider or one written by hand (the structure is explained in the config basics guide). Always validate before going live:

mihomo -t -f /etc/mihomo/config.yaml

Errors are reported with line numbers; fix them until the test passes cleanly. Indentation slips and a missing space after a colon account for most failures.

Treat that file as a credential store: node addresses, passwords and UUIDs sit in it as plain text. Tighten the permissions so other accounts cannot read it:

sudo chmod 600 /etc/mihomo/config.yaml

The directory doubles as the core's data store: on first start it may download GeoIP and rule-set databases into it, so leave it writable.

Set up the systemd service

Create /etc/systemd/system/mihomo.service with the following unit:

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

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Every line earns its place. After=network-online.target with its matching Wants= stops systemd from launching the core before the machine has a usable network, which otherwise makes boot-time starts fail on name resolution. Type=simple matches mihomo's behavior: it stays in the foreground instead of forking. Restart=always revives the core seconds after any exit.

Running it without root

Unless your config creates a TUN device, the core needs no privileges at all. Create a system account, hand it the directory with sudo chown -R mihomo:mihomo /etc/mihomo, and add to [Service]:

User=mihomo
Group=mihomo
LimitNOFILE=65535

The raised descriptor ceiling is cheap insurance for a busy proxy.

Enable and follow the logs

Load and start everything:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
journalctl -u mihomo -f

enable --now starts the service immediately and registers it for autostart at boot; journalctl -u mihomo -f follows the live log, which is your first stop whenever behavior looks off. A healthy start names the ports the core listens on; a unit that keeps appearing and vanishing from the log is one whose config the core rejects, relaunched forever by Restart=always.

The commands you will use afterwards:

Verify with curl

Test that traffic actually flows through the core's local port:

curl -x http://127.0.0.1:7890 -I https://www.example.com

Use the mixed-port value from your own config in place of 7890 (commonly 7890 or 7897 — check the file). HTTP headers coming back means the proxy chain works end to end. Whether the port is reachable from other machines is governed by your config's listening settings, so keep it local unless you have deliberately configured otherwise.

Two failure modes cover nearly everything. Connection refused means nothing is listening there: check ss -tlnp | grep mihomo and the log. A request that hangs means the core took your connection but could not finish the outbound one, which points at an unreachable node.

Update and roll back

1. Stop the service: sudo systemctl stop mihomo
2. Keep an escape hatch: sudo cp /usr/local/bin/mihomo /usr/local/bin/mihomo.bak
3. Unpack the new build (gunzip, chmod +x) and move it over /usr/local/bin/mihomo.
4. Validate the config against the new version with mihomo -t, then sudo systemctl start mihomo.
5. If anything regresses, restore the backup binary and start the service again — that is the whole rollback.

Run two checks after every upgrade: systemctl status mihomo, to be sure the service settled into a running state rather than a restart loop, and one curl through the local port. The same cycle on a desktop machine is covered in the mihomo command-line guide for Windows.