---

mihoro - The 🦀 Rust™-based Mihomo CLI client on Linux.

• Setup, update, apply overrides, and manage with systemd. No more, no less.
• No root privilege required. Maintains per-user instance.
• First-class support for config subscription.

Install

curl -fsSL https://raw.githubusercontent.com/spencerwooo/mihoro/main/install.sh | sh

Optionally, download over a mirror:

curl -fsSL https://raw.githubusercontent.com/spencerwooo/mihoro/main/install.sh | sh -s -- --mirror https://gh-proxy.org

Important

mihoro is installed to ~/.local/bin by default. Ensure this is on your $PATH.

Initialize

mihoro, like mihomo, is a config-based CLI client.

After installing mihoro, run:

mihoro init

If ~/.config/mihoro.toml does not exist yet, mihoro init will create it, prompt for your remote mihomo or clash subscription URL, save it, then finish the full onboarding flow in the same run.

Upon onboarding, mihoro will:

• download the mihomo core binary
• download your remote config and apply local overrides
• download geodata and the default web dashboard
• install and enable mihomo.service
• start the service and print dashboard URLs for the configured controller

You can also proxy GitHub-hosted runtime downloads by setting MIHORO_GITHUB_MIRROR before commands such as mihoro init or mihoro update:

MIHORO_GITHUB_MIRROR=https://gh-proxy.org mihoro init

Note that this only applies to GitHub-hosted resource downloads and does not affect mihoro upgrade yet.

The generated config uses sensible defaults, including metacubexd as the managed dashboard:

remote_config_url = "https://example.com/subscription"
ui = "metacubexd"
mihomo_channel = "stable"
mihomo_binary_path = "~/.local/bin/mihomo"
mihomo_config_root = "~/.config/mihomo"
user_systemd_root = "~/.config/systemd/user"
mihoro_user_agent = "mihoro"
auto_update_interval = 12

[mihomo_config]
port = 7891
socks_port = 7892
mixed_port = 7890
allow_lan = false
bind_address = "*"
mode = "rule"
log_level = "info"
ipv6 = true
external_controller = "0.0.0.0:9090"
external_ui = "ui"
geodata_mode = false
geo_auto_update = true
geo_update_interval = 24

[mihomo_config.geox_url]
geoip = "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
geosite = "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
mmdb = "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/country.mmdb"

By default, ui = "metacubexd" enables dashboard management, so mihoro init also downloads the web UI assets and serves them from the configured external_controller. When the controller binds all interfaces, mihoro init prints localhost plus detected non-loopback machine IPs such as LAN or Tailscale/ZeroTier addresses.

init is idempotent — re-running it skips any artifacts that are already in place. Use --force to re-download everything:

mihoro init --force

For non-interactive environments, pre-populate remote_config_url in mihoro.toml and use:

mihoro init --yes

Use --arch if auto-detection picks the wrong mihomo build for your machine:

mihoro init --arch amd64-v3

Usage

To configure proxy for the current terminal session:

eval $(mihoro proxy export)

To revert proxy settings:

eval $(mihoro proxy unset)

To check running status of mihomo core:

mihoro status

To update subscribed remote config:

mihoro update
# or explicitly: mihoro update --config

To apply settings changes after modifying mihoro.toml:

mihoro apply

To update mihomo binary (core) and/or geodata:

mihoro update --core     # updates core
mihoro update --geodata  # updates geodata
mihoro update --ui       # updates external UI assets
mihoro update --all      # updates config -> geodata -> core -> ui -> restarts mihomo

To enable auto-update via cron job:

mihoro cron enable

To disable auto-update:

mihoro cron disable

To check auto-update status:

mihoro cron status

The auto_update_interval in mihoro.toml controls the update frequency in hours (default: 12, range: 1-24). Set to 0 to disable.

To upgrade mihoro itself to the latest version:

mihoro upgrade

Or check for updates without installing:

mihoro upgrade --check

To manually specify a target architecture (useful when auto-detection fails, e.g., on Ubuntu 20.04):

mihoro upgrade --target x86_64-unknown-linux-musl
mihoro upgrade --target aarch64-unknown-linux-musl

Shell auto-completions are available under mihoro completions for bash, fish, zsh:

# For bash:
mihoro completions bash > $XDG_CONFIG_HOME/bash_completion/mihoro  # or /etc/bash_completion.d/mihoro

# For fish:
mihoro completions fish > $HOME/.config/fish/completions/mihoro.fish

# For zsh:
mihoro completions zsh > $XDG_CONFIG_HOME/zsh/completions/_mihoro  # or to one of your $fpath directories

Full list of commands:

$ mihoro --help
Mihomo CLI client on Linux.

Usage: mihoro [OPTIONS] [COMMAND]

Commands:
  init         Initialize mihoro: download binary, config, geodata, and set up the systemd service
  update       Update mihomo components (config by default)
  apply        Apply mihomo config overrides and restart mihomo.service
  start        Start mihomo.service with systemctl
  status       Check mihomo.service status with systemctl
  stop         Stop mihomo.service with systemctl
  restart      Restart mihomo.service with systemctl
  log          Check mihomo.service logs with journalctl [aliases: logs]
  proxy        Output proxy export commands
  uninstall    Uninstall and remove mihoro and config
  completions  Generate shell completions for mihoro
  cron         Manage auto-update cron job
  upgrade      Upgrade mihoro to the latest version
  help         Print this message or the help of the given subcommand(s)

Options:
  -m, --mihoro-config <MIHORO_CONFIG>  Path to mihoro config file [default: ~/.config/mihoro.toml]
  -h, --help                           Print help
  -V, --version                        Print version

Dashboard

On controlling mihomo itself, we recommend using a web-based dashboard. Some options include metacubexd, zashboard, or yacd.

Web-based dashboards require enabling external_controller under [mihomo_config]. Applying this config will expose mihomo's control API under this address, which you can then configure your dashboard to use this as its backend.

mihoro manages dashboard source via top-level ui config, which defaults to metacubexd and also supports zashboard, yacd-meta, or custom:download_url. The downloaded static files are placed into mihomo_config.external_ui. In this case, mihomo will serve the dashboard locally under {external_controller}/ui. Please refer to the official documentation of mihomo for more information: docs/external_controller, docs/external_ui.

License

MIT