MegaProxy

MegaProxy is an open-source Android VPN client for reliable, secure connections through proxy servers you control or trust. It supports HTTPS and SSH transports, per-app routing, encrypted DNS, connection diagnostics, and automatic failover in one privacy-focused application.

MegaProxy contains no advertising, analytics SDKs, tracking, or remote telemetry. Connection statistics and diagnostic logs stay on the device unless you explicitly choose to share them.

MegaProxy is under active development. Review the current limitations before relying on it for critical connectivity.

Why MegaProxy

• Private by design. No account, ads, analytics, tracking identifiers, or background telemetry.
• Your infrastructure. Connect to your HTTPS or SSH servers, directly or through a jump server.
• Preserves application TLS. HTTPS proxying uses CONNECT without intercepting or decrypting application TLS; plain application protocols still need their own encryption.
• Flexible routing. Route the whole device or only selected applications through the VPN.
• Resilient connections. Profile failover, encrypted DNS fallback, SSH keepalives, and connection health reporting help recover from network and server failures.
• Fully open source. The Android application and Go network core are available under the MIT License.

Features

Connection profiles

• Multiple named, colored, reorderable profiles.
• HTTPS proxies over TLS with Basic authentication, including two-proxy HTTPS with Jump chains.
• HTTP/2 CONNECT multiplexing when supported by the proxy, with automatic HTTP/1.1 fallback.
• SSH direct-tcpip transport and SSH through a jump host.
• SSH password and unencrypted private-key authentication.
• SSH host-key verification with trust-on-first-use confirmation.
• Profile cloning, import, export, and configurable failover.
• Import from MegaProxy JSON, ProxyList, FoxyProxy JSON, and supported SuperProxy text files.

VPN and routing

• Global VPN and per-app split tunneling.
• Local-network bypass enabled by default.
• Per-profile IPv6 support; IPv4-only operation is the default.
• Android Always-on VPN integration and a persistent foreground-service notification.
• Automatic reconnect when the active profile or pending connection settings change.
• Approximate upload speed, download speed, proxy latency, and recent connection-error rate.
• Session traffic totals with selectable IEC/SI units, connection start time and elapsed duration.

DNS and transport

• DNS-over-HTTPS through the configured transport.
• Cloudflare, Google, Quad9, Yandex Basic, Yandex Safe, Yandex Family, and custom DoH endpoints.
• DNS-provider fallback where it does not weaken an explicitly selected filtering policy.
• HTTPS ClientHello profiles powered by uTLS, plus manual JA3 configuration.
• Configurable SSH client profiles, keepalives, channel limits, and session rotation.
• Arbitrary UDP is intentionally not forwarded; QUIC/HTTP/3 clients normally fall back to TCP.

Diagnostics

• A staged connection test for proxy setup, example.com, and the observed exit IP and country.
• Local, size-limited, rotating diagnostic and crash logs designed to omit credentials and traffic content.
• On-device connection visibility checks and actionable connection warnings.
• Optional feedback or crash reports opened in the user's email client; nothing is submitted automatically.
• English and Russian interfaces with an in-app language selector.

Privacy and security

MegaProxy does not operate a proxy service and does not send configuration or usage data to the project author. Network traffic is sent only where required by the selected profile, destination, and DNS configuration. Proxy-hostname bootstrap may contact Cloudflare, Yandex, Google or Quad9 DoH resolvers directly before the tunnel exists. The explicit connection test contacts example.com and uses fallback providers for exit IP (ifconfig.me, api.ipify.org, icanhazip.com) and country (ifconfig.co, ipapi.co, api.country.is) through the proxy. See PRIVACY.md.

• HTTPS proxy certificates are checked against the Android trust store, including hostname and validity. Normal CA certificate renewal does not require certificate pinning.
• Application TLS remains between the application and its destination. MegaProxy does not install a CA certificate and does not perform TLS interception.
• Proxy passwords and imported private keys are encrypted with AES-GCM using a key held by Android Keystore.
• Android cloud backup and device-to-device transfer are disabled for application data.
• Every upstream socket is protected from recursive routing through the VPN.
• SSH host keys are verified and unknown keys require explicit user confirmation.

Two compatibility options deliberately reduce these protections: accepting an invalid HTTPS proxy certificate and accepting any SSH host key. MegaProxy displays a warning before enabling them. Use either option only when you understand and control the associated risk.

The proxy or SSH server can observe connection metadata and the destinations it is asked to reach, even though it cannot read end-to-end encrypted application content. The operator of that server must therefore be trusted. No application can override an explicit Android force-stop, and device vendors may impose additional background-execution restrictions.

Installation

Инструкция по установке на русском языке

MegaProxy requires Android 8.0 (API 26) or newer. Download the latest signed build from GitHub Releases, expand the Assets section, and download the file ending in universal.apk. It is the recommended build: it supports every architecture listed below and is the artifact intended for reproducible F-Droid verification.

Download the recommended universal APK

