Introduction to Zephyr
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr is a secure, lightweight, and modern cross-platform GUI client for the Mihomo (Clash Meta) proxy core. It utilizes a defense-in-depth security architecture combined with a minimalist aesthetic, developed using Rust for backend logic and native JavaScript for the frontend. The project prioritizes performance by avoiding heavy frontend frameworks and leveraging system-native WebViews via the Tauri v2 framework.
The system integrates advanced rule management through the Prism Engine, providing declarative rule patches, smart node selection, and a secure script sandbox. It supports diverse network modes including System Proxy and TUN mode, ensuring comprehensive traffic routing across Windows, macOS, and Linux environments.
Technical Architecture
Zephyr employs a four-layer architecture that separates user interface concerns from core proxy logic and system integration.
The diagram shows the top-down flow from the native JavaScript interface through the Tauri IPC bridge to the Rust logic and finally the proxy core.
Sources: README_en.md:204-215, landing.html:439-472
Component Stack
| Layer | Technology | Description |
|---|---|---|
| Desktop Framework | Tauri v2 | Manages window lifecycle and provides the Rust-to-JS bridge. |
| Backend | Rust 1.92+ | Handles IPC, system integration, security boundaries, and core management. |
| Frontend | Native JS | Zero-framework implementation using UnoCSS for styling and CodeMirror 6 for editing. |
| Rule Engine | Prism Engine | Provides $prepend, $append, and $filter capabilities for YAML configs. |
| Proxy Core | Mihomo | The underlying Clash Meta core performing network operations. |
Sources: README_en.md:162-175, landing.html:474-484
Security Design Principles
Zephyr implements 13 layers of defense-in-depth to protect user metadata and prevent network-based attacks.
Encryption and Data Protection
The system uses hardware fingerprint-derived keys to encrypt subscription metadata via AES-256-GCM. This ensures that metadata.json remains unreadable if moved to another device.
Sources: landing.html:362-366, README_en.md:104-106
Network Security and Sandboxing
- SSRF Protection: Validates DNS before downloading subscriptions or rules to block redirects to private IP addresses.
- DNS Leak Prevention: Automatically injects
dns-hijackin TUN mode to capture all system DNS traffic. - Script Sandboxing: Constrains Prism scripts within a QuickJS environment with strict CPU, memory, and recursion limits.
- IPC Validation: Validates length, format, and UTF-8 safety for all Inter-Process Communication command entry points.
Sources: README_en.md:107-113, SECURITY.md:179-183
This flowchart illustrates the security pipeline for subscription imports, from DNS validation to encrypted storage.
Sources: landing.html:354-366, README_en.md:107-111
System Initialization and Lifecycle
The application entry point in main.js orchestrates the startup sequence, ensuring the backend is ready before initializing the UI.
Bootstrap Sequence
- Backend Listener Initialization: Starts backend event listeners with a 3000ms timeout to ensure IPC availability.
- Core Initialization: Invokes
START_COREvia Rust backend. If TUN mode fails to start on macOS, it records the failure and retries without TUN. - Endpoint Configuration: Sets the Base URL and Secret for communication with the Mihomo RESTful API.
- Prism Engine Application: Compiles patches and populates rule annotations.
- Reactive Binding: Wires the
appStoreto DOM elements and system tray updates.
Sources: apps/desktop/src/main.js:101-140, apps/desktop/src/main.js:174-210
The sequence diagram details the synchronization between the frontend, the Rust bridge, and the Mihomo binary during startup.
Sources: apps/desktop/src/main.js:174-245
Feature Capabilities
Prism Engine Integration
The Prism Engine enhances standard Mihomo configurations through declarative patches.
- Declarative Patches: Supports
.prism.yamlwith operators like$prepend,$append, and__when__conditions. - Smart Selection: Uses EMA (Exponential Moving Average) scoring to select nodes based on latency and stability.
- Failover Strategies: Implements automatic node switching with configurable thresholds and cooldown periods.
Sources: README_en.md:88-98, README.md:92-102
Network Optimization
Zephyr provides a standalone UI for applying OS-level TCP tuning. This includes:
- TCP Fast Open and ECN (Explicit Congestion Notification).
- MTU tuning and buffer optimization.
- Linux persistence via
/etc/sysctl.d/.
Sources: README_en.md:131-135, landing.html:396-398
Development and Contribution
The project follows a standard GitHub fork-and-pull-request workflow.
Coding Standards
- Backend (Rust): Enforces 170 Clippy deny rules across correctness, security, and performance tiers. Tests must be added for all new functionality.
- Frontend (JS): Uses ESLint with a custom
no-unsanitizedrule to prevent unsafe HTML assignments. - CI/CD: Pipelines run
cargo clippy,cargo test, andpnpm linton every pull request.
Sources: CONTRIBUTING.md:27-56, CONTRIBUTING.md:85-92
Summary
Zephyr functions as a high-performance intermediary between the user and the Mihomo core. By utilizing Rust for critical system operations and a framework-less JavaScript frontend, it achieves a significant reduction in resource consumption—approximately 30MB of RAM—while maintaining advanced features like the Prism rule engine and 13-layer security defense. Its architecture ensures that network operations are isolated, metadata is encrypted, and system integration remains lightweight across all supported desktop platforms.