System Proxy Management
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr manages native system proxy settings across Windows, macOS, and Linux platforms. The system configures the operating system to route network traffic through the Mihomo proxy core. It includes automated bypass for private networks and an ownership guard to detect and restore settings if tampered with by other applications.
Sources: FEATURES.md:14-15, apps/desktop/src-tauri/src/sys_proxy.rs
Architecture and Control Flow
The system proxy management operates through a multi-layered architecture involving the frontend UI, Tauri IPC commands, and platform-specific Rust implementations.
The diagram shows the flow from a user action in the UI to platform-specific system calls managed by Rust.
Sources: apps/desktop/src/ui/sysproxy.js:14-16, apps/desktop/src-tauri/src/sys_proxy.rs, packages/shared/src/index.js:58-64
Core Components
| Component | Responsibility |
|---|---|
sysproxy.js | Manages the UI state, event listeners, and calls IPC commands to toggle proxy settings. |
sys_proxy.rs | Implements the backend logic for enabling, disabling, and checking proxy status across platforms. |
Ownership Guard | Periodically verifies if Zephyr still controls the system proxy and restores it if external changes occur. |
Tray Integration | Updates the system tray icon and menu based on the current proxy status. |
Sources: apps/desktop/src/ui/sysproxy.js:1-10, apps/desktop/src-tauri/src/lib.rs:821-840, FEATURES.md:14-15
IPC Command Interface
The frontend communicates with the system proxy module using specific IPC commands defined in the shared constants.
This sequence illustrates the typical interaction when a user toggles the system proxy.
Sources: packages/shared/src/index.js:58-64, apps/desktop/src/ui/sysproxy.js:16-25
API Endpoints
| Command Name | Rust Function | Description |
|---|---|---|
enable_sysproxy | enable_sysproxy() | Configures OS settings to route traffic through the local proxy port. |
disable_sysproxy | disable_sysproxy() | Removes the system proxy configuration. |
get_sys_proxy | get_sys_proxy() | Queries the OS to check if the proxy is currently active. |
has_sysproxy_ownership | has_sysproxy_ownership() | Checks if Zephyr was the last application to set the proxy. |
restore_sys_proxy | restore_sys_proxy() | Re-applies Zephyr's proxy settings if tampered with. |
Sources: packages/shared/src/index.js:58-64, apps/desktop/src-tauri/src/lib.rs:1134-1138
Implementation Details
Frontend Reactive Binding
The application uses a centralized store (appStore) to manage the proxy state. UI components bind to the isSysProxyEnabled property.
const sysProxyToggle = document.getElementById('sys-proxy-toggle');
if (sysProxyToggle) {
bind(appStore, sysProxyToggle, 'isSysProxyEnabled', 'checked');
}
Sources: apps/desktop/src/main.js:134-137
Tray Status Integration
The system tray icon reflects the system proxy state. The get_tray_status command evaluates the hierarchy of proxy modes to determine the correct icon.
Environment Variable Copying
Zephyr provides a utility to copy proxy environment variables in various shell formats (bash, fish, cmd, powershell, nushell). Windows defaults to PowerShell, while other platforms default to Bash.
Sources: apps/desktop/src-tauri/src/lib.rs:271-277, FEATURES.md:16
Summary
System Proxy Management in Zephyr provides a cross-platform solution for routing OS traffic through the Mihomo core. It ensures high reliability through an ownership guard and integrates deeply with the system tray and reactive frontend store.
Sources: FEATURES.md:14-15, apps/desktop/src/main.js:142-143