Portable Mode Installation
Relevant source files
The following files were used as context for generating this wiki page:
Portable Mode allows Zephyr to run without a standard system installation. It stores all data, including configurations, subscriptions, and the Mihomo core, within the program directory instead of system-defined application data folders. This mode is suitable for use on removable media like USB drives or for maintaining independent environments across multiple devices.
Sources: PORTABLE.md:3-5, README_en.md:144-146
Overview and Logic
Zephyr determines its operational mode by checking for a specific marker file. If the file .portable exists in the same directory as the executable, the application enters Portable Mode. In this state, the backend redirects all I/O operations from standard system paths (e.g., %AppData% on Windows or ~/.config on Linux) to the local directory.
Operational Flow
The following diagram illustrates how Zephyr chooses its data storage path during initialization:
The application checks for the .portable marker to define the root directory for all subsequent file operations.
Sources: PORTABLE.md:46-48, FEATURES.md:43-45
Directory Structure
In Portable Mode, the application expects and maintains a specific file structure within its root folder. This ensures that all components, from the proxy core to encrypted keys, remain self-contained.
| File / Folder | Description |
|---|---|
Zephyr.exe / .AppImage | The main application executable. |
.portable | The marker file that enables Portable Mode. |
core/ | Contains the Mihomo core binary and GeoIP/GeoSite databases. |
profiles/ | Stores YAML subscription and proxy configuration files. |
prism/ | Contains Prism engine rules and library data. |
settings.json | The main application configuration file. |
.machine_key | The machine-bound encryption key for sensitive data. |
Sources: PORTABLE.md:20-30, PORTABLE.md:41-45
Installation and Migration
Standard Setup
- Download the portable archive (
.zipfor Windows,.tar.gzfor Linux) from the releases page. - Extract the contents to the desired directory.
- Ensure the
.portablefile is present in the extracted folder. - Run the executable.
Sources: PORTABLE.md:14-18, README_en.md:139-142
Migrating from Installed Version
You can migrate existing data from a standard installation to a portable directory by copying files from the system paths:
- Windows Source:
%AppData%\com.zephyr.desktop\ - Linux Source:
~/.config/com.zephyr.desktop/
Copy the profiles/ and prism/ folders, along with settings.json, into the portable folder containing the .portable marker.
Sources: PORTABLE.md:52-59
Feature Comparison and Limitations
Portable Mode lacks certain features that require deep system integration, such as automatic updates for the client and startup persistence.
| Feature | Portable Mode | Installed Mode |
|---|---|---|
| Data Location | Program Directory | System AppData |
| Auto-start on Boot | ❌ Not Supported | ✅ Supported |
| In-client Updates | ❌ Manual Only | ✅ Supported |
| System Proxy | ✅ Supported | ✅ Supported |
| TUN Mode | ✅ Supported | ✅ Supported |
Sources: PORTABLE.md:32-40, README_en.md:146-148
Technical Constraints
- WebView2 Requirement: On Windows, the portable version still requires the Microsoft Edge WebView2 Runtime to be installed on the host system.
- Path Restrictions: Executables should not be placed in paths containing Chinese characters or spaces, as this may interfere with the Mihomo core process.
- I/O Performance: Using Portable Mode on low-speed USB drives may degrade performance due to frequent writes to
cache.dbby the proxy core.
Sources: PORTABLE.md:63-71, apps/desktop/src/main.js:465-470
Summary
Portable Mode provides a self-contained environment for Zephyr by redirecting data storage to the local program directory via the .portable marker. While it offers high portability and multi-device compatibility, users must manually manage client updates and lack native auto-start capabilities.
Sources: PORTABLE.md:3-5, FEATURES.md:43-45