Bettbox: a FlClash-derived Mihomo client for desktop and Android

What Bettbox is, and who the README is written for

Bettbox describes itself as "Another Better Mihomo Client" and as a multi-platform network debugging and rule-based routing client that uses the Mihomo (Clash Meta) core. The README states that it is a rebuild based on an early version of FlClash, so the interface lineage is explicit rather than implied. The stated goal is a client that stays smooth in the foreground and draws little power in the background, so it can run for long stretches on modest hardware.

That framing tells you the audience. This is not a library you import, and it is not a headless router daemon. It is a GUI application for people who already have a Mihomo or Clash Meta configuration and want to run it on a phone, a laptop or a TV box. The topics list (bettbox, clash, clash-meta, mihomo, mihomo-client) confirms the same scope.

The README is written in Simplified Chinese, with translations into English, Russian, Persian, Japanese and Korean under readme/. If you only read English, you are reading a translation, and the primary document is the Chinese one.

FlClash as the starting point and Mihomo as the engine

The architecture is two layers. FlClash supplies the GUI, and Bettbox is a rebuild of an early FlClash version rather than a fork that tracks it continuously. Mihomo supplies the proxy core, and the README says the project follows the Mihomo mainline branch and adapts new features as they land. The repository layout matches that split: a core/ directory, a lib/ directory for the Flutter application, and platform folders for android/, linux/, macos/ and windows/.

Because the GUI and the core are separate, upgrades to the proxy engine and upgrades to the interface are separate concerns. That is the normal arrangement for this class of client, and it is also where the risk sits: a rebuild of an early FlClash version means upstream FlClash changes do not automatically arrive here. The README does not describe a rebase or merge policy against FlClash, so how much of the original project's ongoing work reaches Bettbox is not documented.

What the README does claim is a set of behaviours around that core: TUN/VPN permission handling, a double configuration check, a one-click QUIC disable, smart start and stop, Android sleep support, and tray menu additions. The README calls the smart start and stop the first multi-platform implementation of its kind, which is a claim about the project's own history rather than something a reader can verify from the text.

Installing Bettbox on Windows, Linux, macOS and Android

There is no single install command. The README points to the Releases page for the current build for your platform and system, and lists supported targets: Windows 8.1 and later (x64/arm64), Linux kernel 5.4 and later (x64/arm64), macOS 10.15 and later (Intel/Apple Silicon), Android 8.0 and later (ARMv8, ARMv7, x86_64, Universal), and Android TV, which the README says is fully adapted with an optional 32-bit ARMv7 build. HarmonyOS NEXT is listed as usable through a third-party Android compatibility layer.

On Arch Linux there is a packaged route maintained outside the project:

yay -S bettbox-bin

The README also gives paru as an equivalent, and notes a second package for first-generation AMD64 CPUs:

yay -S bettbox-compatible-bin

Both AUR packages are maintained by other people, not by the Bettbox project, which matters when you decide who to ask about packaging problems.

On macOS the README is unusually specific, because the application is not signed with an Apple developer certificate. After opening the .dmg and dragging the icon to Applications, you are told to right-click the icon and choose Open, then confirm. The fallback is System Settings, then Privacy & Security, then "Open Anyway". The first time you enable TUN mode, macOS asks for your login password so Bettbox can configure the network.

First run is then a matter of importing a subscription. The FAQ's advice for a link that will not import is to reset the link first and confirm it works, and to contact the provider before filing an issue.

Building from source with setup.dart

The README gives a Windows example and a specific toolchain: a Windows 10 or later machine, Git, Visual Studio, Flutter 3.44.x, Golang, Inno Setup and Rust. The build is driven by setup.dart, and the README separates building only the core from building the full application:

flutter pub get
dart .\setup.dart windows --arch amd64 --out core
dart .\setup.dart windows --arch amd64 --out app --compatible

The first dart command builds only the core; the second builds the application and is marked in the README as the optional compatible variant. The README states that the final artifacts land in the dist/ directory. The repository's Makefile carries the same pattern for other targets, for example android_arm64 and macos_arm64, plus core-only variants such as android_arm64_core and macos_arm64_core. If you plan to build on Linux or macOS, the Makefile is the more useful reference than the Windows walkthrough, though the README does not document the toolchain for those hosts.

One detail worth noting for anyone scripting distribution: the repository contains a SIGNING-POLICY.md and the README credits SignPath.io and the SignPath Foundation for free code signing on Windows. That covers Windows only. The macOS situation described above is the opposite.

Extending the routing UI with an external override script

