MrMatin0/Aether

An Android client for censorship circumvention, powered by Aether, Psiphon, Xray, and Tor

English · فارسی · Downloads · Build workflow

Aether+ brings endpoint discovery, encrypted tunneling, and configurable routing to a native Kotlin and Jetpack Compose application. Use a device-wide VPN, connect individual proxy-aware applications, or combine supported cores when a single transport cannot reach the network.

About this repository: this is the MrMatin0/Aether Android fork, not the upstream command-line engine. It installs as Aether+ with application ID io.github.mrmatin0.aether, allowing it to coexist with builds using the upstream application ID. The Kotlin namespace remains studio.cluvex.aether.

The name Aether on its own is used throughout this README for the engine — the circumvention core at CluvexStudio/Aether — and for the chain modes built on it. The app is Aether+.

• Highlights
• Install and connect
• Connection modes
• Privacy and security
• Build from source
• Architecture
• Troubleshooting
• Contributing
• Documentation
• Credits and license

• Multiple transports: Smart Auto selection, MASQUE over HTTP/3 or HTTP/2, WireGuard, and nested WireGuard (gool) through the Aether engine.
• Adaptive endpoint discovery: Turbo, Precise, and Ultra scanning, plus a manually selected endpoint or custom IP ranges.
• Four connection cores: Aether, Psiphon, and Tor, available individually or in predefined chains, plus your own Xray server (VLESS, VMess, Trojan, Shadowsocks, Hysteria2, WireGuard, SOCKS) connecting first underneath Aether, Psiphon, and/or Tor, when the required binaries and assets are included.
• Device-wide or selective access: Android VpnService, proxy-only mode, per-app split tunneling, and routing controls.
• Connection controls: DNS and MTU settings, Smart DNS (one server, with the flag of the country it answers from), reconnection options, optional kill switch, IPv6 leak-protection setting, and advanced transport tuning.
• Everyday usability: English and Persian UI, RTL support, bundled Vazirmatn typography, live traffic information, session history, diagnostics, Quick Settings tile, and home-screen widget.
• Optional LAN sharing: expose SOCKS5 and HTTP proxies to other devices on a trusted local network.

Feature availability is not a guarantee of connectivity. Reachability depends on your network, the selected core, and the contents of the installed APK.

• Android 8.0 or newer (API 26+).
• An ARM64 (arm64-v8a) or 32-bit ARM (armeabi-v7a) device.
• Permission to install an APK from your chosen download application.
• Android VPN consent when using device-wide mode. Root is not required.

1. Open this fork's Releases page. Prefer a tagged release over a build marked Pre-release for everyday use.
2. Download the APK matching your device: arm64-v8a for ARM64 or armeabi-v7a for 32-bit ARM. Choose universal if unsure; it includes both ARM variants, not x86/x86_64.
3. Install the APK and open Aether+. Complete or skip onboarding and choose your language.
4. Start with the Aether core and default connection settings. Tap the connection control and approve Android's VPN request.
5. Wait for connection establishment, then check that an application can actually load content. If the connection fails, review diagnostics before adding extra chain layers.

Updates require the same application ID and a compatible signing certificate. A build signed with a different key cannot simply replace your installed copy. See signing guidance before changing distribution keys.

VPN mode routes device traffic through Android's VPN interface, subject to your split-tunneling and routing settings. Proxy-only mode does not capture the whole device: configure each proxy-aware application to use the active local proxy. Do not assume unrelated applications are protected in this mode.

LAN sharing is separate and disabled by default. Enable it only on a trusted Wi-Fi or hotspot network and use the address and live ports displayed in the sharing panel. It exposes proxy access to reachable devices; do not enable it on an untrusted network.

Start with Auto unless you are diagnosing a specific network restriction. Advanced settings expose MASQUE, WireGuard, gool, HTTP/2 selection, obfuscation, TLS fragmentation, and endpoint controls.

• Turbo: prioritize finding a responding endpoint quickly.
• Precise: compare candidates and select a better-performing endpoint; the default scan mode.
• Ultra: require a real traffic check before accepting an endpoint; useful on difficult networks and slower by design.

The app allows approximately 60, 190, and 340 seconds respectively for these scans. A manually pinned endpoint bypasses scanning. Overlay cores have their own startup budgets.

The supported combinations are:

