Stelliberty Remake

Home · Light	Home · Dark

Settings · Light	Settings · Dark

Stelliberty is a cross-platform desktop proxy client for Windows, Linux, and macOS.

Import Clash-standard and Base64 subscriptions. It starts quickly and uses little resources. On Windows and macOS, platform-level frosted window effects are available, with a simple native look.

It also ships with a large set of simulation and prewritten test flows that walk through real user actions, so ongoing maintenance stays easier.

Navigation

• Installation
• Quick Start
• FAQ
• Development Guide
  • Architecture
  • C# Conventions
  • Rust Conventions
  • Avalonia / MVVM
  • Control Test IDs
  • Build & Test
• PR Guidelines
• License
• Friends

📦 Installation

_{↑ Back to Navigation}

Download

Grab the package for your platform from the Releases page:

System Requirements

🚀 Quick Start

_{↑ Back to Navigation}

1. Launch the app and import your subscription or config file.
2. Select nodes on the Nodes page; set an outbound mode on the Home page (Rule / Global / Direct).
3. Enable system proxy or virtual network mode for full-device traffic coverage.

Config format is fully compatible with Clash Meta — see the mihomo documentation for details.

❓ FAQ

_{↑ Back to Navigation}

App will not start or appears unresponsive after installation?

Install the .NET 11 Runtime, then start Stelliberty again:

• General: Microsoft download
• Arch Linux and derivatives: AUR package dotnet-core-preview-bin

UWP Loopback & Administrator Privileges

UWP apps on Windows (e.g. Microsoft Store apps) are blocked from accessing the local proxy loopback address by default. Stelliberty provides a UWP loopback exemption toggle to remove this restriction.

Notes:

• Administrator privileges are usually not required; the system only prompts for elevation when permission is insufficient.
• Virtual network mode is unaffected — it takes over traffic at the adapter level and never goes through loopback.
• If you use system proxy mode and want UWP apps (such as Microsoft Store apps) to go through the proxy, turn this option on.

Do system proxy / virtual network require admin?

• System proxy: No administrator privileges required.
• Virtual network: Creating a virtual network adapter requires administrator privileges. Install service mode on first use to avoid repeated UAC prompts.
• UWP loopback exemption (Windows): usually no administrator privileges required; elevate only if permission is insufficient.

🛠 Development Guide

_{↑ Back to Navigation}

Prerequisites

Architecture

Modular monolith + Clean Architecture + MVVM.

src/Stelliberty.Desktop         Avalonia host, windows, platform services
src/Stelliberty.Presentation    ViewModels, UI state, command bindings
src/Stelliberty.Application     Use cases, service & capability interfaces
src/Stelliberty.Domain          Entities, value objects, domain rules
src/Stelliberty.Infrastructure  File system, persistence, external services
src/Stelliberty.Native          C# wrappers over the native FFI layer
native/hub                      Native library: config override, parsing, capabilities
native/service                  Service mode
scripts/                        build.py · prebuild.py · test.py

Dependency direction: Desktop → Presentation → Application → Domain

Infrastructure and Native implement interfaces defined by Application; Application has no dependency on desktop, Avalonia, or FFI details.

Prohibited:

• Views accessing databases, file system, or Rust FFI directly
• ViewModels holding platform APIs, file paths, or window lifecycle details
• Domain depending on Avalonia, databases, networking, logging, or config files
• Rust crates being aware of C#, Avalonia, or window lifecycle

C# Conventions

Naming

• Types, enums, interfaces, properties, methods: PascalCase
• Local variables, parameters, private instance fields: camelCase; private readonly instance fields: _camelCase
• Interfaces use I prefix only when expressing an abstract capability
• Async methods end with Async; cancellable operations take CancellationToken
• Booleans use affirmative semantics: IsEnabled, CanSave, HasSelection

Practices

• Use var when the type is obvious from the right side; explicit types otherwise
• Use result objects for complex state (SaveResult, ParseResult), not bare bool
• Guard clauses at system boundaries; no excessive defensiveness for impossible internal states
• Never use .Result or .Wait() to block async tasks
• Comments state intent, constraints, and pitfalls; concise, max 2 lines per block

Rust Conventions

Naming

• crate, module, function, variable: snake_case
• type, trait, enum, struct: PascalCase
• const, static: SCREAMING_SNAKE_CASE

Practices

• Immutable by default, prefer borrowing
• Use Result<T, E> and ? for error propagation; no unwrap() for recoverable errors
• unsafe is prohibited by default; when necessary, minimize scope and comment the safety precondition
• No mod.rs — use Rust 2018+ same-name file style
• FFI function naming: hub_<capability>_<action>

Capability module structure

native/hub/src/
├── lib.rs              // module declarations only
├── ffi.rs              // root FFI aggregation
├── capabilities/       // one file per capability
├── infra/              // HTTP client, runtime, etc.
└── util/               // pure utility functions

Avalonia / MVVM

• Views handle display and binding only — no business logic
• ViewModels expose immutable or observable state; never manipulate control instances directly
• UI thread handles UI updates only; heavy work goes to background threads
• Platform capabilities (windows, tray, permissions) are implemented in the host layer and exposed via Application interfaces

Control Test IDs

All interactive controls must have AutomationProperties.AutomationId set.

• Format: PageOrArea.SemanticName, e.g. Main.SaveButton, Library.SearchBox
• IDs are stable — they don't change with display text, language, or layout
• No duplicates within the same View
• No random numbers, indices, or visual-position naming

Build & Test

Development workflow: prebuild → test → build.

1. Prebuild

Downloads the core binary, GeoIP data, and fonts; builds the service-mode binary.

python scripts/prebuild.py

2. Test

python scripts/test.py --all

Rust scenario tests:

C# business tests:

3. Build

python scripts/build.py

Full release build:

python scripts/prebuild.py
python scripts/build.py --pack all

Formatting

dotnet format
cargo fmt

📋 PR Guidelines

_{↑ Back to Navigation}

Before submitting a Pull Request, confirm the following:

Requirements

Pull Requests must target beta. Direct Pull Requests to stable are prohibited; only the repository owner may promote the repository's beta branch to stable.

Debug Command Requirements

Debug commands are wrapped under src/Stelliberty.Desktop/Debug and invoked through the debug control port. When business logic changes, add or update the corresponding Debug/Commands/*.cs implementation.

Control ID Requirements

When adding clickable, input-capable, selectable, or state-assertable controls:

<Button AutomationProperties.AutomationId="Settings.SaveButton" />
<TextBox AutomationProperties.AutomationId="Subscription.UrlInput" />

Naming rule: PageOrArea.SemanticName — stable, unique, independent of visual layout.

📄 License

_{↑ Back to Navigation}

Open Source Commitment

This project is fully open source under the WTF License. Any derivative work based on this project must publish its complete corresponding source code and remain under the WTF License, whether it is distributed directly or provided as a network service.

Commercial Use Restrictions

This project and its derivative works must not be used for commercial purposes.

Branding and Identifiers

Derivative works must not retain any identifier associated with the original Stelliberty software, including but not limited to its name, logos, icons, product names, package names, application identifiers, and other branding.

Third-Party Components

Third-party components remain subject to their original licenses. See the WTF License for the complete terms and third-party project list.

🤝 Friends

_{↑ Back to Navigation}

• Telegram Updates — Project updates and release notices.
• LINUX DO — A friendly community for technology enthusiasts.