Zephyr: a Tauri desktop client for the Mihomo proxy core

A desktop client for a proxy core it does not own

Zephyr is a GUI for Mihomo, the proxy core also known as Clash Meta. The architecture table in the README makes the split explicit: Tauri v2 provides the desktop shell, Rust 1.92 or later handles IPC, system integration, core management and the security boundary, the frontend is plain JavaScript with no framework dependency, UnoCSS presetWind4 does the styling, and CodeMirror 6 provides the editor with Prism DSL highlighting and completion.

That last combination is the interesting part of the design. Most desktop clients in this category are Electron applications, where the interface is a browser runtime with a Node process attached. A Tauri client uses the system webview instead, which is why the app can destroy the WebView when the window closes and keep only the system tray running, in a mode the README calls lightweight mode and locates at Settings, General, Lightweight Mode.

The core capabilities are the expected ones for a Mihomo client: starting, stopping and restarting the core, creating, editing and switching between YAML configurations, importing subscriptions by URL, by file or by drag and drop with automatic Base64 decoding, switching between rule, global and direct proxy modes, managing the native system proxy on Windows, macOS and Linux, enabling TUN mode for system level proxying, and a live connection list with per connection closing, up and down speed figures and history trends.

The interesting capability is Prism Engine, which is where Zephyr departs from being a front end.

Five steps from download to proxied traffic

The quick start in the README is a five step sequence, and it is worth reading closely because the order encodes the design. You download the latest version from the GitHub Releases page, run the installer or unzip the portable build, import a subscription by URL or by file, choose a proxy node from the list, and then switch on either the system proxy or TUN mode. Only after that last step is your traffic routed through the selected node.

Distribution comes in two shapes, and the difference is not cosmetic. The Full package contains the Mihomo core along with the GeoIP and GeoSite data, and the README recommends it for a first install or for offline use. The Lite package is smaller and does not include the core, which makes sense if you already have a core on the machine or if you never enable proxying at all.

The platform requirements are spelled out. Windows needs version 10 1809 or later on x64 or ARM64, macOS needs 10.13 High Sierra or later on x64 or ARM64 including Apple Silicon, and Linux needs glibc 2.31 or later, which the README equates to Ubuntu 20.04, Debian 11 and Fedora 34 or newer. The hardware figures given are around 300MB of memory and about 50MB of disk for the full build.

For a portable deployment there is a separate PORTABLE.md document in the repository root, alongside the feature list in FEATURES.md and the override guide in override-system-guide.md.

Prism Engine: rule patches, failover and a QuickJS sandbox

Prism Engine is a rule engine built on the clash-prism-* crates, and the README describes it as enhancing Mihomo's configuration ability. The first piece is declarative rule patching: a .prism.yaml file supports $prepend, $append, $filter and $override directives plus __when__ conditions, so rules are edited as data rather than by rewriting YAML by hand.

The second piece is rule library management, with create, read, update and delete operations, grouping, import, automatic application and file watching. The third is smart node selection, scoring nodes with an EMA over latency, success rate and stability, with adaptive scheduling, and the fourth is failover, which switches nodes automatically when one fails and supports thresholds, cooldown and fallback policies.

The scripting part is the most interesting to review. The script sandbox is a QuickJS execution environment with explicit resource limits on time, memory, string length, loops and recursion. Plugins are discovered, loaded and given lifecycle hooks, with fine grained permission control, and script execution is constrained by both resource and permission limits.

On top of that sits an override system with a Prism DSL and a JavaScript engine working in parallel, scoped globally or per configuration, with drag ordering and import and export, plus a persistent key value store. The result is a client that can rewrite its own configuration through code, which is exactly the capability that makes the security section worth reading.

The security table, and the row that disagrees with the build profile

The README presents a defence in depth table with one row per layer. Encryption binds to the machine, deriving a key from a hardware fingerprint to encrypt subscription metadata, with optional encryption of proxy configuration from version 2.3.7. Network protections include SSRF defence, where downloads of subscription and rule URLs are DNS validated first and redirects to internal addresses are blocked, and DNS leak prevention, where TUN mode injects dns-hijack so all DNS traffic goes to Mihomo.

Configuration handling removes dangerous YAML fields recursively and limits provider path traversal. IPC entry points validate length, format and UTF-8 safety, and there is dual rate limiting, a fixed cooldown for ordinary commands and a sliding window for Prism commands. File handling covers safe permissions, UUID temporary files, archive path traversal protection, symlink rejection and archive bomb detection. Updates are checked with SHA256 and Minisign Ed25519 signature verification, restricted to trusted hosts, applied atomically and rolled back automatically. Deep link entry is limited to the clash:// protocol and URL scheme, and the build section mentions a content security policy that restricts script and connection sources, with LTO, strip and panic=abort enabled for releases.

That last row is where the documentation and the code disagree. The release profile in the workspace Cargo.toml sets panic = "unwind" rather than abort, so the claim about panic=abort in release builds does not match the checked in profile. There is a release-small profile with opt-level = "z" for size, inheriting the release settings, which means the two profiles share that panic setting. Small inconsistencies like this are exactly what an audit of a client that handles your traffic should surface.

The README also carries a disclosure that deserves to be read rather than skimmed: the whole project content, including that text, was generated by AI, security measures are in place, but security, stability and performance should not be treated as fully validated, and users are asked to assess the risk themselves.

