VPN App

Private Android/Desktop client built as a small monorepo:

app/ — Flet/Python UI, profiles, settings, runtime state and common business logic.
native/android/ — Flet service extension and Kotlin service boundary. VPN lifecycle, TUN, foreground service, hotspot and mobile libraries belong here, not in Python.
backend/ — deliberately small FastAPI + SQLite operator API and device subscription endpoint.
docs/ — architecture, upstream research, implementation status and device test plan.

The current product scope is Android first and desktop proxy-only. iOS is intentionally not in this repository. macOS is not a target of the first build; if added later it will be proxy-only unless a separate native implementation is approved.

Current product model

The app has two top-level tabs:

VPN — Основная (VLESS) and Усиленная (AmneziaWG 3.1), both through the SignBox adapter contract.
Белые списки — FreeTurn, with stream presets 1..4, CAPTCHA handling and optional stability mode.

The Python engine manager is real and tested. Desktop SignBox proxy mode can launch a configured local executable when one is supplied. Android native lifecycle and command protocol are implemented; FreeTurn is integrated from a pinned local AAR during the build, while SignBox remains UNSUPPORTED until the exact signed artifact and API are supplied. Engine AARs are intentionally not checked into git. The UI never treats an unsupported result as a successful connection.

The exact remaining functional blockers are tracked in docs/implementation-status.md; an APK build alone is not evidence that the missing VPN data path works.

Quick start

uv sync
uv run flet run app/main.py
uv run pytest

Run the backend locally:

export VPNAPP_ADMIN_TOKEN='replace-this-in-a-secret-shell'
uv run uvicorn backend.main:app --reload --port 8080

The backend deliberately requires HTTPS in deployment. VPNAPP_ADMIN_TOKEN is an operator credential only. Devices use a separate random bearer credential; UUIDs and User-Agent strings are not authentication.

Build scripts

./scripts/fetch-engine-artifacts.sh       # fetches pinned libbox + verifies SHA256SUMS
./scripts/build-android.sh                # flet build apk (requires Android SDK/Flutter)
./scripts/build-desktop.sh linux          # flet build linux
./scripts/run-backend.sh                  # local backend

For Android, the fetch script downloads Leadaxe/sing-box-lx at the pinned version. REQUIRE_NATIVE_ARTIFACTS=1 ./scripts/build-android.sh then builds an arm64 APK. Artifacts stay ignored; versions and hashes live in native/android/libbox.version and THIRD_PARTY_NOTICES.md.

The current Android APK is libbox-first. FreeTurn is not packaged alongside it because the independently generated gomobile AARs contain incompatible global runtime classes; see docs/implementation-status.md.

Security posture

The default proxy bind is localhost. Wi-Fi sharing is explicit, binds to the discovered LocalOnlyHotspot address, and requires authentication by default. Management/debug APIs are disabled by default. Secrets are redacted from logs. Application routing models distinguish PROXY, DIRECT, and VOID; DIRECT excludes the package from VpnService, while VOID fails startup until its native fail-closed classifier is shipped.

License and upstreams

This repository's original code is MIT-licensed; see LICENSE. Upstream components, versions, URLs and license obligations are recorded in THIRD_PARTY_NOTICES.md. Do not copy the GPL Android reference application's UI or source into this project.

3.7 KiB Raw Blame History