ClashTui: managing Mihomo and sing-box proxies from the terminal

What ClashTui is, and what it deliberately is not

ClashTui is described as a terminal user interface proxy management tool supporting both Mihomo, also known as Clash.Meta, and sing-box proxy cores. The feature list starts where you would expect a proxy client to start and ends somewhere unusual. The point of the tool is that you can switch nodes, update subscriptions, manage connections and control services, all from the terminal. What it is not is a proxy implementation. It is a front end that talks to an existing core, and the dual core support is the first feature listed, with the ability to switch between Mihomo and sing-box at any time in the interface. The primary language is Rust, the licence in Cargo.toml is MIT OR Apache-2.0, the package version is 0.3.2 and the crate description is a Clash and sing-box TUI application. Supported platforms are Linux, macOS and Windows.

The feature set beyond node switching

The list is longer than a node picker, and several entries point at real operational work. Subscription management supports File, URL and Template profile types, where the Template type is a ClashTui template rather than a plain proxy subscription. Proxy switching works by group or by node, with latency testing. Connection monitoring shows all active connections in real time and lets you close individual connections or all of them. Service control manages core start, stop and restart through systemd. Log viewing shows core logs in real time inside the interface, which saves you a second terminal. There is also a config override option, core_override_config, which lets you override the final generated configuration without modifying the original subscription files, a template system that auto-generates config files from templates plus proxy node groups with variable expansion, and the author recommends the template system for sing-box specifically to avoid configuration version issues. Custom key bindings per tab live in keymap.yaml, custom themes in theme.yaml, and there is a which panel for locating binaries and an fzf integration for selection.

CLI mode, and why it matters for automation

The CLI mode is arguably the more interesting half of the project, because a TUI that also exposes scriptable subcommands can sit in a shell pipeline. The README lists profile, mode, service and update as the available subcommands, for scripting and automation. The subscription types, the template expansion and the config override all become scriptable operations rather than mouse-driven ones, which is what makes the tool usable from a dotfiles setup or a provisioning script. The Cargo.toml shows how the CLI is built: clap with the derive feature handles argument parsing, clap_complete provides shell completions, and self-replace is included, which is the mechanism for the tool updating itself. The TUI side is optional in the dependency list, with tokio, crossterm, ratatui and futures-lite all marked optional, so a headless install does not carry the terminal UI stack.

Installing on Linux, and the root versus user decision

The install path differs depending on whether you want TUN mode, and the README splits the instructions accordingly. On Linux and macOS the requirements are sudo and fzf, while Windows needs nssm. For a root install on Linux, the optional first step is to install the cores from your package repository so the install script skips downloading them.

sudo pacman -S mihomo sing-box clashtui  # ArchLinux

Then the install script itself is run with a core selector, and the tip in the README is that it downloads resources from GitHub, so if downloads keep failing you should enable a proxy before running it.

bash <(curl -fsSL https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install) --core all

On boot persistence is handled with a systemd unit, and you enable one or the other, not both.

sudo systemctl enable clashtui_mihomo.service
# OR
sudo systemctl enable clashtui_singbox.service

Without root access, for example when you do not want TUN, the same script is run with the --is-user flag, and the boot units are user-level instead.

bash <(curl -fsSL https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install) --core all --is-user

The macOS path is the same script with the same flags, but persistence uses launchd rather than systemd, loading a LaunchDaemons plist for the root mode and a LaunchAgents plist for the user mode.

Windows takes a different route through CoreSrvCtl

The Windows instructions diverge more than the Linux and macOS ones. The optional first step is a Scoop install of the cores and the tool, followed by a Get-Command check that the binaries are on the PATH, so the install script skips downloading them.

scoop install mihomo sing-box clashtui
# Verify
Get-Command mihomo sing-box clashtui

The install script is then run as Administrator from PowerShell, and the default install location is D:\ClashTui, with a custom directory form that does not allow spaces.

irm https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install.ps1 | iex

The key difference comes after the install. The README is explicit that the install script does not register Windows services: you launch clashtui and use the built-in CoreSrvCtl to install and start the core services, and you should enable only one core service at boot rather than both at once. That is a different model from the systemd and launchd units on Unix, and it is the detail most likely to surprise someone coming from the Linux instructions.

What can go wrong, and where the tool stops

The FAQ names two concrete failure modes. File permission issues arise because clashtui requires group permissions, and the fix is to log in again so the group permissions take effect, which is a symptom of the tool needing elevated rights to control a proxy core. Connection refused issues, for example with mihomo, are diagnosed with netstat -utapln piped through grep for 9090, which is the Clash API port. Beyond that, three limits are worth naming. The first is that a proxy client needs a working core and a working subscription, and ClashTui does not create either for you, so a broken configuration is a broken configuration whether the interface is pleasant or not. The second is that the tool is a front end, so anything the core's API does not expose is out of reach, and the connection monitoring and service control features are exactly as good as the core's API. The third is the service story on Windows, where, as the README says, the install script does not register Windows services and CoreSrvCtl has to be used instead. The alternative to weigh is running the core with its own native client, which is one more window but no second configuration surface to keep in sync.

Documentation, architecture and the release state

The documentation is unusually thorough for a project at 0.3.x, and the README links it as a table. There is a Getting Started guide covering UI operations, the CLI, subscription management, a config reference and an FAQ, a Manual Installation document for system and user mode, a Feature Design document covering the config structure, subscription management, template expansion and the sing-box merge algorithm, an Architecture document covering module structure, startup flow, the TUI event loop and the tab system, and a Development Conventions document that starts with branch naming. The repository tree backs this up, with src/, installs/ for the install scripts, docs/, contrib/, dockers/, assets/, tests/, a build.rs, a CHANGELOG.md and a .githooks/ directory alongside .github/ workflows for build, pull request and release. The recent release tags are v0.3.2-alpha.2 from 2026-05-31, v0.3.2-alpha.1 from 2026-05-30 and v0.3.1 from 2026-05-26, so the published line is still in alpha for the current minor version. The last push was on 2026-09-29, and the repository is not archived.

Editorial conclusion

Adopt ClashTui if you already run Mihomo or sing-box and want a single terminal interface for switching nodes, updating subscriptions and watching live connections, especially if you script the core from a shell and want the same operations available in a UI. Do not adopt it as a proxy core itself, because it drives the cores rather than replacing them, and do not expect the documented service control to work on Windows, where the README says the install script does not register Windows services. Before you install, decide between root mode with TUN and user mode without it, since the install flags differ, and check the requirement that fzf be present on Linux and macOS.

Frequently asked questions

Official sources

1. Issues
2. JohanChane/clashtui on GitHub
3. License: MIT
4. README
5. Releases