System integration and TCP tuning across three operating systems

Beyond proxying, the client integrates with the operating system. There is a system tray status icon with a quick menu, global hotkeys for waking the window and toggling the system proxy, TUN and proxy mode, deep link subscription import through the clash:// protocol, Windows UWP loopback exemption, and update handling for the Mihomo core, the GeoIP and GeoSite data and the client itself. Autostart at login, system notifications and opening the configuration directory are also listed.

The network optimisation section describes a three layer system. The first layer is Mihomo configuration defaults such as tcp-concurrent, keep-alive and fake-ip persistence. The second is operating system TCP tuning, with Fast Open, ECN and buffer settings. The third is DNS optimisation. The control for this is separate from the main interface, with manual Apply, Revert and Status actions, and on Linux the settings are persisted into /etc/sysctl.d/.

The manual apply step is a deliberate choice. Changes to system wide networking parameters that require elevated privileges are the kind of thing that goes wrong quietly, so making the operator trigger them and then look at a status readout is a reasonable trade for a tool that rewrites operating system configuration.

The interface itself is described in detail: a transparent frameless window with a custom title bar, UI scaling from 1x to 1.5x for different resolutions, virtual scrolling logs with level filtering and regular expression search, node cards with 3D interaction effects, a theme system with presets and custom colours, and internationalisation across 14 languages with right to left layout support and CLDR plural rule validation.

A pnpm and Cargo monorepo with strict lint rules

The repository is a monorepo with a pnpm workspace over apps/* and packages/*, alongside a Cargo workspace. The root package.json names the project zephyr, marks it private, pins the package manager to pnpm 10.12.1 and requires Node 20.18.1 or later. The scripts show the shape of the build:

  "scripts": {
    "dev": "pnpm --filter @zephyr/desktop tauri dev",
    "build": "pnpm --filter @zephyr/desktop build:css && pnpm --filter @zephyr/desktop tauri build",
    "build:css": "pnpm --filter @zephyr/desktop build:css",
    "lint": "pnpm -r lint",
    "test": "pnpm -r test",
    "typecheck": "pnpm -r typecheck",
    "tauri": "pnpm --filter @zephyr/desktop tauri",
    "check:i18n": "node packages/scripts/check-i18n.js",
    "prepare": "husky"
  },

The Cargo side is a workspace of three members, the desktop Tauri crate plus crates/core and crates/core-ffi:

[workspace]
members = ["apps/desktop/src-tauri", "crates/core", "crates/core-ffi"]
resolver = "2"

The workspace lints are where the project's engineering standards are written down. The clippy configuration denies correctness, suspicious patterns, panic, unimplemented, todo, unwrap_used, expect_used, dbg_macro, indexing_slicing, a set of cast truncations, undocumented unsafe blocks and map_err_ignore, then a second group covers concurrency and memory safety with rc_mutex, clone_on_ref_ptr, mutex_atomic, await_holding_lock and unused_async among others. The comment above them explains the intent, namely that every member crate inherits through lints workspace = true so that a local cargo clippy run and CI use exactly the same rule set.

The repository root shows the supporting infrastructure: deny.toml for cargo-deny, osv-scanner.toml, a Semgrep configuration, a Clippy configuration, husky hooks with a pre-commit config, a rust-toolchain.toml, renovate.json for dependency updates, codecov.yml, an AUDIT_REPORT.md, a CODE_SIGNING_POLICY.md, SECURITY.md and a NOTICE file.

Release cadence, licence and what the badges actually cover

The project moves quickly. The recent releases are v2.4.4 on 2026-08-22, v2.4.3 on 2026-08-08 and v2.4.2 on 2026-07-22, and the last push to the repository was on 2026-10-20, so the gap between the newest tag and the branch head is a couple of months. That is a normal cadence for a desktop client that tracks an upstream core.

The licence is MIT, which keeps the legal side simple for anyone redistributing a build, subject to the usual notice requirement. The README carries an OpenSSF Best Practices badge alongside security badges for CodeQL, Semgrep, cargo-deny and Clippy, plus separate Rust and JavaScript test status badges, and the repository holds a GitHub Actions workflow for those.

What the badges do not tell you is whether the client behaves correctly with your subscription provider, whether the rule engine handles your particular configuration, or whether the TUN mode works on your kernel and network. Those need testing on your own machine, and the AI generated disclosure in the README is the reason to do it rather than skip it.

The project also links a landing page in the repository as landing.html and a documentation site at the project homepage, with the full feature list in FEATURES.md, the override system guide in override-system-guide.md, the portable build notes in PORTABLE.md, contribution guidance in CONTRIBUTING.md and the security policy in SECURITY.md.

Editorial conclusion

Adopt Zephyr if you already run the Mihomo core and want a desktop client with a rule patching engine, a sandboxed script layer and a lightweight memory footprint, and you are comfortable auditing a client that handles your traffic. Do not adopt it as a trusted proxy for sensitive work without reading the security documentation first, because the project states its own content is AI generated and its security, stability and performance are not fully validated. Verify first that the release you install is the Full build if you expect the core and the GeoIP and GeoSite data to be bundled, and that the update path you rely on checks SHA256 and Minisign signatures, since the Lite build ships without the core.

Frequently asked questions

Official sources

1. Juwan-Hwang/Zephyr on GitHub
2. License: MIT
3. Project website
4. README
5. Releases