From version 1.18.8, the README says Bettbox supports external override scripts that adapt the routing UI. The example given is AIsouler's script and configuration collection, where a single declaration at the top of the script is enough to expose Bettbox's built-in visual switches:

const Compatible_With_Bettbox = { ruleOptionsEnable: true };

This is the most interesting design decision in the project, because it means the routing UI is not fixed. A script author can opt into Bettbox's controls without writing Bettbox-specific code beyond that one line, and the same script presumably keeps working in other clients that ignore the constant. The README presents this as the first such UI adaptation for JavaScript override scripts, which is a claim about precedence rather than capability.

The limitation is that this is documented in a single paragraph with one example. There is no reference for what other keys the object accepts, no statement about which script engines or versions are supported, and no description of what happens when a script declares the constant but the client version predates 1.18.8. If your workflow depends on override scripts, treat the one-line declaration as the documented surface and expect to read the source for anything beyond it.

Where Bettbox is the wrong choice

The clearest limitation is macOS distribution. The README states plainly that the project has not purchased an Apple developer certificate, and links to Apple's own support page about the resulting block. Every macOS user has to walk through the right-click, Open, confirm sequence on first launch, and again after updates. For an individual that is a minute of friction. For a managed fleet it is a policy problem, because you are asking users to override Gatekeeper by hand.

Second, the README does not document rollback, downgrade or configuration migration between versions. It documents a double configuration check, but not what the check rejects or how a bad configuration is reported. If you are deploying this to people who cannot debug a failed import themselves, that gap is the whole job.

Third, the project is not a router. If you want a headless client on a Linux box, or something you can drive entirely from a CLI, the README offers no CLI mode and no server deployment story. It is a GUI application with platform installers.

Finally, the README's own troubleshooting list names conflicting proxy software as a cause of errors. That is a real constraint: Bettbox expects to own the TUN interface, and running it alongside another proxy service is a supported failure mode, not a supported configuration.

How Bettbox differs from FlClash and from sing-box based clients

The nearest alternative is FlClash, the project Bettbox is built from. The difference is not the interface, which Bettbox inherits, but the maintenance model: FlClash is the upstream, and Bettbox is a rebuild of an early version with its own additions on top, including the compatible builds for older CPUs, the external override script hook, and the platform-specific behaviours the README lists. Choosing between them is choosing between following upstream and following this project's additions. The README does not say how far the two have diverged since the rebuild started.

A different kind of alternative is a sing-box based client, such as SFA, which the README lists among the projects it has used or referenced. The difference in approach is the core, not the shell: Mihomo and sing-box have separate configuration formats and separate rule models, so a subscription or configuration written for one does not move to the other unchanged. If your configuration is already Mihomo-shaped, that alone keeps you in this family. The README also lists Zashboard, CMFA, Sparkle, HUSI and V2rayN as related or referenced projects, which gives you a reasonable shortlist to compare against, though the README does not compare them feature by feature.

Licence, maintenance and what upgrades cost you

Bettbox is GPL-3.0. If you redistribute it or ship a modified build, the licence's source and copyleft obligations apply, and the README's note about an open CI/CD process is a statement of intent rather than a description of what the pipeline does. This is a summary, not legal advice; read LICENSE and SIGNING-POLICY.md in the repository if redistribution is on your roadmap.

The maintenance signal is straightforward: the repository is not archived, and the last push was on 2026-09-22, with releases v1.19.2 on 2026-09-19 and v1.19.3-pre1 on 2026-09-22. The release cadence includes pre-release builds, so if you want stable versions, filter for the plain version numbers rather than the -pre tags.

Upgrade cost is concentrated in two places. On macOS, every update reintroduces the Gatekeeper prompt, so budget for that in any user instructions you write. On the core side, the README says the project follows the Mihomo mainline, which means configuration semantics can shift when upstream changes; the README does not describe a compatibility policy for older configurations, so a pinned version is the only guaranteed-stable option. The AUR packages are maintained by third parties, so their update timing is not the project's to control.

Editorial conclusion

Adopt Bettbox if you already run a Mihomo or Clash Meta configuration and want a GUI that covers desktop, Android and Android TV from one project, and you are comfortable installing from GitHub Releases or the bettbox-bin AUR package. Do not adopt it if you need a signed macOS application, a reproducible build pipeline you can audit end to end, or a client whose README documents its own internals; the README covers installation and features, not architecture. Before you commit, verify three things: that a build exists for your exact platform and architecture (including the Compatible variants for older CPUs), that your subscription link imports after a reset, and that no other proxy service is running, since the FAQ names conflicting proxy software as a cause of errors.

Frequently asked questions

Official sources

1. appshubcc/Bettbox on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases