WhiteAestherMobile README

The project's README from github.com/WhiteDNS/WhiteAestherMobile. As one markdown file: README.md.

WhiteAestherMobile

Android client for the Aether encrypted route engine. Finds a working path out of restrictive networks and carries your traffic through it.

Release CI Licence Android

Install

Grab the APK for your phone from the latest release.

File Use it if
arm64-v8a Almost every phone from 2017 onward. Start here.
armeabi-v7a Older or budget 32-bit devices
x86_64 Emulators, ChromeOS
universal You are not sure. Works everywhere, roughly three times the size.
.aab Play Store submission, not for sideloading

Verify what you downloaded against SHA256SUMS in the same release:

sha256sum -c SHA256SUMS --ignore-missing

Android will warn about installing outside the Play Store. That is expected for a sideloaded APK.

راهنمای فارسی: docs/GUIDE.fa.md -- installing, first run, and what to change when a network blocks the connection.

First run

1. Leave Coverage on "Whole device". Under Traffic, this is the default and what almost everyone wants — every app on the phone is carried through the tunnel. Proxy only runs a local SOCKS5 listener instead and routes nothing by itself; traffic only goes through it if you point an app at 127.0.0.1:1819. If you pick it by accident, it looks like the app connected but did nothing.

2. Leave the profile on "Adaptive". Under Routes. It balances how hard the engine searches against how quickly it connects. The other profiles are narrower:

Profile For
Adaptive Most networks. Start here.
Patchy signal Mobile data that keeps dropping — searches harder
Strict network Office or campus Wi-Fi that blocks a lot — quieter probing, slower
Manual You set the transport and search depth yourself

3. Allow background running when asked. Under Settings, a card appears if Android is still allowed to suspend the app. Without the exemption the tunnel drops when the screen goes off — some manufacturers are far more aggressive about this than others.

4. Expect the first connect to take a moment. The engine tests real network paths before accepting one. If a path fails it backs off and retries, and the status line tells you which attempt it is on.

When it will not connect

The line under the big status heading is the engine's own message, not a generic error. It is the first thing to read.

What you see What it means
... · retry 3 of 8 in 12s A path failed and it is trying another. Normal on a hostile network.
Could not reach Tor's bridge service Tap Fetch bridges while connected through Aether or Psiphon, or paste bridges from @GetBridgesBot.
... is looking for a way out A carrier is establishing. Psiphon tries many protocols at once; Tor fetches a consensus and builds a circuit. A minute is normal, and behind a bridge rather more.
Stopped after 8 attempts Nothing worked here. Try a different profile or network.
custom endpoint ... failed MASQUE validation The address you pinned is not reachable. Switch Endpoint back to Automatic.
Connected to a different endpoint Your pinned address failed and fallback substituted a working one.

Worth trying, in order: switch the profile to Strict network; set Addresses to IPv4 only under Traffic if the network handles IPv6 badly; turn Obfuscation up to Aggressive.

Under Settings → Diagnostics you can raise the detail level, reproduce the problem, and send a report. It shows you the exact text before anything is sent, and replaces IP addresses with placeholders unless you turn that off.

How it works

Aether probes reachable Cloudflare endpoints, completes an authenticated MASQUE handshake against them, and only accepts a route once real traffic returns through it. The app then either raises an Android VpnService tunnel that captures IPv4, IPv6 and DNS, or exposes a loopback SOCKS5 proxy.

Requirements

Android 8.0 (API 26) or newer, on arm64-v8a, armeabi-v7a or x86_64.

Build from source

git clone https://github.com/WhiteDNS/WhiteAestherMobile.git
cd WhiteAestherMobile
./gradlew assembleStableDebug

Needs JDK 21, Android SDK 36 with NDK 29.0.14206865 and CMake 3.22.1, and Rust 1.88.0 with the Android targets plus cargo-ndk. The Gradle build compiles the Rust bridge itself.

./gradlew :app:compileStableDebugKotlin skips the native build and is the fast loop when only touching Kotlin.

Two things Gradle does not build for you. The exit chain's Go library, which the Psiphon carrier also needs to reach the interface:

pwsh -File native/chain/setup.ps1
pwsh -File native/chain/build.ps1

