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.
- Carrier — Aether by default. Under Routes, Psiphon or Tor can carry
the tunnel instead: each finds its own way out and the app routes the whole
device into it. Both are slower, and one of them is someone else's network, so
they are there for the networks Aether cannot get out of rather than as equal
choices. Tor carries no UDP, which the app declares rather than discovers
- Transports — MASQUE over HTTP/3 (QUIC) and HTTP/2 (TLS over TCP, for
networks that block UDP)
- Obfuscation — padding profiles that make tunnel traffic harder to
fingerprint
- Endpoints — discovered automatically, or pinned to a specific
IP:port
with optional fallback
- Identity — provisioned on first connect, private key kept in app-private
storage, never leaves the device
- Exit chain — an optional second hop after the tunnel, so sites see your
own node rather than Cloudflare. Nodes come from a subscription or pasted
links, and are dialled from inside the tunnel by default so neither your
network nor the node learns the other'''s address
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 是 Aether 加密路由引擎的原生 Android 客户端。它会探测出一条可用的路径来突破受限或受审查的网络，并让设备流量经由该路径路由。