Stelliberty and the shape of a desktop proxy client

An Avalonia shell over a Rust core

Stelliberty is a cross platform desktop proxy client for Windows, Linux and macOS, and the description of what it does is short: it imports Clash standard and Base64 subscriptions, starts quickly and uses little resources, and on Windows and macOS it offers platform level frosted window effects with a simple native look.

The stack is what makes it cross platform in a way that is not just about packaging. The interface is Avalonia, and the badges show .NET 11 as the runtime, with Windows, Linux and macOS all listed. Underneath, the repository carries a Rust workspace, and the topics list both csharp and rust, so this is a managed application with a native core rather than a managed application with a native helper.

The functional centre of the project is configuration compatibility. The README states that the config format is fully compatible with Clash Meta and points to the mihomo documentation for details. That single sentence decides who the project is for. Anyone whose proxy configuration is already a Clash or mihomo configuration can use it as is, and anyone whose configuration is in another format, an arbitrary JSON schema of their own, is outside what this client understands.

The audience is therefore users who already have a working Clash Meta style configuration and want it in a desktop application with a proper interface, and developers who want to work on a client for that configuration format.

The tray owns the runtime, the window is disposable

The architecture section is the most technical part of the README and the most useful, because it explains how the application behaves rather than how it is organised in a diagram.

The application is split into modular layers with Clean Architecture and MVVM, and it runs two processes. A persistent tray host owns the core lifecycle and the background tasks, and an on demand UI host runs the Avalonia windows and the UI platform services. The directory listing in the README names the projects:

src/Stelliberty.Tray            Persistent tray host, core lifecycle, background tasks
src/Stelliberty.Desktop         On-demand Avalonia UI host, windows, UI 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, IPC transport and clients
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

The public entry point, stelliberty.exe on Windows, owns the tray, the core runtime, the system proxy, service mode, the global shortcuts and the background scheduling, and it launches data/deps/stelliberty_ui.exe through an authenticated session when a window is actually needed. Other platforms use the corresponding executable names without the .exe extension.

The window lifecycle is then a deliberate design choice rather than an accident. Opening the window again reuses the active UI session, and by default hiding to the tray keeps the UI process alive. Lightweight Mode releases the UI process when it is hidden and creates a new session when it is reopened, and the background runtime continues either way. Full application exit is coordinated by the tray, and startup integration, installers and elevated restarts all go through the tray entry point.

The dependency rules are written as prohibitions

The architecture section states the dependency directions, and then states what must never happen, which is the more useful half.

The allowed directions are Desktop to Presentation to Application to Domain, and Tray to Application to Domain. Infrastructure and Native implement interfaces that Application defines, and Application has no dependency on the desktop, on Avalonia, or on the FFI details. The prohibitions that follow are specific and testable: views may not access databases, the file system or the Rust FFI directly; ViewModels may not hold platform APIs, file paths or window lifecycle details; the Domain layer may not depend on Avalonia, databases, networking, logging or config files; and Rust crates may not be aware of C#, Avalonia or the window lifecycle.

That last prohibition is the interesting one. In a mixed C# and Rust codebase, the usual failure mode is a slow leak where native code starts making decisions about the UI, and once that happens the layers stop being boundaries and become suggestions. Writing the rule down, in the README, in the form of a thing that must not happen, is the cheapest possible defence against it.

The practical consequence for a contributor is that the layering is not negotiable in review. A view that wants to read a config file has to go through an Application interface, and a native crate that wants to know whether a window is open has to be given that information from the managed side. It is more ceremony than a small utility needs, and it is exactly the ceremony a codebase that mixes a UI framework with native code needs.

Rust lints that ban unwrap and panic

The Rust workspace configuration is in the Cargo manifest, and the lints are stricter than a default.

The workspace has three members, native/hub, native/service and native/xtask, and the clippy lints deny several common shortcuts outright:

[workspace.lints.clippy]
unwrap_used = "deny"
expect_used = "deny"
panic = "deny"
todo = "deny"
unimplemented = "deny"
indexing_slicing = "deny"

Deny is the important word, because a warn level would be advisory and a deny level breaks the build. Since these crates hold config parsing, capabilities and service mode, a panic in a native component is a crash of the whole application, and a panic in the service mode is a crash of a privileged helper, so the ban is well placed.

The release profile is tuned the same way, and the opt level is worth noting:

[profile.release]
panic = "unwind"
strip = "symbols"
lto = true
codegen-units = 1
opt-level = "z"

Optimising for size, with link time optimisation on, a single codegen unit and stripped symbols. That is the profile of a client that wants to feel light on startup and small on disk, which matches the README's claim that it starts quickly and uses little resources.

