Stelliberty is a native Android proxy client based on Mishka, powered by mihomo, with a Jetpack Compose interface built on miuix.

Use Android VPN without root, or choose ROOT TUN and ROOT TPROXY for privileged traffic capture. Manage subscriptions, proxy groups, connections, and routing from one app.

• Installation
• Quick Start
• Features
• FAQ
• Development Guide
• Release Workflow
• Contributing
• License and Credits

_{↑ Back to Navigation}

Download an APK from the Releases page.

Android 12 or later is required. Choose arm64-v8a for current phones or x86_64 for devices and emulators with that architecture.

Stable and beta packages share the same application ID and signing key. Android checks the version code when installing an update; a beta of the next version may be newer than the current stable release.

_{↑ Back to Navigation}

1. Import a subscription URL, scan a QR code, or select a local configuration file.
2. Select the active subscription and choose nodes on the proxy page.
3. Choose Rule, Global, or Direct mode on the home page.
4. Start the proxy and approve the Android VPN permission. ROOT modes require root access instead.

For configuration options, see the mihomo documentation.

_{↑ Back to Navigation}

_{↑ Back to Navigation}

VPN mode works without root. ROOT TUN and ROOT TPROXY need root permission; TPROXY also requires support from the device kernel.

Configuration changes currently take effect by restarting the core. Rule, Global, and Direct describe routing behavior; they are separate from the tunnel mode.

No. Import your own subscription or configuration. The project supplies the client and its proxy core.

_{↑ Back to Navigation}

Android Gradle Plugin resolves the NDK and CMake used for native compilation. Android dependency coordinates and tool versions are maintained in libs.versions.toml.

Local builds and CI use the same portable Go setup, with archives verified against the official SHA256 checksums. Regular builds reuse the downloaded toolchain without checking the network. Run python scripts/prebuild.py --refresh-go to check for and install the latest stable release; a compiler version change also rebuilds the native core.

android/app/src/main/kotlin/com/stelliberty/android/
├── ui/           Compose screens, components, navigation, and themes
├── viewmodel/    Screen state and user actions
├── domain/       Models and repository interfaces
├── data/         Repositories, JSON stores, core API clients, and backup
├── platform/     Android integration and service control
└── service/      VPN, ROOT, subscriptions, and background services
android/app/src/main/cpp/                        JNI and process helpers
android/app/src/main/native/stelliberty_core/     Go core integration
third_party/                                    mihomo and scripta submodules
scripts/                                        Prebuild and build entry points

Screens receive dependencies through parameters. ViewModels depend on repository interfaces, and platform code owns Android-specific behavior. See AGENTS.md for project conventions.

git clone --recurse-submodules https://github.com/Kindness-Kismet/stelliberty_android.git
cd stelliberty_android
python scripts/prebuild.py
python scripts/build.py --dev

APKs are collected in build/apk/. Release signing uses KEYSTORE_PATH, KEYSTORE_PASS, KEY_ALIAS, and KEY_PASSWORD environment variables. An unsigned local release build must be signed before installation.

The repository uses a directory and extension allowlist. CI also rejects tracked files outside that allowlist, including files added with force. Downloaded launchers, JDKs, Go toolchains, GeoIP data, native binaries, caches, and temporary files stay outside Git. Collected Baseline Profiles remain tracked because a download cannot recreate them.

_{↑ Back to Navigation}

Both release channels build signed release APKs for all two supported 64-bit architectures. The local --dev flag selects a debug build and does not select the beta release channel.

Configure these repository Actions secrets before publishing:

Use the same key for both channels. APK uploads finish before a release becomes public. Stable releases use .github/CHANGELOG.md; beta releases list commits since the previous release baseline. The first beta uses the current changelog if no baseline exists.

The version-bump skill updates ProjectConfig.VERSION_NAME and rewrites the current changelog: English bullets first, a separator, then matching Simplified Chinese bullets. It does not raise dependency versions or publish releases on its own.

_{↑ Back to Navigation}

Submit changes to beta. Promote reviewed changes from beta to main for a stable release.

• Keep each change focused and preserve existing user data and configuration behavior.
• Maintain English, Simplified Chinese, and Traditional Chinese app strings together.
• Register new interactive controls in the debug test ID system.
• Run git diff --check and the relevant compile or package command.
• Read the matching project skill before changing UI, services, subscriptions, core APIs, or native builds.

_{↑ Back to Navigation}

This project is licensed under GPL-3.0. Third-party projects retain their own licenses.

• Mishka — direct upstream
• mihomo — proxy core; integrated through the mihomo submodule
• miuix — Compose UI components
• scripta — configuration editor submodule