# Mirrly TG Proxy for Android
**Local routing gateway for Telegram powered by the native Rust engine (mirrlyengine) with MTProto, SOCKS5, and multi-uplink tunneling support (Cloudflare Worker WSS, WARP MASQUE HTTP/3, AmneziaWG, VLESS, WARP Cascade) without system VPN**
**[ π·πΊ Π ΡΡΡΠΊΠΈΠΉ ](README.md)** | **[ π¬π§ English ](README_EN.md)**
[](https://developer.android.com)
[](https://kotlinlang.org)
[](https://developer.android.com/jetpack/compose)
[](mirrlyengine)
[](https://workers.cloudflare.com)
[](https://developer.android.com/ndk)
[](https://github.com/joycecurcirt539-dot/Mirrly-TG-Proxy/releases)
[](#7-application-ui)
[](CHANGELOG.md)
[](https://github.com/joycecurcirt539-dot/Mirrly-TG-Proxy/releases)
[](https://github.com/joycecurcirt539-dot/Mirrly-TG-Proxy/stargazers)
[](https://github.com/joycecurcirt539-dot/Mirrly-TG-Proxy/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/joycecurcirt539-dot/Mirrly-TG-Proxy/issues)
[](https://t.me/WhyOkyHb)
[](#15-security-and-terms-of-use)
[](tools/deploy-worker/worker.js)
[](tools/deploy-worker)
[](CHANGELOG.md)
[](TERMS_OF_USE.md)
[](LICENSE)
*Telegram traffic routing powered by the native mirrlyengine core (Rust/Tokio). Supports MTProto and SOCKS5 protocols, multi-uplink architecture (Cloudflare Worker WSS, VLESS, WARP MASQUE HTTP/3, AmneziaWG, WARP Cascade), discrete FSM network stabilization, 4 MB buffer flow control, and secure preflight diagnostics. Runs locally on the device without root privileges and without creating a system VPN tunnel.*
---
## Table of Contents
1. [About Mirrly TG Proxy](#1-about-mirrly-tg-proxy)
2. [How It Works](#2-how-it-works)
3. [Uplink Modes](#3-uplink-modes)
4. [Key Features & Architecture Modules](#4-key-features--architecture-modules)
5. [System Architecture](#5-system-architecture)
6. [Supported Telegram Clients](#6-supported-telegram-clients)
7. [Application UI](#7-application-ui)
8. [Quick Start & Installation](#8-quick-start--installation)
9. [Configuration & Parameters](#9-configuration--parameters)
10. [Cloudflare Worker Setup & Deployment](#10-cloudflare-worker-setup--deployment)
11. [Project Structure & Building from Source](#11-project-structure--building-from-source)
12. [Development Activity Graph](#12-development-activity-graph)
13. [Star History](#13-star-history)
14. [Project Roadmap & Chronology](#14-project-roadmap--chronology)
15. [Security and Terms of Use](#15-security-and-terms-of-use)
16. [Acknowledgements & Hall of Fame](#16-acknowledgements--hall-of-fame)
---
## 1. About Mirrly TG Proxy
**Mirrly TG Proxy** is a free and open-source Android application serving as a high-performance local proxy gateway for Telegram traffic. The application addresses unstable connectivity, protocol throttling, media download slowdowns, and DPI filtering imposed by ISPs and mobile carriers.
The app **does not use** the system `VpnService` for routing Telegram and **does not intercept** third-party device traffic. Telegram connects to a local socket on the device (`127.0.0.1:1443` for MTProto or `127.0.0.1:10808` for SOCKS5) handled by the native `mirrlyengine` core (Rust/Tokio). The engine encapsulates packets into secure external tunnels and relays them to Telegram data centers via Cloudflare Edge Anycast, private Cloudflare Workers, VLESS, or custom tunnels.
---
### Feature Status & Maturity Levels
#### 1. Production-Ready Features (Stable)
* **Dual Local Protocols for Telegram**:
* *MTProto* (port `1443`): FakeTLS domain masquerading (`ee` / `dd`), persistent connection pool (`WsPool`), and direct interaction with Anycast CDN.
* *SOCKS5* (port `10808`): Transparent TCP relay with username/password subnegotiation (RFC 1928 / RFC 1929), domain name resolution, IPv4/IPv6 support, and voice/video calls.
* **Stable Uplink Modes**:
* `WORKER`: Tunneling via Cloudflare Worker over WebSocket TLS 1.3 on port 443 with Anti-Open-Relay security rules.
* `VLESS`: VLESS over WebSocket masqueraded as standard HTTPS traffic on port 443, supporting CDN domain pools and Reality.
* `SOCKS5`: Direct TCP stream relaying through secure upstreams.
* `HYBRID`: Automatic connection failover when the primary upstream becomes unavailable.
* **Networking & Stability Core**:
* *Telegram DC-Affinity Engine*: Direct session routing to Telegram DCs (DC1βDC5) preventing repeated cryptographic handshakes.
* *Trust Policy & Node Isolation*: Isolation of private VPS configurations from public relay fallback (`allowPublicRelayFallbackForPrivateVps`).
* *Discrete FSM Network State Machine*: Three-stage state machine (`NORMAL`, `DEGRADED`, `RECOVERING`) with anti-flapping filters (5β10s hysteresis, 30β60s cooldown).
* *Network Generation Guard*: Epoch-based socket and DNS cache invalidation during network switches (Wi-Fi β Cellular).
* *Bounded Flow Control*: 4 MB write buffer in JS Worker and Rust core with watermark backpressure (prevents WebSocket 1009 frame errors during high-volume media transfers).
* *Smart Connect*: 2β3 second preflight diagnostic check before establishing connections.
* **UI & Localization**:
* *Dual-Level Settings*: Simple Mode for standard usage and Advanced Mode for socket tuning (`TCP_NODELAY`, socket buffers, TLS).
* *Full Bilingual Support*: Complete Russian and English localizations (`values-en`), per-app language selection on Android 13+ (`locales_config`).
* *Onboarding Wizard*: Step-by-step introduction for first-time users.
* *Official Telegram Channel*: Integrated screen for project community updates (`@WhyOkyHb`).
* *Safe Diagnostic Report*: Monospace report generator with automatic token, password, and private domain redaction (`Zero Secret Leak`).
* *Error Taxonomy*: User-friendly localization and machine-readable error codes for logs.
* *Cryptographic Integrity Verification*: Native C++ NDK signature validation (`SignatureVerifier`) and automated SHA-256 hash checks via `UpdateChecker`.
#### 2. Experimental Features (In Testing / ISP Dependent)
* **MASQUE Mode (Anycast HTTP/3)**: Direct tunneling via Cloudflare WARP using `CONNECT-UDP` and QUIC datagrams. Dependent on UDP/Anycast reachability on the local carrier.
* **AWG Mode (AmneziaWG Anycast)**: Obfuscated WireGuard Anycast designed to bypass DPI (`H1..H4`, `Jc`, `I1` initialization, custom INI import for private VPS).
* **WARP Cascade Mode (`WARP_CASCADE`)**: Intelligent fallback sequence: `MASQUE` -> `AWG` -> `Worker WSS`.
* **WARP Pipeline Profiler**: Millisecond-precision latency profiling across 4 tunnel startup phases.
* **WARP Account Manager**: Client-side device registration and Anycast endpoint scanning.
#### 3. In Active Development (Preview)
* **System VPN Mode (`VpnModeScreen` / `MirrlyVpnService`)**: Kinetic UI preview with orbital ring animation for future device-wide traffic protection (Telegram proxying remains completely autonomous and does not require system VPN).
* **In-App Speed Test (`TunnelSpeedTestScreen` / `SpeedTestInDevDialog`)**: Built-in throughput measurement module.
---
## 2. How It Works
The application operates two independent local gateways powered by the native **mirrlyengine** (Rust/Tokio):
### Pipeline 1: MTProto Gateway (`127.0.0.1:1443`) β Direct Anycast CDN Tunneling
1. The Telegram client connects to `127.0.0.1:1443` using the MTProto FakeTLS protocol (with an `ee` / `dd` secret key).
2. The native `mirrlyengine` core performs FakeTLS demultiplexing, extracting the destination Telegram Data Center (DC1βDC5) and stream type (messages or media).
3. The `WsPool` connection pool borrows or establishes a persistent WebSocket connection to official Telegram Web gateways (`kws1..kws5.web.telegram.org:443/apiws`) through Anycast CDN.
4. Edge server selection is handled by the DoH race resolver (`dns.rs`), Happy Eyeballs (RFC 8305), and the latency-based balancer (`balancer.rs`).
5. **Zero Worker Quota Consumption**: MTProto communicates directly with Telegram Web Anycast CDN edge servers, bypassing Cloudflare Workers and consuming 0 requests from daily worker quotas.
### Pipeline 2: SOCKS5 Gateway (`127.0.0.1:10808`) β Multi-Uplink Route Supervisor
1. The Telegram client connects to `127.0.0.1:10808` via standard SOCKS5 with mandatory RFC 1929 authentication (username/password).
2. Supported commands:
* `CONNECT (0x01)`: Proxies TCP streams for chats, channels, bots, and media downloads;
* `UDP ASSOCIATE (0x03)`: Tunnels UDP datagrams for Telegram VoIP audio and video calls.
3. The `RouteSupervisor` dispatcher routes the stream into the active Uplink transport:
* **`WORKER`**: Encapsulates TCP into WebSocket TLS 1.3 to a personal Cloudflare Worker (or developer pool), which opens raw TCP sockets to target DCs via the `cloudflare:sockets` API;
* **`VLESS`**: Relays traffic over VLESS WebSocket (TLS 1.3 :443) or Reality directly to a private VPS or CDN;
* **`MASQUE`** *(in testing)*: Anycast tunneling via HTTP/3 QUIC (`CONNECT-UDP`) with an embedded `smoltcp` userspace TCP/IP stack into Cloudflare WARP;
* **`AWG`** *(in testing)*: Obfuscated WireGuard Anycast designed to bypass DPI (`I1`, `Jc`, `H1..H4`) with the `smoltcp` stack;
* **`WARP_CASCADE` / `HYBRID`**: Intelligent multi-stage fallback across transports during radio degradation or ISP blocks.
---
## 3. Uplink Modes (SOCKS5 Orchestration)
In SOCKS5 mode, the `RouteSupervisor` module in `mirrlyengine` manages the following upstream transports (MTProto uses its dedicated Anycast CDN pool `WsPool`):
| Mode (`UplinkMode`) | Status | Protocol & Port | Description |
| :--- | :--- | :--- | :--- |
| **`WORKER`** | **Stable** | WebSocket TLS 1.3 (`:443`) | Traffic is encapsulated into WebSocket to Cloudflare Worker, where `cloudflare:sockets` opens direct TCP sockets to Telegram DCs and VoIP reflectors. Protected by Anti-Open-Relay filters. |
| **`VLESS`** | **Stable** | VLESS WSS TLS 1.3 (`:443`) | VLESS protocol disguised as standard HTTPS traffic on port 443. Supports CDN domain pools, private VPS endpoints, and Reality. |
| **`HYBRID`** | **Stable** | WSS + Failover | Primary connection via Cloudflare Worker WSS with seamless automatic failover if upstream errors or rate limits (HTTP 429) occur. |
| **`MASQUE`** | **Testing** | HTTP/3 QUIC (`:443`) | Direct Anycast tunneling via Cloudflare WARP MASQUE (`CONNECT-UDP`) with userspace `smoltcp` stack. Dependent on UDP reachability. |
| **`AWG`** | **Testing** | WireGuard UDP | Obfuscated WireGuard Anycast designed to bypass DPI (`H1..H4`, `Jc`, `I1`) with `smoltcp` stack. Supports custom INI imports for private servers. |
| **`WARP_CASCADE`** | **Testing** | MASQUE + AWG + WSS | Multi-tier failover cascade: priority start with MASQUE, automatic switch to AWG on UDP drop, and emergency fallback to Worker WSS. |
---
## 4. Key Features & Architecture Modules
### Network Stabilization & Anti-Flapping (FSM)
* **Discrete Finite State Machine (FSM)**:
* `NORMAL`: Normal latency, zero packet loss, standard socket policy.
* `DEGRADED`: Verified radio channel degradation (RTT > 500 ms, jitter > 60 ms, or burst losses).
* `RECOVERING`: Smooth stabilization stage following network interface handovers.
* **Hysteresis Window**: Profile switches require 5β10 seconds of continuous confirmation to prevent oscillatory switching.
* **Cool-down Period**: 30β60 second re-trigger block applied after any configuration adjustment to eliminate routing resonance.
### Network Generation Guard
Assigns an incrementing epoch counter (`network_generation`) to each connection state. When transitioning between Wi-Fi and Cellular networks, obsolete sockets and DNS records from prior epochs are discarded immediately to eliminate stale socket stalls.
### Pre-Flight Smart Connect
Performs a fast 2β3 second validation sequence upon activation:
1. Fast validation of DoH and system DNS resolvers;
2. Reachability verification of uplink endpoint pools;
3. Selection of the lowest-latency, least-loaded node;
4. Real-time stage indication in the UI ("Optimizing route...").
### Dual-Level Settings (Simple vs Advanced UX)
* **Simple Mode (Default)**: Clean interface focused on core preferences: proxy mode (MTProto / SOCKS5), uplink selector, sleep timer, scheduler, auto-start on boot, language, and theme.
* **Advanced Mode**: Toggleable mode providing full control over socket flags (`TCP_NODELAY`: Auto / On / Off), buffer tuning, WebSocket pool capacity, Happy Eyeballs parameters, Anycast IP overrides, and custom AWG/VLESS parameters.
### Secure Diagnostic Report (Zero Secret Leak)
* Monospace configuration report generation via `DiagnosticReportScreen`.
* **Strict Redaction**: Automated masking of SOCKS5 passwords, authentication tokens, WireGuard private keys (`[REDACTED]`), private IPs, and worker subdomains (`***.workers.dev`).
* One-click export to clipboard or system `ShareSheet` for GitHub Issue submissions.
### Error Taxonomy
* **User Layer (UI & Notifications)**: Contextual descriptions in the selected language ("Worker daily quota exceeded", "DNS server unreachable", "Mobile data disconnected").
* **Engineering Layer (Report & Logs)**: Machine-readable error codes:
* `WORKER_QUOTA_EXCEEDED` β Cloudflare Free tier limit reached (HTTP 429, 1015, 1027);
* `DNS_RESOLUTION_UNAVAILABLE` β Domain resolution failure;
* `SOCKS5_AUTH_REJECTED` β RFC 1929 authentication error;
* `CLOUDFLARE_EDGE_BLOCKED` β Upstream TCP reset at carrier DPI level;
* `WARP_HANDSHAKE_TIMEOUT` β WireGuard UDP packets dropped;
* `NETWORK_INTERFACE_DOWN` β All device network interfaces offline.
### Bounded Flow Control for High-Bandwidth Media
* 4 MB write buffer limit in JS Worker and Rust core (`MAX_PENDING_WRITE_BYTES = 4 * 1024 * 1024`).
* Asynchronous FIFO queue processing for Blob and ArrayBuffer chunks.
* Full protection against WebSocket frame disconnects (code 1009) during concurrent media and video uploads.
### Deep Dormancy & Battery Guard
* **Deep Dormancy**: Upon total network loss (Airplane mode, no signal), the service closes active sockets and suspends periodic DoH and ping cycles, instantly resuming when connectivity returns.
* **Battery Guard**: Configurable auto-shutdown when battery drops below a specified threshold (5%, 10%, 15%, 20%, 25%) or Android enters power saver mode while disconnected from power.
### SOCKS5 RFC 1928 / RFC 1929 Authentication
* Native username/password subnegotiation implemented directly in `mirrlyengine`.
* Mandatory credential setup dialog on first SOCKS5 launch to prevent open proxy exposure.
* Instant connection links: `tg://socks?server=127.0.0.1&port=10808&user=...&pass=...`.
---
## 5. System Architecture
```mermaid
flowchart TD
subgraph ClientLayer ["1. Telegram Clients on Device (Android)"]
TG_MTProto["Telegram Client (MTProto)
[](https://github.com/joycecurcirt539-dot/Mirrly-TG-Proxy)
---
## 13. Star History