Network paths can fail differently
Direct WebSocket, Cloudflare Proxy, Cloudflare Worker, and direct TCP do not have the same availability on every network. A single fixed route is not sufficient for all Wi-Fi and mobile environments.
← All projects
Stable · v1.10.13
Stable · v1.10.13> android / local Telegram proxy
TgWsProxy Android
A local Telegram proxy with MTProto and SOCKS5 frontends and multiple network routes.
TgWsProxy Android listens locally on the device, lets Telegram connect through MTProto Proxy or SOCKS5 compatibility mode, and delegates outbound routing to a native Go runtime. The primary v1.10.13 path is MTProto Proxy → Cloudflare Proxy on 127.0.0.1:1443.
PlatformAndroid 8.0+
Releasev1.10.13
Published25 Aug 2026
ABIarm64-v8a
LicenseGPL-3.0
> context
What the app does
It is a Telegram-specific local proxy, not a system-wide VPN. Only traffic that Telegram sends to the configured local proxy is handled by the application.
Separate the local frontend from the outbound route
Telegram connects to a local MTProto or SOCKS5 frontend. Android ProxyService keeps the foreground service alive, while the Go runtime applies per-network route policy and chooses only routes allowed by that policy.
> capabilities
Core capabilities
The stable release combines a local Telegram frontend, route policy, diagnostics, lifecycle handling, and safe update/feedback flows.
MTProto Proxy frontend
Primary local frontend with Telegram proxy-link generation and Fake TLS secret formats.
SOCKS5 compatibility
Compatible SOCKS5/WebSocket frontend remains available for manual Telegram proxy configuration.
Per-network policies
Separate allowed and preferred routes for Wi-Fi, mobile data, and unknown network profiles.
Cloudflare Proxy
Recommended cf_proxy_ws route through Cloudflare proxy domains and WebSocket transport.
Direct WebSocket
Optional direct_ws path to Telegram WebSocket endpoints when the network allows it.
Cloudflare Worker
Optional cf_worker_ws route through a user-configured Cloudflare Worker, including worker failover logic.
TCP fallback
Optional direct TCP route to Telegram data-center IPs on port 443 when policy permits it.
Diagnostics
Route probes, runtime status, masked reports, logging controls, watchdog, and route truth in the UI.
Feedback & updates
GitHub Issue Forms without an embedded PAT, plus official GitHub Releases checks without silent APK install.
$ routing
Runtime routing
Frontend protocol and outbound route are separate concepts. The runtime reports the actual route kind rather than reducing everything to “WebSocket”.
01 / appTelegramMTProto Proxy or SOCKS5
→
02 / localProxyService127.0.0.1:1443
→
03 / runtimeGo runtimelibtgwsproxy.so
cf_proxy_ws
direct_ws
cf_worker_ws
tcp_fallback
NOT A VPNThe app does not create a system VPN tunnel and does not route traffic from other applications.
> interface
Application screens
Current screenshots from the project's repository.
$ architecture
Application architecture
Kotlin/Compose handles UI and Android lifecycle; the native Go runtime owns proxy protocols and route execution.
UI
Jetpack Compose main/settings screens, Feedback and Updates, language/theme and diagnostics.
Frontend
Local MTProto Proxy or SOCKS5 frontend on the shared configurable port, default 1443.
Service
Android ProxyService foreground service, notifications, watchdog and network-change reconfiguration.
Bridge
JNA/CGO bridge between Kotlin and native libtgwsproxy.so.
Runtime
Go listener, MTProto transforms, Fake TLS, WebSocket receive path, route chains and pools.
Routing
cf_proxy_ws, direct_ws, cf_worker_ws and tcp_fallback filtered by NetworkRoutePolicy.
> engineering
Engineering decisions
Several constraints are deliberate because they keep route selection observable and predictable.
Route kind is not transport
cf_proxy_ws and direct_ws both use WebSocket transport, but the UI and diagnostics keep them as different route kinds.
Per-network policy is an absolute filter
Android emits route tokens for the current network profile; the Go runtime must not select a route disabled by the active policy.
Bound fragmented WebSocket receive
v1.10.13 reassembles continuation frames and limits individual and accumulated messages to 16 MiB.
Stop after the first successful Worker
Worker failover and session-pool behavior are regression-tested to avoid duplicate connection/refill work.
Foreground service is visible by design
Android requires a foreground notification while the proxy is active; notification modes can be compact, not completely hidden.
No silent self-update
The app checks official releases and opens the validated release page. Download and installation remain under user and Android control.
> technology
Technology stack
KotlinAndroid layer
Gonative runtime
Jetpack Compose + Material 3UI
JNA / CGOnative bridge
Foreground Serviceproxy lifecycle
Gradle 8.2.1build
compileSdk / targetSdk35 / 35
minSdk26
ABIarm64-v8a
> privacy
LOCAL PROXYOnly Telegram proxy traffic is handled.
The application receives connections that Telegram explicitly sends to its local proxy frontend. Runtime collection and persistent file logging are disabled by default.
- No system-wide VPN tunnel
- No interception of other applications
- Logging is opt-in for diagnostics
- Cloudflare Worker is user-configured and optional
- Diagnostic reports should be reviewed before sharing
> security
SECURITY BOUNDARIESKeep credentials and diagnostics bounded.
Sensitive values are masked where supported, release signing material stays outside Git, and feedback does not automatically attach runtime logs, proxy credentials, Telegram data, IP addresses, or secrets.
- No embedded GitHub write PAT
- Release keystore excluded from Git
- Official GitHub Releases update source
- No automatic APK installation
- Proxy secrets and Worker URLs should not be posted publicly
> lineage
Project lineage
This Android implementation started from amurcanov/tg-ws-proxy-android and uses Flowseal/tg-ws-proxy as the reference upstream for the proxy runtime and WebSocket routing concepts. Android-specific lifecycle, route policy, Fake TLS, watchdog, diagnostics, UI and release work are maintained in this fork.
$ stable_release
TgWsProxy Android v1.10.13
The stable v1.10.13 release was published on 25 August 2026 after manual Android acceptance and signed-release verification.
APK SHA-256
D419874BF8C5EAB4E6AB5EDE3CCF2013583314A5AA7E089D79E158145892233A> project links
Development and documentation
GitHub remains the source of truth for code, releases, issues, upstream lineage and technical documentation.