We have migrated to codeberg!

Husi is a non-professional and recreational proxy tool integration, aiming at promoting proxy customization.

In August 2025, Google announced that as of September 2026, it will no longer be possible to develop apps for the Android platform without first registering centrally with Google. This registration will involve:

• Paying a fee to Google
• Agreeing to Google’s Terms and Conditions
• Providing government identification
• Uploading evidence of the developer’s private signing key
• Listing all current and future application identifiers

As a free software, husi will never submit to Google. Visit Keep Android Open to defend the openness!

CONTRIBUTING

New here? You can use DeepWiki to known basic structure of husi and ask anything you want.

Is husi not in your language, or the translation is incorrect or incomplete? Get involved in the translations on our Weblate.

In Linux, you can build husi reproducibly for release version.

For this, you should use the same version of JDK, NDK as below. And Go version should as same as version.sh.

git clone https://codeberg.org/xchacha20-poly1305/husi.git --depth=1
cd husi/
./run lib source # Will help you to get submodules

Environment:

• These versions need to apply patch.

  Unfold

  1.22.5: Apply this patch to ${GOROOT}/src/runtime/cgocall.go

  1.23.0-1.23.3: Apply this patch to${GOROOT}. make patch_go1230

  1.23.4: Apply this patch to $(GOROOT). make patch_go1234

• Openjdk-21 (Later may OK, too.)

For Android:

make libcore_android

This will generate composeApp/libs/libcore.aar.

For desktop, build libcore for your host platform:

make libcore

This will generate composeApp/libs/libcore-desktop-<host-platform>-<host-arch>.jar.

Or for specific targets:

make libcore_desktop DESKTOP_TARGETS=linux/amd64,darwin/arm64

Common desktop targets:

• linux/amd64
• linux/arm64

For Linux targets, the build includes with_naive_outbound and requires a cronet-go checkout with the naiveproxy toolchain prepared. By default it is expected at $HOME/cronet-go; override with CRONET_GO_ROOT:

CRONET_GO_ROOT=/path/to/cronet-go make libcore

Desktop Gradle builds select composeApp/libs/libcore-desktop-<platform>-<arch>.jar automatically from the current os.name and os.arch.

You can override it explicitly:

./gradlew -p composeApp run -PdesktopTarget=linux/amd64

If the selected jar is missing, the build fails immediately.

If you run libcore/build.sh directly:

• --android: build Android only
• --desktop: build desktop only (default target: host)
• --android --desktop: build both
• no platform args: defaults to Android only

If anja is not in GOPATH, it will be automatically downloaded and compiled.

If you don't want to build it, you can download then in actions

If you don't want to use the same package name, you can run ./run rename target_name.

Environment:

• jdk-21
• ndk 29.0.14206865

If the environment variables $ANDROID_HOME and $ANDROID_NDK_HOME are not set, source buildScript/init/env_ndk.sh to set them:

source buildScript/init/env_ndk.sh

Then write the SDK path to local.properties:

echo "sdk.dir=${ANDROID_HOME}" > local.properties

Signing preparation (optional, it is recommended to sign after compilation): Replace release.keystore with your own keystore.

echo "KEYSTORE_PASS=" >> local.properties
echo "ALIAS_NAME=" >> local.properties
echo "ALIAS_PASS=" >> local.properties

Download geo resource files:

make assets

Generate open source license metadata:

./gradlew :composeApp:exportLibraryDefinitions

Compile the release version:

make apk

The APK file will be located in androidApp/build/outputs/apk.

Environment:

• jdk-21
• zig 0.15

Run the desktop application:

make desktop

Package a distributable for the current OS:

make desktop_uberjar

This now builds an uber JAR that runs on system Java (no bundled JRE/runtime image). Output directory:

composeApp/build/compose/jars/

Run it with system Java (JDK/JRE 21+):

java -jar composeApp/build/compose/jars/fr.husi-<platform>-<arch>-<version>.jar

Build Linux native packages (deb/rpm/pacman) with Java 21 dependency metadata:

make desktop_package_linux

This command still builds the uber jar first, then packages it with native Linux tooling. Required host tools: cc, dpkg-deb, rpmbuild, bsdtar, zstd. Default output directory:

composeApp/build/compose/packages/linux/

You can select target formats:

make desktop_package_linux LINUX_PACKAGE_FORMATS=deb,pacman

Installed launcher supports user config files:

• ~/.config/husi/desktop-java-opts.conf for JVM options
• ~/.config/husi/desktop-app-args.conf for application startup arguments

Linux native packages include a native launcher built with Zig from launcher/.

Build the launcher standalone:

make launcher

The default packaging flow runs make launcher first, then package-native.sh consumes that binary. Zig targets musl by default for static linking; no external C toolchain is needed. Package install scripts call setcap on the launcher so capabilities can be raised to ambient set before starting the JVM.

make plugin PLUGIN=<Plugin name>

Plugin name list:

• hysteria2
• juicity
• naive ( Deprecated. Build official repository directly, please. )
• mieru
• shadowquic

Wiki

GPL-3.0 or later

• SagerNet/sing-box
• shadowsocks/shadowsocks-android
• SagerNet/SagerNet
• XTLS/AnXray
• MatsuriDayo/NekoBoxForAndroid
• SagerNet/sing-box-for-android
• AntiNeko/CatBoxForAndroid
• MetaCubeX/ClashMetaForAndroid
• dyhkwong/Exclave
• chen08209/FlClash
• RikkaApps/RikkaX

Developing

• 

  JetBrains' powerful IDE.