• Aether
• Psiphon
• Tor
• Psiphon over Aether
• Tor over Aether
• Tor over Psiphon
• Tor over Psiphon over Aether
• Aether over Xray
• Psiphon over Xray
• Psiphon over Aether over Xray
• Tor over Xray
• Tor over Aether over Xray

Here, X over Y means X establishes its upstream connections through Y's local SOCKS5 proxy. For example, Tor over Aether carries Tor's relay connections through Aether; it does not put a fixed Aether proxy after the Tor exit. See chaining internals for the exact wiring.

Psiphon includes a built-in client configuration; ordinary users do not need to obtain or paste a configuration. The APK still needs the Psiphon executable and bootstrap server list. Tor requires its executable, and exit-country selection additionally requires its GeoIP assets.

Xray is your own server, connects first, and is never offered alone. Paste a share link (vless://, vmess://, trojan://, ss://, hy2://, wireguard://, socks://), a subscription body, or Xray JSON (comments are fine) under the selected Xray mode on the Chain page; the first entry Aether+ can run is used. Xray connects to your server first, and Aether, Psiphon, or Tor dial out through it (AETHER_UPSTREAM, UpstreamProxyUrl, Socks5Proxy), so the network sees only your Xray server. The config is a credential: it is stored encrypted with the Android Keystore on the device, and it is never part of the profile, an export, or a backup. See the Xray hop.

Important limitations:

• Chains containing Psiphon or Tor do not support general UDP traffic in this implementation. DNS is handled separately through the tunnel. UDP-only calls and games may fail; prefer Aether alone for those workloads.
• Tor can take several minutes to bootstrap. More layers add latency and are not automatically safer or more reliable.
• Bundled Tor integration does not include pluggable transports such as obfs4 or Snowflake.
• Country selection depends on reachable exits. Psiphon can retry with automatic selection if the requested country fails; Tor's strict country setting can prevent connection entirely.
• The bundled Xray-core (v26.9.30) no longer accepts allowInsecure (use the link's pcs / pinSHA256 certificate pin instead) or the HTTP/2 and QUIC transports. Plaintext VLESS / Trojan links to a public server are forwarded through an on-device dokodemo-door loopback relay (127.0.0.1:1850) so Xray accepts them unchanged. The Chain page says so when a pasted config cannot run.
• Development APKs can omit overlay cores or assets. The app reports unavailable modes; tagged-release CI requires the chain binaries and Psiphon bootstrap list.

Aether+ is a circumvention client, not a promise of anonymity or undetectable traffic. The selected network providers, DNS resolvers, applications, and any configured Zero Trust organization remain part of your trust model. Enabling an organization's Gateway can apply its filtering and logging policies.

• Android backup is disabled in the manifest. Diagnostics and crash reports can still contain sensitive information: review and redact them before sharing.
• Kill-switch settings are opt-in. Proxy-only mode, direct routes, and excluded applications must not be mistaken for device-wide protection.
• Obtain APKs from a source you trust. This repository supports a committed CI signing key as a fallback. That key is public: it can preserve update compatibility but cannot establish publisher authenticity. Production distributors should use a private release key and plan migration for existing installations
• The Android app does not contain an in-app APK installer. Install updates yourself from the repository's release page.
• Existing security-review documents record findings at particular revisions; they are not certification of the current build.

Never publish credentials, enrollment tokens, private keys, Xray share links, or unredacted logs in an issue. For a suspected vulnerability, use GitHub's private vulnerability reporting option if the repository exposes one; otherwise arrange a private channel with the maintainer before disclosing sensitive details.

The commands below follow the repository's Linux CI layout. Use Linux or a Linux development environment with the Android SDK configured.

The checked-in configuration currently specifies:

• JDK 17.
• Gradle 9.7.1, declared in the wrapper descriptor.
• Android SDK platform 37 and NDK 26.3.11579264.
• Rust stable, the two Android targets below, and cargo-ndk 4.1.2.
• Go 1.26 for Psiphon, with GOTOOLCHAIN=auto to satisfy the upstream module's toolchain directive when newer.
• Go 1.27 for Xray-core v26.9.30 (CI installs it separately as XRAY_GO_VERSION; GOTOOLCHAIN=auto fetches it locally).
• Git, Bash, C/C++ build tools, CMake, Make, curl, unzip, and Python 3.

Install Android SDK command-line tools and required build tools, accept SDK licenses, and make sdkmanager available. Dependency and asset downloads need network access. The build uses AGP 9.4.0-alpha04, Kotlin 2.4.20-RC3, and preview AndroidX dependencies: use the versions in the version catalog, not assumptions about a stable Android toolchain.

The repository contains a Gradle wrapper descriptor but does not ship gradlew or gradle-wrapper.jar. Install the declared Gradle version and use gradle, as CI does. Commands here are derived from the checked-in build configuration, not a claim of a separately verified local build.

git clone https://github.com/MrMatin0/Aether.git
cd Aether

# Set this to your Android SDK installation.
export ANDROID_SDK_ROOT="$HOME/Android/Sdk"
export ANDROID_HOME="$ANDROID_SDK_ROOT"
sdkmanager --licenses
sdkmanager --install "platforms;android-37" "platform-tools" "ndk;26.3.11579264"
export ANDROID_NDK_HOME="$ANDROID_SDK_ROOT/ndk/26.3.11579264"
export ANDROID_API=26

rustup target add aarch64-linux-android armv7-linux-androideabi
cargo install cargo-ndk --version 4.1.2 --locked

gradle --version
java -version

bash scripts/fetch-natives.sh
bash scripts/build-natives.sh all

These scripts use the vendored engine in native/aether, fetch hev-socks5-tunnel, and produce libaether.so, libhev-socks5-tunnel.so, and the project's JNI bridge libaethertun.so for both ARM ABIs under app/src/main/jniLibs/.

For a full-featured build, run each core build separately so failures are visible:

GOTOOLCHAIN=auto bash scripts/build-overlay-cores.sh psiphon
bash scripts/build-overlay-cores.sh tor
GOTOOLCHAIN=auto bash scripts/build-xray-core.sh
bash scripts/fetch-psiphon-serverlist.sh
bash scripts/fetch-fonts.sh

Psiphon is compiled from upstream source. Tor is extracted from the published tor-android AAR by default; TOR_FROM_SOURCE=1 selects the alternative source-build path. Xray-core is compiled from the tag pinned in scripts/build-xray-core.sh (XRAY_REF, default v26.9.30). See chain-core build notes and the Xray hop.

Overlay cores are optional for an Aether-only development build. Omitting their binaries or bootstrap assets makes the corresponding modes unavailable. Font retrieval also runs automatically before the Android build; fetching fonts explicitly is useful when preparing dependencies in advance.

# Development APKs
gradle :app:assembleDebug -PgithubRepo=MrMatin0/Aether

# Local JVM unit tests; the project uses the release test build type.
gradle :app:testReleaseUnitTest

# Release APKs; configure signing as described below.
gradle :app:assembleRelease -PgithubRepo=MrMatin0/Aether

APKs are written to app/build/outputs/apk/debug/ or app/build/outputs/apk/release/. Test reports are under app/build/reports/tests/. ARM64, 32-bit ARM, and universal ARM APKs are configured. These unit tests do not replace VPN, DNS, reconnection, and chain testing on a physical Android device.

For a private release key, start with keystore.properties.example and follow SIGNING.md. Local builds support keystore.properties or KEYSTORE_PATH, KEYSTORE_PASSWORD, KEY_ALIAS, and KEY_PASSWORD; CI accepts the keystore through KEYSTORE_BASE64. Keep private signing material out of Git. Without a configured private key, the checked-in CI fallback may be used; see the security warning above.

The build workflow builds native components, assembles APKs, runs unit tests, and checks signing and packaged payloads. Pushes to the default branch can publish prereleases; v* tags publish releases and enforce the full chain payload (Psiphon, Tor, and Xray). Documentation-only pull requests are excluded from that build workflow, but default-branch pushes are not.

app/src/main/java/studio/cluvex/aether/
  core/       Core processes, proxies, diagnostics, routing, traffic tracking
  data/       Application data and preferences
  model/      Connection profiles, routing models, chain definitions
  ui/         Compose screens, controls, and theme
  vpn/        Android VPN service and session orchestration
  widget/     Home-screen widget
app/src/test/ Local unit tests
native/aether/ Vendored Rust engine and quiche source
scripts/      Native builds, assets, signing helpers, core maintenance
docs/         Technical documentation and review history
.github/      Build and core-sync workflows, release metadata

In device-wide mode, Android supplies a TUN interface. The in-process hev tunnel and JNI bridge forward traffic into the selected local SOCKS5 entry. Aether, Psiphon, Xray, and Tor run as supervised child processes; SocksFront handles the DNS adaptation needed for Psiphon/Tor entries, while Xray answers DNS through its own resolver.

The executables are packaged under .so filenames so Android extracts them into an executable native-library directory. Preserve useLegacyPackaging = true unless this launch mechanism is redesigned.

• Connected, but applications cannot load content: check proxy-only mode, routing and split-tunneling rules, DNS settings, and whether the application needs UDP. Try Aether alone to isolate chain limitations.
• Scanning appears stuck: Precise and Ultra have longer budgets. Let the attempt finish, examine diagnostics, and try a different protocol or network instead of repeatedly restarting the same scan.
• Psiphon, Tor, or Xray is unavailable: install a build containing the required core. For Psiphon, also check the bootstrap server list; changing connection settings cannot repair a missing APK asset.
• Xray says the config cannot run, or the server does not answer: check the link against the limitations above (self-signed servers need pcs), then the server address, UUID / password, and TLS / REALITY settings. A wrong credential ends in a timeout, never a false "connected".
• APK will not install as an update: confirm the application ID, signing certificate, architecture, and version. Avoid uninstalling until you have considered the loss of application data.
• Gradle or native build fails: compare your installed versions with the checked-in toolchain, verify ANDROID_NDK_HOME, and check access to dependency repositories. A plain Android build without the native preparation steps is not a complete runnable VPN build.
• Vazirmatn download fails: run bash scripts/fetch-fonts.sh with network access, or supply the expected font files in app/src/main/res-fonts/font/ as described by the build error.

For a useful bug report, include the app version, Android version, device ABI, selected protocol and chain, reproduction steps, expected versus actual behavior, and redacted diagnostics. State whether you used a release APK or built from source.

Focused fixes, networking tests, accessibility improvements, and translation updates are welcome. The full guide — setup, branch and commit conventions, what CI checks, and the house rules — is in CONTRIBUTING.md.

In short:

1. Open an issue for a substantial behavior or architecture change before implementing it.
2. Create a branch from the current main and keep the change narrowly scoped.
3. Add or update relevant tests and run gradle :app:testReleaseUnitTest with the project toolchain.
4. Test affected network behavior on a supported physical device; include both success and failure cases.
5. Keep this README and the Persian version in sync, then open a pull request explaining the change and validation performed.

Do not commit generated APKs, downloaded native binaries, build caches, private configuration, or signing secrets. Preserve upstream attribution and review dependency license obligations when changing bundled components.

To report a security problem, do not open a public issue — see SECURITY.md.

• Contributing guide
• Security policy and how to report a vulnerability
• Chaining architecture and limitations
• Chain-core packaging and build notes
• The Xray hop: modes, config, chaining, and build
• APK signing and update compatibility
• Security review history (historical — written against the 1.2.x line)
• Vendored engine documentation
• Dependency versions
• Build and release workflow

Engine documentation covers a separate command-line component. Its desktop, Docker, and Termux instructions are not installation instructions for this Android APK. Where historical notes differ from current behavior, consult the relevant implementation and workflow.

This is a modified distribution of Aether Mobile, forked from QW-AI-Code/Aether and developed independently since. Under AGPL-3.0 section 5, it carries a record of what was changed and when: see MODIFICATIONS.md. The component-by- component license inventory is in THIRD_PARTY_NOTICES.md.

This project builds on the work of Aether Mobile contributors and these upstream projects:

• CluvexStudio/Aether: the Aether engine.
• hev-socks5-tunnel: TUN-to-SOCKS forwarding.
• Psiphon Tunnel Core: Psiphon connectivity.
• Tor Android and the Tor Project: Tor integration.
• Xray-core (Project X, MPL-2.0): the Xray hop.
• Vazirmatn: Persian and Latin typography.

The repository's LICENSE declares GNU AGPL version 3 or later, with no warranty. Bundled and downloaded third-party components retain their own licenses and notices; review those obligations before redistribution. Project and product names belong to their respective owners; integration does not imply endorsement.