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…

262 ·GitHub
WhiteAestherMobile
Что это?WhiteAestherMobile — нативный Android-клиент шифрованного движка маршрутов Aether. Он находит рабочий путь из ограничивающих или цензурируемых сетей и направляет трафик вашего устройства через него.
Это VPN-приложение или просто локальный прокси-инструмент?По умолчанию это полноценный VPN: он поднимает туннель Android VpnService, перехватывающий весь трафик устройства. Вместо этого можно переключить Coverage на «Proxy» — тогда открывается только локальный слушатель SOCKS5, на который приложения нужно направлять вручную.
Как установить его на телефон?Скачайте из последнего GitHub-релиза APK под архитектуру устройства (arm64-v8a покрывает почти все телефоны с 2017 года, при сомнениях берите universal-сборку), сверьте его с SHA256SUMS, затем установите вручную (sideload), так как через Play Store он не распространяется.
Какая версия Android и какое железо нужны?Android 8.0 (API 26) или новее, на устройстве arm64-v8a, armeabi-v7a или x86_64.
Ему всегда удаётся подключиться?Нет — движок активно проверяет реальные сетевые пути и повторяет попытки с нарастающими паузами, поэтому враждебная сеть может потребовать несколько попыток или не поддаться вовсе. Опциональные носители вроде Psiphon и Tor зависят ещё и от дополнительных шагов сборки; если их пропустили, приложение всё равно установится, но эта конкретная функция сообщит, что работать не может, а не молча откажет в момент подключения.
Какие данные собирает приложение?По умолчанию никаких: без аналитики, телеметрии и аккаунтов. Локальный прокси привязывается только к loopback, незашифрованный трафик блокируется, бэкапы отключены, а диагностические отчёты показываются вам до отправки куда-либо.
Какие транспорты Aether использует для обхода блокировок?MASQUE поверх HTTP/3 (QUIC), с HTTP/2 поверх TLS/TCP как запасным вариантом для сетей, блокирующих UDP, плюс профили обфускационного паддинга, чтобы усложнить снятие отпечатка туннельного трафика.
Для чего функция exit chain?Это опциональный второй хоп после основного туннеля, набираемый изнутри него, чтобы сайты назначения видели ваш собственный узел, а не Cloudflare. Узлы берутся из подписки или вставленных ссылок.
Можно использовать Tor или Psiphon вместо стандартного носителя Aether?Да, в разделе Routes можно переключить носитель на Psiphon или Tor. Оба медленнее и предназначены для сетей, из которых сам Aether не выбраться; Tor, в частности, не передаёт UDP.
Где живёт мой приватный ключ?Он создаётся при первом подключении и хранится в приватном для приложения хранилище — никогда не покидает устройство.
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
262
Updated
CommitOct 16Releasev1.13.0Oct 16
Age
2mo
Commits · 90 Days