APK	Intended device
mega-proxy-universal.apk	Recommended for phones, tablets, and emulators; supports all listed architectures
mega-proxy-arm64-v8a.apk	Smaller download for almost all modern Android phones and tablets
mega-proxy-armeabi-v7a.apk	Older 32-bit ARM devices
mega-proxy-x86_64.apk	64-bit x86 Android emulators and uncommon x86 devices
mega-proxy-x86.apk	Older 32-bit x86 Android emulators and devices

Install a release APK on the device

1. Open the latest release on the Android device.
2. Under Assets, download the file ending in universal.apk. Architecture-specific APKs are smaller alternatives when the device architecture is known.
3. Open the downloaded file from the browser notification or the system Downloads application.
4. If Android blocks the installation, open the settings offered by the warning and enable Allow from this source for the browser or file manager that opened the APK. Return to the installer and confirm Install. This permission can be disabled again after installation.
5. Open MegaProxy. Android asks for VPN access when the first connection is started; approve the system VPN confirmation dialog.

Browsers may warn that APK files can be harmful because the application is installed outside an app store. Confirm the download only when the URL belongs to this repository. Do not download MegaProxy APKs from third-party mirrors.

Verify the download

Each release includes a SHA256SUMS file. Download it alongside the APK and compare the APK hash before installation when the distribution channel is not trusted:

# macOS
shasum -a 256 mega-proxy-universal.apk

# Linux
sha256sum mega-proxy-universal.apk

The printed value must exactly match the corresponding line in SHA256SUMS. Substitute the downloaded version and architecture in the filename.

Install with ADB

Alternatively, download the APK to a computer. With USB debugging enabled and the device listed by adb devices, install or update MegaProxy with:

adb install -r mega-proxy-universal.apk

Use the APK filename that was actually downloaded. The -r option preserves existing application data during an update. Confirm the USB-debugging authorization prompt on the phone if Android shows one.

Update an existing installation

Download the newer universal APK and install it over the existing application. An appropriate architecture-specific APK signed by the project key can also update the same installation. Do not uninstall MegaProxy first: uninstalling removes its profiles, trusted SSH host keys, and other local settings. Android accepts an in-place update only when the application ID and signing key match the installed build.

Release APKs are signed by the project's release key. SHA-256 checksums are published alongside the APK files. Android will preserve application data across upgrades only when the package name and signing key remain unchanged.

After installation:

1. Create or import a connection profile.
2. Choose global routing or select applications for split tunneling.
3. Review DNS and fingerprint settings if the defaults are not appropriate for your server.
4. Open the main-screen menu and choose Test, then tap Connect.
5. Optionally enable Always-on VPN in Android settings.

Server configurations and setup instructions are maintained separately in MegaProxyServer.

Generated configuration imports

External generators can produce MegaProxy JSON files using schema net.megaproxy487.config, version 8. Every profile must have a stable, generator-controlled id. Reimporting a file updates profiles with matching IDs and adds only new IDs; it does not create duplicates. Omitted password and SSH private-key fields preserve credentials already stored on the device, while explicit empty values clear them. After import, MegaProxy offers an unselected list of local profiles absent from the file so the user can optionally remove specific obsolete profiles.

HTTPS with Jump

Select HTTPS with Jump to use two HTTPS CONNECT proxies in sequence: phone → jump proxy → destination proxy → website. Enter the destination proxy in the main connection fields and the first hop in Jump HTTPS proxy. Both ports default to 443. The jump proxy must allow CONNECT to the destination proxy hostname and port; it resolves that hostname. Only the jump proxy is bootstrapped on the phone. Both hops use the selected TLS fingerprint and support HTTP/1.1 and HTTP/2 CONNECT independently.

Each hop verifies its own TLS certificate and can use separate Basic Auth credentials. The optional shared-authentication setting reuses the destination username and password. Certificate verification exceptions apply only to the selected hop. Connection tests and DoH use the chain; local-network destinations still follow the existing bypass setting. A failed hop never causes fallback to a direct connection to the destination proxy.

JSON schema version 8 stores this mode as proxy.type: "HTTPS_JUMP", with first-hop settings in proxy.jump: host, port, sameAuthentication, username, password, and allowInvalidProxyCertificate. Export passwords only when needed. Older application versions reject version 8 files, preventing a chain from being imported as a single proxy. ProxyList exports support single HTTPS proxies only and omit chain profiles.

Current limitations

• Only TCP application traffic is forwarded. General SOCKS5 UDP and QUIC forwarding are not implemented.
• SSH private keys protected by a passphrase are not supported yet.
• Browser and SSH fingerprint presets are version-specific approximations. A preset name is not a permanent guarantee of an exact client fingerprint.
• Edge Android, Samsung Internet, and Yandex Browser TLS presets remain unavailable until verified Android ClientHello fixtures are added.
• Always-on behavior ultimately depends on Android and the device vendor. An explicit force-stop cannot be recovered from programmatically.

Building from source