The one exception is explicit. unsafe operations inside unsafe functions are denied, and the manifest allows linker messages because linking a DLL with exports on MSVC always prints import library generation messages, which the comment says have no warning value. That is a small, human decision inside an otherwise strict policy, and it tells you the policy is applied deliberately rather than by copying a template.

Installation is a table of packages, and the runtime is a dependency

The installation section is a table rather than a paragraph, and it covers the platforms and the shapes a package takes.

For Windows on x64 or arm64, the recommended artefact is an installer with the setup.exe suffix, with a portable zip as the alternative. For Linux on x64 or arm64, the recommendation is an AppImage, with a zip, a deb, an rpm and a pkg.tar.zst as alternatives. For macOS on x64 or arm64, the recommendation is a dmg with a pkg as the alternative. The system requirements are listed next: Windows 10 (1809 or later) or 11, a glibc desktop with fontconfig and X11 on Linux, and macOS 22 or later on Intel or Apple Silicon.

The Linux requirements are the one to check, because fontconfig and X11 are not implied by a generic Linux. A minimal server install without them will not run the client, which is a reasonable constraint for a desktop application and an awkward one for a headless box.

The other dependency is the.NET 11 runtime, and the FAQ explains the symptom. If the app will not start or appears unresponsive after installation, the answer is to install the.NET 11 Runtime and start it again, with a download link and, for Arch Linux and derivatives, an AUR package for the preview runtime. Since the release build does not appear to be self contained, a machine without the runtime simply will not run the client, and for a client you install on several machines that is the first thing to plan for.

System proxy or virtual network, and who needs elevation

The FAQ answers the question that decides whether a client works on your machine, which is how the traffic is captured.

The system proxy mode routes applications that honour the system proxy setting, and it does not require administrator privileges. The virtual network mode creates a virtual network adapter and takes over traffic at the adapter level, which does require administrator privileges, and the documentation advises installing service mode on first use to avoid repeated UAC prompts.

That distinction has a consequence worth spelling out. The virtual network mode covers traffic that never consults a proxy setting, which is why the README recommends it for full device traffic coverage. The UWP loopback exemption toggle exists because UWP apps on Windows are blocked from accessing the local proxy loopback address by default, and the toggle removes that restriction. The documentation is careful to add that virtual network mode is unaffected, since it never goes through loopback.

The user flow is short. Launch the app and import your subscription or config file, select nodes on the Nodes page, set an outbound mode on the Home page, where the choices are Rule, Global and Direct, and then enable system proxy or virtual network mode for full device traffic coverage.

That Rule, Global and Direct choice is the familiar Clash one, and it maps to how the configuration is interpreted, which is the point of the Clash Meta compatibility.

A custom licence, beta builds and a stable branch

The licence is the first thing to sort out, and the repository's own metadata records it as something GitHub cannot classify, with a LICENSE file in the tree. For a project that ships installers and package files for three platforms, the terms of that file decide what an organisation can do with the client, and the metadata being unclassifiable means a reader cannot infer the answer from a badge.

The release picture is busy in a way worth understanding. The default branch is stable, and the recent releases are v2.0.39-beta1 on 2026-10-15, v2.0.38 on 2026-10-14 and v2.0.37 on 2026-09-30, so there is a beta build published alongside the numbered releases, and a release roughly every two weeks. The repository is not archived, and the last push was on 2026-10-18, three days after the newest tag.

The project name in the README is Stelliberty Remake, and the repository is under the Kindness-Kismet organisation, with the README offering an English version and a Simplified Chinese one under.github/docs. The Development Guide is extensive, with sections on C# conventions, Rust conventions, Avalonia and MVVM, control test ids, and build and test, which is the sign of a project that expects outside contributions and wants them to land in a consistent shape.

For an adopter the practical reading is that this is an actively developed client with a fast release cadence, a documented architecture that a contributor can follow, and a licence that has to be read rather than assumed.

Editorial conclusion

Adopt Stelliberty if you want a desktop proxy client for a Clash Meta compatible configuration with a native look, a tray resident runtime and a documented split between the system proxy and virtual network modes. Do not adopt it as a headless router service or as a client for a non Clash configuration format, since the compatibility it advertises is specifically Clash Meta. Verify three things first: which mode you need, because virtual network mode creates a virtual adapter and needs administrator rights while the system proxy does not, that the.NET 11 runtime is present on the machines you install it on, since a missing runtime is the documented reason the app will not start, and which licence terms apply, because the repository is published under a custom licence that GitHub cannot classify. The last push was on 2026-10-18 and the newest release is v2.0.39-beta1 from 2026-10-15.

Frequently asked questions

Official sources

1. Issues
2. Kindness-Kismet/stelliberty on GitHub
3. Project website
4. README
5. Releases