WhiteDNS for Android: a DNS tunneling client with VPN and proxy modes
Source-available Android DNS tunneling client with VPN and proxy modes, backed by MasterDNS & StormDNS.
At a glance
- What is it?
- WhiteDNS is an Android app that runs local DNS tunneling through StormDNS and CottenDns engines, with a SOCKS5 proxy path and a VpnService path that packages tun2proxy. It is source-available, not open source, and the licence restricts redistribution.
- Who is it for?
- WhiteDNS suits Android users who want a local DNS tunneling client with both a SOCKS5 proxy path and a VpnService path, and who accept that the licence forbids redistributing builds. It is the wrong choice if you need an open source licence, a Play Store install, or a desktop client, since the repository only ships an Android app.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 53 days ago.
- What is it written in?
- Mainly Kotlin, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What WhiteDNS actually does on an Android device
WhiteDNS is an Android application for running a local DNS tunneling client, according to the README. The client engines underneath are StormDNS and CottenDns, both pinned as source under third_party/ and compiled into native libraries. The app itself is Kotlin, Jetpack Compose with Material 3, and it ships two ways to move traffic: a foreground proxy service with local SOCKS5 support and an optional HTTP proxy bridge, and a VPN service built on Android VpnService that packages tun2proxy.
The audience is narrow. This is not a general-purpose VPN client that speaks WireGuard or OpenVPN. It is for people who already have a WhiteDNS server profile, or a stormdns:// profile link, and want an Android endpoint for it. The README lists built-in and custom server profiles, resolver profile management with validation, split tunnel options, and runtime logs with traffic statistics. Those features assume you are pointing the app at infrastructure you or someone else already runs.
How the proxy and VPN paths differ under the hood
The repository layout tells most of the story. Under app/src/main/java/shop/whitedns/client/ there are separate packages: proxy/ holds the foreground proxy service and the HTTP bridge, vpn/ holds the Android VPN service and tun2proxy management, storm/ holds StormDNS config and process management, and runtime/ handles state, traffic counters and progress parsing. The two paths do not share a data plane.
In proxy mode the app exposes a local SOCKS5 listener, so any app that can be pointed at a SOCKS5 proxy can use the tunnel without the system VPN permission. The HTTP bridge is described as optional, which suggests it wraps the SOCKS5 path rather than replacing it. In VPN mode the traffic is captured at the system level through VpnService and handed to the packaged tun2proxy native libraries, which is why jniLibs/ contains native StormDNS, CottenDns and tun2proxy binaries for multiple ABIs. Split tunnel options apply to VPN routing, per the README, not to the proxy path.
The trade-off is visible here. Proxy mode is lighter and needs no VPN consent dialog, but only apps you configure will use it. VPN mode captures everything the split tunnel rules allow, at the cost of a persistent foreground service notification and a native library per architecture in the APK.
Building a local debug APK from the WhiteDNS repository
The README gives explicit local development instructions and states they are for review, testing and contribution to the official project only. It does not grant permission to publish, redistribute, re-sign or upload APKs. The stated requirements are Android Studio or the SDK command line tools, JDK 17, Go matching the version in third_party/StormDNS/go.mod and third_party/CottenDns/go.mod, the SDK platform for compileSdk = 36, NDK 26.3.11579264, and NDK 29.0.14206865 for rebuilding the native clients.
Start by pulling the pinned submodules, then run the unit tests and the debug build target:
git submodule update --init --recursive
./gradlew testDebugUnitTest
make debugThe Makefile's debug target depends on both stormdns and cottendns, so it cross-compiles the Go clients for arm64, armv7, x86_64 and x86 before Gradle assembles the APK. Each native target runs check-ndk first, which tests for the clang wrapper under NDK_ROOT and exits with a message if the NDK is missing. If Go is not on your PATH, the README shows passing it explicitly:
make debug GO=/path/to/goThe README states the debug APK uses package shop.whitedns.client.debug and the label WhiteDNS Debug, so it can be installed alongside a production build without uninstalling it. That is the practical way to try profile import and resolver validation without touching an existing install.
Where WhiteDNS is the wrong tool
The licence is the first limit. WhiteDNS is source-available proprietary software, and the README is direct about it: you may view the code and submit contributions, but you may not fork it into another app, redistribute builds, repackage APKs, sell modified versions, or reuse the name, logo, icon, design or branding. If your requirement is an open source licence that permits redistribution, this project fails that requirement before any technical question is asked. The repository's LICENSE.MD is listed under NOASSERTION in the metadata, and the README itself says the project is not open source.
The second limit is distribution. The README carries an app store warning: WhiteDNS has no publication on Google Play, and any APK, listing or package found there or on another marketplace is not an official release and may be modified, outdated or unsafe. The official channel is the Telegram link in the README. Anyone who needs a store-managed install path with automatic updates has no supported option here.
The third limit is scope. The repository is an Android app. The related searches include WhiteDNS Windows and WhiteDNS Linux, but the material describes only an Android client with VpnService and a SOCKS5 proxy service. Nothing in the README documents a desktop build, and the Makefile targets Android ABIs only. Treat desktop availability as unconfirmed.
Finally, release builds are produced only by the official maintainers, per the README. A self-built debug APK is for local review, not a substitute for a release channel.
How WhiteDNS compares with a general VPN client
A conventional Android VPN client, such as one built on WireGuard or OpenVPN, establishes a tunnel to a server and routes IP traffic through it. The transport is the point: the client speaks a standard protocol and the server terminates it. WhiteDNS takes a different approach. It runs a DNS tunneling client locally and carries traffic inside DNS, using StormDNS and CottenDns as the client engines. The README describes the app as a local DNS tunneling client, and the credits point to the MasterDNS Client project as the backing work.
That difference drives the feature set. Resolver profile management, validation and default resolver assets exist because the resolver is part of the tunnel, not an afterthought. The stormdns:// profile import and export helpers exist because server profiles are a first-class object. A WireGuard client has no equivalent concept. Conversely, a WireGuard client gives you a standard, widely documented protocol and a mature ecosystem of servers; WhiteDNS gives you a specific engine pair and a profile format that only this family of tools understands.
If your goal is a general encrypted tunnel with broad server support, a standard VPN client is the more conventional pick. If your goal is specifically DNS tunneling with these engines, the alternative is to build the StormDNS or CottenDns client yourself on the target platform, which is what the third_party/ submodules exist for.
Licence, maintenance and upgrade cost
The last push to the default branch was on 2026-07-28, the same day release 1.6.0 was published. Before that, the release list shows v1.5.1c-rc17 on 2026-07-23 and v1.5.1c-rc15 on 2026-07-22, so the project moved through release candidates quickly in the week before 1.6.0. The repository is not archived.
Upgrading is not a matter of swapping an APK. The app depends on pinned native sources in third_party/StormDNS and third_party/CottenDns, and the Makefile cross-compiles them with the NDK. The README names two NDK versions: 26.3.11579264 for the app and 29.0.14206865 for rebuilding the native clients. A Go toolchain matching the go.mod files is also required. In practice, anyone tracking upstream changes is maintaining a Go toolchain, two NDK installs and a Gradle build together.
On licensing, the README is explicit that the project is not open source and that contributions are accepted through the official repository. It references LICENSE.MD, CONTRIBUTING.md, CLA.md and TRADEMARK.MD. The CLA and trademark files exist alongside the licence, which is consistent with a project that wants code contributions while retaining control of the name and builds. The practical implication for an engineer is that reading the code and filing a patch is fine, and shipping a modified build is not. This is a description of what the repository states, not legal advice; read LICENSE.MD and TRADEMARK.MD yourself before doing anything with the code beyond local review.
Editorial conclusion
WhiteDNS suits Android users who want a local DNS tunneling client with both a SOCKS5 proxy path and a VpnService path, and who accept that the licence forbids redistributing builds. It is the wrong choice if you need an open source licence, a Play Store install, or a desktop client, since the repository only ships an Android app. Before building, verify that the Go version in third_party/StormDNS/go.mod matches your toolchain and that both Android NDK versions named in the README are installed, because the Makefile aborts the native build without them.
Frequently asked questions
Is WhiteDNS available on Google Play?
No. The README states WhiteDNS has no publication on Google Play, and that any APK, listing or package found there or on another marketplace is not an official release and may be modified, outdated or unsafe. It points to the repository and the official Telegram channel as the sources for project updates.
What is WhiteDNS built on?
The README credits the MasterDNS Client project and says WhiteDNS supports both the StormDNS and CottenDns client engines. Both engines are pinned as source under third_party/ and compiled into native libraries for the Android ABIs.
Can I redistribute a WhiteDNS APK I built myself?
No. The README says the local build instructions do not grant permission to publish, redistribute, re-sign or upload APKs, and that release builds are produced only by the official maintainers. It also states you may not repackage APKs or publish modified builds.
Community notes