The command-line build does not require Android Studio. It requires:

• JDK 21
• Go 1.26.3 or newer (see native/go.mod)
• Network access to download the pinned gomobile/gobind tools during native builds
• Android SDK Platform 36 and Build Tools 36.0.0
• Android NDK 29.0.14206865

Example environment on macOS:

export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
export ANDROID_HOME="$HOME/Library/Android/sdk"
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/29.0.14206865"
export PATH="$JAVA_HOME/bin:$HOME/go/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH"

Install Ruby 3.4 and the pinned Fastlane dependencies, then build and test the application through the project's supported automation entry point:

bundle install
bundle exec fastlane android test

For a debug APK without the complete check suite, run bundle exec fastlane android debug_artifact. The APK is written to app/build/outputs/apk/debug/app-debug.apk. Gradle and the scripts under scripts/ remain the low-level implementation used by the Fastlane lanes. Installation details and the complete command reference are in the Fastlane workflow documentation (по-русски).

Install the debug APK on a connected device:

adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n net.megaproxy487/.MainActivity

The project pins Gradle 8.11.1 through the checked-in wrapper. Use ./gradlew rather than a globally installed Gradle version. See native/README.md for Go data-plane details.

Development workflow

English is the project language for source code, comments, commit messages, logs, and tooling. User-visible UI strings are provided in English and Russian. Developer guides are maintained in both languages; numbers and dates follow the system locale independently of the app language.

Emulator

For optional local device testing on an ARM64 host, create the API 35 Google APIs ARM64 emulator (the script installs the emulator and system image if missing):

./scripts/create-android-emulator.sh

Required CI and Robolectric Compose tests do not need an emulator.

The script installs missing components, configures host keyboard and mouse input, and can be run more than once. It creates MegaProxy_API_35 by default; set MEGAPROXY_AVD_NAME to override the name.

Start the application without a debugger:

./scripts/run-without-debugging.sh

The repository also includes VS Code tasks and launch configurations for creating and starting the emulator, building, installing, viewing app-specific Logcat output, running tests, and attaching a JDWP debugger. Select Run MegaProxy on Emulator for Ctrl+F5 or Attach MegaProxy (JDWP) for F5.

For Kotlin editing, install the workspace recommendations, including fwcd.kotlin and Gradle for Java. The repository's kls-classpath helper supplies the language server with the Android SDK, Compose dependencies, and generated R classes that it cannot discover from Android Gradle Plugin variants by itself. After installing or updating the extensions, run Kotlin: Restart the Language Server (or Developer: Reload Window) once. Run ./kls-classpath directly to diagnose classpath resolution.

Run all native and Android checks from VS Code with Tasks: Run Test Task, or from a shell:

bundle exec fastlane android test

JDWP covers Kotlin and Java code only. Debug the Go core with its tests and privacy-safe diagnostic logging.

Signed release builds

Release scripts require gomobile on PATH. The debug_artifact and android_checks lanes install the pinned native tools; run either once when preparing a fresh build environment.

Build optimized and signed APKs for arm64-v8a, armeabi-v7a, x86_64, and x86, plus the universal APK used for reproducible F-Droid verification:

bundle exec fastlane android release_artifacts

The scripts read the default signing key from $HOME/AndroidApkKey and its password from $HOME/.my-tokens/android-key-password. Override these with MEGAPROXY_KEYSTORE_PATH, MEGAPROXY_KEY_ALIAS, MEGAPROXY_KEY_PASSWORD_FILE, and MEGAPROXY_KEY_PASSWORD. The signed ABI-specific and universal APKs, the signed universal App Bundle, its native debug-symbol archive, and SHA256SUMS are written to dist/release. The App Bundle contains every supported ABI; app stores generate and serve optimized device-specific APK splits from it. Go native symbols are provided as mega-proxy-native-debug-symbols.zip for upload in Play Console.

Pushing a version tag runs the same Fastlane release lane in GitHub Actions, builds and verifies every APK and the App Bundle, and attaches the artifacts to a GitHub Release. The tag must match v followed by the current versionName in app/build.gradle.kts. Create that tag with git tag and push the specific tag with git push origin; do not reuse a historical release tag.

Contributing

Bug reports and focused pull requests are welcome. Please avoid including proxy credentials, private keys, destination history, or other personal data in issues and logs. Run both the Go and Android checks with bundle exec fastlane android test before opening a pull request. For Python changes, also run bundle exec fastlane android python_checks; the test lane does not include Python.

License

MegaProxy is released under the MIT License.

CI tools

Every push to main runs all Android/Compose UI, Go and Python checks; the CI badge tracks these runs. PR CI selects checks from changes since each suite’s last successful ancestor check, with a full PR diff fallback. Use python3 scripts/github_actions.py to choose an open PR and rerun all CI jobs (including skipped checks) or only failed jobs through GitHub CLI. Supports --dry-run and --yes/-y. See the English or Russian reference for scope rules, Python formatting/tests and launcher setup.