Proxy Switcher VPN

English · Русский · Українська · Deutsch · Français · Español · Italiano · Português (Brasil) · Polski · 简体中文 · 日本語 · 한국어

Android app for running a local VPN that routes device traffic through the selected upstream proxy or through explicit Direct mode.

The app does not change Android system proxy settings. It uses VpnService and an embedded sing-box core.

Screenshots

Captured from the debug app (v0.4.1) on Android API 35. Proxy profiles use only reserved TEST-NET addresses and contain no credentials; proxy check results are sample data.

Home — VPN running	Proxy profiles
Add proxy	VPN diagnostics
Filtered VPN logs

Languages

The app is available in English, Russian, Ukrainian, German, French, Spanish, Italian, Portuguese (Brazil), Polish, Chinese (Simplified), Japanese and Korean. It follows the system language; you can also pick a language in Settings → Language or, on Android 13+, in the system per-app language settings. Log entries and technical diagnostic values stay in English so bug reports are easy to read.

Limits

• IPv4 only;
• IPv6 is explicitly unsupported;
• UDP/443 is blocked by default to avoid QUIC/HTTP3 bypass;
• if the selected upstream proxy remains unavailable after retries, VPN stops fail-closed;
• Direct mode is explicit and is never used as a silent fallback;
• proxy passwords must be masked in UI, logs, and diagnostics.

Keeping the VPN running

Android, and Samsung One UI in particular, can kill the app process in the background. To keep the VPN up:

• allow the app to run in background (Home shows an "Allow" warning while it is battery-optimized); on Samsung also remove it from Sleeping apps;
• optionally enable Always-on VPN in Android VPN settings (Settings dialog → Always-on VPN). With "Block connections without VPN" this works as a kill switch: no traffic leaves the device while the VPN is down.

If the process is killed while the VPN is enabled, the app restores the VPN within a minute or two. Diagnostics shows the last VPN stop reason and the last app exit reason.

Build

make test
make build-local

The first build downloads the pinned sing-box/libbox AAR (about 97 MB) into the Gradle user cache. gradle/libbox.properties fixes its source revision, immutable artifact URL, byte size, and SHA-256. Every build verifies the hash and required native ABIs before compilation. To fetch it explicitly:

make fetch-libbox

Debug APK:

app/build/outputs/apk/debug/app-debug.apk

Install on a connected device:

make install

Debug Logs

The app writes sanitized runtime logs to the in-app Logs screen and Android logcat:

adb logcat -s ProxySwitcherVPN

Logs include route selection, proxy tests, upstream monitor results, reconnect attempts, backoff, TUN setup, engine lifecycle, and final fail-closed reasons. Proxy passwords are masked.

Release

The version is read from VERSION.

make update-version
make release

make release updates Gradle versionCode/versionName, runs checks, builds the release, creates a commit/tag, and pushes the tag.

A signed release requires keystore.properties. Do not commit secrets or the keystore.

License

Proxy Switcher VPN is licensed under GNU GPL v3 or later. Releases embed sing-box/libbox, so distributors must also preserve third-party notices and provide the exact corresponding source required by GPLv3. See third-party notices and the dependency license audit.