Psiphon's bootstrap server list, which is data rather than code and is not committed:

pwsh -File native/psiphon/setup.ps1

and Tor's pluggable transports, which are Go programs built as Android executables:

pwsh -File native/tor/setup.ps1
pwsh -File native/tor/build.ps1

A build missing either still installs and runs; the feature that needs it says so rather than failing at connect time on somebody's phone.

Repository layout

Path
app/ The Android application
native/aether/ Vendored Aether engine
native/psiphon/ The Psiphon carrier: what to fetch, and why it is a separate process
native/android-bridge/ Rust JNI bridge between the two
design/ Clickable design prototype and the notes from building it
docs/ Release process and device test plan

design/PORT-STATUS.md records what was verified against the engine and what is still outstanding — worth reading before changing the connection UI.

Releasing

CI verifies every pull request and every push to main. Publishing happens on tags alone:

git tag v1.2.3 && git push origin v1.2.3

That builds, tests, signs, verifies every APK, and publishes the release.

Privacy

No analytics, no telemetry, no accounts. The proxy binds to loopback only, cleartext traffic is blocked, backups are disabled, and diagnostics reports are never sent without you reviewing them first. See PRIVACY.md.

Licence

AGPL-3.0, as is the Aether engine it embeds. The exit chain is built on mihomo, which is GPL-3.0; AGPL-3.0 section 13 permits the combination, and each part keeps its own licence. Components, revisions, and the one modification we make are listed in THIRD_PARTY_NOTICES.md.

WhiteAestherMobile (WhiteDNS/WhiteAestherMobile)

Searching Database…

255 ·GitHub
WhiteAestherMobile
What is this?WhiteAestherMobile is the native Android client for the Aether encrypted route engine. It probes for a working path out of restrictive or censored networks and routes your device's traffic through it.
Is this a VPN app or just a local proxy tool?By default it's a full VPN: it raises an Android VpnService tunnel that captures all of the device's traffic. You can switch Coverage to 'Proxy' instead, which only exposes a local SOCKS5 listener that apps must be pointed at manually.
How do I install it on my phone?Download the APK matching your device's architecture (arm64-v8a covers almost every phone since 2017, or grab the universal build if unsure) from the latest GitHub release, verify it against SHA256SUMS, then sideload it since it isn't distributed through the Play Store.
What Android version and hardware do I need?Android 8.0 (API 26) or newer, on an arm64-v8a, armeabi-v7a or x86_64 device.
Does it always manage to connect?No — the engine actively tests real network paths and retries with backoff, so a hostile network can take several attempts or fail outright. Optional carriers like Psiphon and Tor also depend on extra build steps; if those are skipped, the app still installs but that specific feature reports it can't work rather than failing silently at connect time.
What data does the app collect?None by default: no analytics, no telemetry, no accounts. The local proxy only binds to loopback, cleartext traffic is blocked, backups are disabled, and diagnostic reports are shown to you before anything is sent out.
What transports does Aether use to get through blocks?MASQUE over HTTP/3 (QUIC), with HTTP/2 over TLS/TCP as a fallback for networks that block UDP, plus obfuscation padding profiles to make tunnel traffic harder to fingerprint.
What is the exit chain feature for?An optional second hop taken after the main tunnel, dialled from inside it, so destination sites see your own node rather than Cloudflare. Nodes come from a subscription or pasted links.
Can I use Tor or Psiphon instead of the default Aether carrier?Yes, under Routes you can switch the carrier to Psiphon or Tor. Both are slower and meant for networks Aether itself can't escape, and Tor specifically carries no UDP.
Where does my private key live?It's provisioned on first connect and kept in app-private storage — it never leaves the device.
What are similar projects?ClashMetaForAndroid, fanqiang, mlmvpn_android, v2rayNG, panda-vpn-pro, russia-mobile-internet-whitelist, usque-custom-pro, clash
Which topics is it in?f-droid, http3, tor, quic, vpn-client, mihomo, gfw, socks5, privacy-tools, anti-censorship, censorship-circumvention, cloudflare
Creator
WhiteDNS
Size
19.7 MB
Stars
255
Updated
CommitOct 16Releasev1.13.0Oct 16
Age
2mo
Commits · 90 Days