• Windows: Windows 10/11 (x64 / arm64)
• Linux: Mainstream distributions (x64 / arm64)
• macOS: Experimental

⚠️ Platform Status: Fully tested on Windows and Linux. macOS support is experimental and may have incomplete functionality.

• Stable Version: Releases
• Beta Version: Pre-releases (latest features)

1. Download the .zip file from the release page.
2. Extract to your desired location (e.g., D:\Stelliberty).
3. Run stelliberty.exe directly from the extracted folder.
4. ✅ No installation required, fully portable.

1. Download the .exe installer from the release page.
2. Run the installer and follow the setup wizard.
3. Choose an installation location (see restrictions below).
4. Launch the application from the desktop shortcut.
5. ✅ Includes uninstaller and desktop shortcut.

The installer enforces path restrictions for security and stability:

• System Drive (Usually C:):
  • ✅ Allowed: %LOCALAPPDATA%\Programs\* (e.g., C:\Users\YourName\AppData\Local\Programs\Stelliberty).
  • ❌ Prohibited: System drive root and all other paths.
• Other Drives (D:, E:, etc.):
  • ✅ No restrictions. Install anywhere, including root directories (e.g., D:\, E:\Stelliberty).

💡 Recommendation: For the best experience, install to a non-system drive (e.g., D:\Stelliberty) to avoid permission issues. The default path %LOCALAPPDATA%\Programs\Stelliberty is recommended for most users.

Supported architectures: x86_64, aarch64

• yay: yay -S stelliberty-bin
• paru: paru -S stelliberty-bin

AUR Package: stelliberty-bin

1. Download the .zip file for your architecture (amd64 or arm64).
2. Extract it to your desired location (e.g., ~/Stelliberty).
3. Important: Grant permissions: chmod 777 -R ./stelliberty.
4. Run ./stelliberty from the extracted directory.
5. ✅ Ready to use.

If you encounter port conflicts, run Command Prompt as Administrator:

1. Find Process: netstat -ano | findstr :<port_number>
2. Kill Process: taskkill /F /PID <process_id>

• Path Requirements: The path should not contain special characters (except spaces) or non-ASCII characters.
• Installation Restrictions: Use the portable ZIP version if you need to install to a location not allowed by the EXE installer.

If the application fails to start, install the Visual C++ Runtimes: vcredist - Runtimes AIO.

If you encounter any issues:

1. Enable Application Logging in Settings → App Behavior
2. Reproduce the issue to generate logs
3. Find log files in the data directory under the application installation directory
4. Remove any sensitive/private information from the logs
5. Create an issue on GitHub and attach the sanitized log file
6. Describe the problem and steps to reproduce

Before building this project, ensure you have the following installed:

• Flutter SDK (latest stable version recommended, minimum 3.38)
• Rust toolchain (latest stable version recommended, minimum 1.91)
• Dart SDK (included with Flutter)

📖 This guide assumes you are familiar with Flutter and Rust development. Installation instructions for these tools are not covered here.

The prebuild script requires additional Dart packages:

cd scripts && dart pub get && cd ..

Install the Rust-Flutter bridge tool globally:

cargo install rinf_cli

flutter pub get

After installing dependencies, generate Rust-Flutter bindings and i18n translations:

# Generate Rust-Flutter bridge code
rinf gen

# Generate i18n translation files
dart run slang

💡 Important: These generation steps are required before building the project for the first time.

Always run the prebuild script before building the project:

dart run scripts/prebuild.dart

Prebuild script parameters:

# Show help
dart run scripts/prebuild.dart --help

# Install platform packaging tools (Windows: Inno Setup, Linux: dpkg/rpm/appimagetool)
dart run scripts/prebuild.dart --installer

# Android support (not implemented yet)
dart run scripts/prebuild.dart --android

What does prebuild do?

1. ✅ Cleans asset directories (preserves test/ folder)
2. ✅ Compiles stelliberty-service (desktop service executable)
3. ✅ Copies platform-specific tray icons
4. ✅ Downloads latest Mihomo core binary
5. ✅ Downloads GeoIP/GeoSite data files

Use the build script to compile and package:

# Show help
dart run scripts/build.dart --help

# Build Release version for current platform (default: ZIP only)
dart run scripts/build.dart

# Build with Debug version too
dart run scripts/build.dart --with-debug

# Build with installer package (Windows: ZIP + EXE, Linux: ZIP + DEB/RPM/AppImage)
dart run scripts/build.dart --with-installer

# Build installer only, no ZIP (Windows: EXE, Linux: DEB/RPM/AppImage)
dart run scripts/build.dart --installer-only

# Full build (Release + Debug, with installer)
dart run scripts/build.dart --with-debug --with-installer

# Clean build
dart run scripts/build.dart --clean

# Build Android APK (not supported yet)
dart run scripts/build.dart --android

Build script parameters:

Output location:

Built packages will be in build/packages/

⚠️ Platform Support Status:

• ✅ Windows: Fully tested and supported
• ✅ Linux: Fully tested and supported
• ⚠️ macOS: Core functionality works, but system integration is experimental
• ❌ Android: Not implemented yet

⚠️ Unsupported Parameters:

• --android: Android platform is not adapted yet

After modifying Rust signal structs (with signal attributes):

rinf gen

📖 Rinf uses signal attributes on Rust structs to define messages, not .proto files. See Rinf documentation for details.

After modifying translation files in lib/i18n/strings/:

dart run slang

# Run prebuild first
dart run scripts/prebuild.dart

# Start development
flutter run

For developers, the project includes a test framework for isolated feature testing:

# Run override rule test (supports YAML or JS rules)
flutter run --dart-define=TEST_TYPE=override

# Run IPC API test
flutter run --dart-define=TEST_TYPE=ipc-api

Required test files in assets/test/:

• For override test:

  assets/test/
  ├── config/
  │   └── test.yaml          # Base configuration file for testing
  ├── override/
  │   ├── your_script.js     # JS override script
  │   └── your_rules.yaml    # YAML override rules
  └── output/
      └── final.yaml         # Expected final output after applying overrides
  

• For ipc-api test:

  Note: It is recommended to run the pre-build script (dart run scripts/prebuild.dart) before this test to download the necessary resources.

  assets/test/
  └── config/
      └── test.yaml          # Base configuration file for testing
  

💡 Note: Test mode is only available in Debug builds and automatically disabled in Release mode.

Test implementations: lib/dev_test/ (override_test.dart, ipc_api_test.dart)