Skip to content

valnesfjord/tg-ws-proxy-rs

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

130 Commits
.cargo
.cargo
 
 
.github/workflows
.github/workflows
 
 
docs
docs
 
 
src
src
 
 
tests
tests
 
 
.dockerignore
.dockerignore
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
Dockerfile
Dockerfile
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

tg-ws-proxy-rs

Telegram MTProto WebSocket Bridge Proxy — a Rust vibecoded port of Flowseal/tg-ws-proxy.

Listens for Telegram Desktop's MTProto connections on a local port and tunnels them through WebSocket (TLS) connections to Telegram's DC servers.

Telegram Desktop → MTProto (TCP 1443) → tg-ws-proxy-rs → WS (TLS 443) → Telegram DC
                                                         ↘ CF proxy (kws{N}.{cf-domain}) → Telegram DC  (WS via Cloudflare)
                                                         ↘ CF Worker (*.workers.dev) → Telegram DC  (TCP tunnel via Cloudflare)
                                                         ↘ upstream MTProto proxy → Telegram DC  (WS fallback)
                                                         ↘ direct TCP :443 → Telegram DC          (last resort)

Why Rust?

Python original This port
Runtime CPython required Single static binary
Memory ~30–50 MB ~3–5 MB
CPU Higher Lower (compiled)
OpenWrt Needs Python install Just copy the binary
Static build No Yes (musl)

Quick Start

Pre-built binaries

Download from the Releases page.

Build from source

# Debug build
cargo build

# Optimised release build
cargo build --release

# Static binary for Linux x86_64 (e.g. for Docker scratch images)
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

The release binary is at target/release/tg-ws-proxy (or target/<target>/release/tg-ws-proxy for cross-compiled targets).

Cross-platform builds with cargo-zigbuild

cargo-zigbuild uses the Zig compiler as a drop-in C cross-linker so you can build for every platform from a single Linux or macOS host without installing any platform SDKs.

# Install cargo-zigbuild and Zig
pip install ziglang        # or: brew install zig
cargo install cargo-zigbuild

# Add all required Rust targets in one shot
rustup target add \
  x86_64-unknown-linux-musl \
  aarch64-unknown-linux-musl \
  armv7-unknown-linux-musleabihf \
  mipsel-unknown-linux-musl \
  x86_64-apple-darwin \
  aarch64-apple-darwin \
  x86_64-pc-windows-gnu

# Build for all platforms
cargo zigbuild --release --target x86_64-unknown-linux-musl       # Linux x86-64 (musl static)
cargo zigbuild --release --target aarch64-unknown-linux-musl      # Linux / OpenWrt ARM64
cargo zigbuild --release --target armv7-unknown-linux-musleabihf  # OpenWrt ARMv7
cargo zigbuild --release --target mipsel-unknown-linux-musl       # OpenWrt MIPS LE
cargo zigbuild --release --target x86_64-apple-darwin             # macOS Intel
cargo zigbuild --release --target aarch64-apple-darwin            # macOS Apple Silicon
cargo zigbuild --release --target x86_64-pc-windows-gnu           # Windows x86-64

Note: Building macOS targets (*-apple-darwin) requires the macOS SDK (XCode Command Line Tools). On Linux you can use osxcross to supply the SDK and then set SDKROOT / MACOSX_DEPLOYMENT_TARGET appropriately before running cargo zigbuild.

Usage

tg-ws-proxy [OPTIONS]
Flag Default Description
--port <PORT> 1443 Listen port
--host <HOST> 127.0.0.1 Listen address
--link-ip <IP> auto-detected IP shown in the tg:// link (see Router deployment)
--secret <HEX> random 32 hex-char MTProto secret
--listen-faketls-domain <DOMAIN> — Accept inbound clients with ee FakeTLS and advertise this SNI domain in the link
--dc-ip <DC:IP> DC2 + DC4 Target IP per DC (repeatable); omit when using --cf-domain to let CF proxy handle all DCs
--buf-kb <KB> 256 Socket buffer size
--pool-size <N> 4 Pre-warmed WS connections per DC
--cf-domain <DOMAIN> — Cloudflare-proxied domain(s) for alternative WS routing, comma-separated (see CF Proxy)
--cf-worker-domain <DOMAIN> — Cloudflare Worker domain for TCP-tunnel fallback, no owned domain required (see Cloudflare Worker)
--default-domains off Fetch and use the built-in CF proxy domain list from GitHub (no Cloudflare setup needed, see Default domains)
--cf-priority off Try CF proxy before direct WS for all DCs (see CF Proxy)
--cf-balance off Round-robin load balance across multiple --cf-domain values (see CF Proxy)
--max-connections <N> auto Max concurrent client connections (auto-computed from ulimit -n)
--mtproto-proxy <HOST:PORT:SECRET> — Upstream MTProto proxy fallback (repeatable)
--log-file <PATH> — Write logs to a file instead of stderr (no ANSI color codes)
-q / --quiet off Suppress all log output
-v / --verbose off Debug logging
--danger-accept-invalid-certs off Skip TLS verification

Every flag has a matching environment variable (TG_PORT, TG_HOST, TG_SECRET, TG_BUF_KB, TG_POOL_SIZE, TG_MAX_CONNECTIONS, TG_QUIET, TG_VERBOSE, TG_SKIP_TLS_VERIFY, TG_LINK_IP, TG_LISTEN_FAKETLS_DOMAIN, TG_MTPROTO_PROXY, TG_LOG_FILE, TG_CF_DOMAIN, TG_CF_WORKER_DOMAIN, TG_CF_PRIORITY, TG_CF_BALANCE, TG_DEFAULT_DOMAINS).

Examples

# Standard run (random secret, DC 2 + 4)
tg-ws-proxy

# Custom port and extra DCs
tg-ws-proxy --port 9050 --dc-ip 1:149.154.175.205 --dc-ip 2:149.154.167.220

# With upstream MTProto proxy fallback
tg-ws-proxy --mtproto-proxy proxy.example.com:443:ddabcdef1234567890abcdef1234567890

# With Cloudflare proxy domain (WS fallback via Cloudflare CDN)
tg-ws-proxy --cf-domain yourdomain.com

# With Cloudflare Worker (free workers.dev TCP tunnel fallback)
tg-ws-proxy --cf-worker-domain random-symbols-1234.username.workers.dev

# CF proxy only: omit --dc-ip so CF proxy handles all DCs
tg-ws-proxy --cf-domain yourdomain.com --cf-priority

# Use default CF domains from GitHub — no Cloudflare setup required
tg-ws-proxy --default-domains

# Default domains + CF priority (try CF first, fall back to direct WS)
tg-ws-proxy --default-domains --cf-priority

# Default domains + your own domain (yours goes first)
tg-ws-proxy --cf-domain yourdomain.com --default-domains

# Multiple CF domains (tried in order) with CF priority over direct WS
tg-ws-proxy --cf-domain proxy.net,example.com --cf-priority

# Multiple CF domains with round-robin load balancing
tg-ws-proxy --cf-domain proxy.net,example.com --cf-balance

# CF balance + priority: round-robin across CF domains, tried before direct WS
tg-ws-proxy --cf-domain proxy.net,example.com --cf-balance --cf-priority

# CF priority: CF proxy is tried first, falls back to direct WS on failure
tg-ws-proxy --dc-ip 2:149.154.167.220 --cf-domain yourdomain.com --cf-priority

# Multiple upstream proxies (tried in order until one succeeds)
tg-ws-proxy \
  --mtproto-proxy proxy.example.com:443:ddabcdef1234567890abcdef1234567890 \
  --mtproto-proxy other.example.net:8888:dddeadbeef01234567deadbeef01234567

# Router deployment: listen on all interfaces, let all LAN devices use the proxy
tg-ws-proxy --host 0.0.0.0

# Public home server: inbound ee FakeTLS, backend still WSS to Telegram Web
tg-ws-proxy --host 0.0.0.0 --port 443 --listen-faketls-domain www.yandex.ru

# Equivalent: pass a full ee secret directly
tg-ws-proxy --host 0.0.0.0 --port 443 --secret ee<32-hex-key><hex-encoded-domain>

# Verbose logging
tg-ws-proxy -v

# Log to a file instead of stderr (no garbled ANSI codes — useful on Windows)
tg-ws-proxy --log-file proxy.log

# All options via environment variables (useful for Docker / systemd)
TG_PORT=1443 TG_SECRET=deadbeef... tg-ws-proxy

On startup the proxy prints a tg://proxy?... link you can paste into Telegram Desktop to configure it automatically. With --listen-faketls-domain, the printed link uses secret=ee<key><domain_hex>; otherwise it uses the classic dd<key> padded MTProto secret.

Inbound FakeTLS listener

For public home servers where DPI blocks raw inbound MTProto, enable inbound FakeTLS:

tg-ws-proxy --host 0.0.0.0 --port 443 --listen-faketls-domain www.yandex.ru

This changes only the client-facing transport:

Telegram client → ee FakeTLS → tg-ws-proxy-rs → WSS/TLS → kws*.web.telegram.org

The proxy accepts the TLS ClientHello, validates the FakeTLS HMAC, sends a synthetic TLS ServerHello, unwraps TLS Application Data records, and then passes the recovered MTProto init into the existing WebSocket backend path.

Upstream MTProto proxy fallback

When WebSocket connections to Telegram are blocked, the proxy can route traffic through an external MTProto proxy before falling back to direct TCP:

WS (preferred) → upstream MTProto proxy → direct TCP (last resort)

Pass one or more --mtproto-proxy HOST:PORT:SECRET flags (or a comma-separated list in TG_MTPROTO_PROXY). Proxies are tried in the order given; if one fails it enters a 60-second cooldown so subsequent connections skip it without delay.

# Padded-intermediate proxy (dd prefix)
tg-ws-proxy --mtproto-proxy proxy.example.com:443:ddabcdef1234567890abcdef1234567890

# FakeTLS proxy (ee prefix — domain-fronting transport)
tg-ws-proxy --mtproto-proxy proxy.example.com:443:ee<32-hex-key><hex-encoded-hostname>

# Multiple proxies (tried in order until one succeeds)
tg-ws-proxy \
  --mtproto-proxy proxy.example.com:443:ddabcdef1234567890abcdef1234567890 \
  --mtproto-proxy other.example.net:8888:dddeadbeef01234567deadbeef01234567

# Or via environment variable (comma-separated)
TG_MTPROTO_PROXY="proxy.example.com:443:ddabcdef1234...,other.example.net:8888:dddeadbeef..." tg-ws-proxy

ℹ️ Secret format — pass the secret exactly as shown in the tg://proxy link

Public MTProto proxies advertise secrets with a 1-byte prefix that tells the proxy which transport mode to use. Copy the full secret as-is — prefix included:

Prefix Meaning Example
dd Padded-intermediate transport ddabcdef1234567890abcdef1234567890
ee FakeTLS (domain-fronting) transport ee + 32 hex key chars + hex-encoded hostname
(none) Plain transport (legacy, 32 hex chars) abcdef1234567890abcdef1234567890

In the tg://proxy?server=...&secret= link the secret= value already contains the correct prefix. Copy everything after secret= and pass it directly to --mtproto-proxy.

Cloudflare Proxy

When Telegram's IP ranges are blocked by your ISP, you can route WebSocket traffic through Cloudflare using --cf-domain. This requires only a domain name — no server-side component.

# Use your own Cloudflare-proxied domain
tg-ws-proxy --cf-domain yourdomain.com

# Multiple domains (tried in order, first has highest priority)
tg-ws-proxy --cf-domain primary.net,backup.com

# Multiple domains with round-robin load balancing
tg-ws-proxy --cf-domain primary.net,backup.com --cf-balance

# CF-only mode: omit --dc-ip so CF proxy handles all DCs
tg-ws-proxy --cf-domain yourdomain.com

# CF priority: try CF proxy before direct WS, with WS as fallback
tg-ws-proxy --dc-ip 2:149.154.167.220 --cf-domain yourdomain.com --cf-priority

# Or via environment variable
TG_CF_DOMAIN=yourdomain.com tg-ws-proxy

The proxy will try the CF path as a fallback after direct WebSocket fails. With --cf-priority, the CF proxy is tried before direct WebSocket for all DCs.

--cf-balance — round-robin load balancing

When multiple --cf-domain values are given, connections normally always start with the first domain. Adding --cf-balance distributes connections evenly across all configured CF domains using round-robin selection:

tg-ws-proxy --cf-domain d1.example.com,d2.example.com,d3.example.com --cf-balance
# connection 0 → tries d1, then d2, then d3
# connection 1 → tries d2, then d3, then d1
# connection 2 → tries d3, then d1, then d2

The remaining domains still serve as ordered fallbacks if the primary one fails, so resilience is unchanged. Has no effect when only one CF domain is configured. Can be combined with --cf-priority:

# Round-robin CF load balancing, tried before direct WS
tg-ws-proxy --cf-domain d1.example.com,d2.example.com --cf-balance --cf-priority

One-time domain setup (do this in the Cloudflare dashboard):

  1. In SSL/TLS → Overview set mode to Flexible.

  2. In DNS → Records add these proxied (🔶) A records:

    Name IPv4 address
    kws1 149.154.175.50
    kws1-1 149.154.175.50
    kws2 149.154.167.51
    kws2-1 149.154.167.51
    kws3 149.154.175.100
    kws3-1 149.154.175.100
    kws4 149.154.167.91
    kws4-1 149.154.167.91
    kws5 149.154.171.5
    kws5-1 149.154.171.5
    kws203 91.105.192.100
    kws203-1 91.105.192.100

See docs/CfProxy.md for full instructions.

Cloudflare Worker

Cloudflare Worker mode is an alternative to --cf-domain when you do not own a domain. Deploy the Worker script from docs/CfWorker.md, copy its *.workers.dev domain, and pass it to the proxy:

tg-ws-proxy --cf-worker-domain random-symbols-1234.username.workers.dev

Or via environment variable:

TG_CF_WORKER_DOMAIN=random-symbols-1234.username.workers.dev tg-ws-proxy

The Worker accepts an outer WebSocket connection from tg-ws-proxy-rs, opens a raw TCP connection to the selected Telegram DC IP, and forwards WebSocket message payloads as TCP bytes:

tg-ws-proxy-rs → wss://<worker>/apiws?dst=<dc-ip>&dc=<dc>&media=<0|1>
Cloudflare Worker → TCP <dc-ip>:443

For DCs with a configured direct WebSocket target, direct WS is tried first and the Worker is used only after that path fails. For DCs without a direct WS target, the Worker is tried before the regular Cloudflare proxy/default domains and the remaining fallbacks.

Default domains

Don't want to configure your own Cloudflare DNS zone? Use --default-domains to automatically fetch a pre-configured, working list of CF proxy domains from the upstream repository:

# No Cloudflare account or DNS setup required
tg-ws-proxy --default-domains

# Enable CF priority so CF path is tried first
tg-ws-proxy --default-domains --cf-priority

# Combine with your own domain (yours gets highest priority)
tg-ws-proxy --cf-domain yourdomain.com --default-domains

# Test the fetched domains before starting the proxy
tg-ws-proxy --default-domains --check

Or via environment variable:

TG_DEFAULT_DOMAINS=true tg-ws-proxy

At startup the proxy fetches an obfuscated domain list from Flowseal/tg-ws-proxy, deobfuscates it, and appends the decoded domains after any explicit --cf-domain entries. If the fetch fails (network not yet available, GitHub unreachable) the proxy falls back to a small built-in list and logs a warning — it will still start normally.

Note: These are community-maintained domains; availability may change over time. For maximum reliability, consider setting up your own Cloudflare zone (see docs/CfProxy.md).

Router deployment

Run the proxy on your router with --host 0.0.0.0 so it accepts connections from all LAN devices:

tg-ws-proxy --host 0.0.0.0 --port 1443

When --host 0.0.0.0 is used, the proxy auto-detects the router's LAN IP address and uses it in the generated tg:// link, so you can share the same link with every device on your network.

If auto-detection picks the wrong interface, override it explicitly:

tg-ws-proxy --host 0.0.0.0 --link-ip 192.168.1.1

Note: The default --host 127.0.0.1 only accepts connections from the machine running the proxy. Other devices on the network will not be able to connect unless you change this to 0.0.0.0 (or the router's LAN IP).

Telegram Desktop Setup

  1. Settings → Advanced → Connection type → Use custom proxy
  2. Add MTProto proxy:
    • Server: 127.0.0.1
    • Port: 1443 (or your --port)
    • Secret: shown in the proxy startup log

Or use the tg://proxy?... link that is printed on startup.

Cross-compilation for OpenWrt

OpenWrt uses musl libc and runs on MIPS, ARM, and ARM64 CPUs. Building a fully static Rust binary requires:

  1. A C cross-compiler for your target (used by ring/aws-lc-sys)
  2. The matching Rust target

ARM64 (aarch64) — e.g. GL.iNet MT6000, Banana Pi R4

# Install the cross toolchain (Ubuntu/Debian)
apt-get install gcc-aarch64-linux-gnu

# Add the Rust target
rustup target add aarch64-unknown-linux-musl

# Uncomment the [target.aarch64-unknown-linux-musl] section in .cargo/config.toml,
# then build:
cargo build --release --target aarch64-unknown-linux-musl

ARM (armv7) — e.g. older GL.iNet routers, some TP-Link models

apt-get install gcc-arm-linux-gnueabihf
rustup target add armv7-unknown-linux-musleabihf
# Uncomment the armv7 section in .cargo/config.toml
cargo build --release --target armv7-unknown-linux-musleabihf

MIPS LE — e.g. TP-Link WR series

apt-get install gcc-mipsel-linux-gnu
rustup target add mipsel-unknown-linux-musl
# Uncomment the mipsel section in .cargo/config.toml
cargo build --release --target mipsel-unknown-linux-musl

Using cross (easier alternative)

cross uses Docker to manage toolchains:

cargo install cross
cross build --release --target aarch64-unknown-linux-musl

OpenWrt procd init script

Create /etc/init.d/tg-ws-proxy:

#!/bin/sh /etc/rc.common
USE_PROCD=1
START=90
STOP=10

PROG=/usr/local/bin/tg-ws-proxy

start_service() {
    procd_open_instance
    procd_set_param command "$PROG" --host 0.0.0.0 --port 1443
    procd_set_param respawn
    procd_set_param stdout 1
    procd_set_param stderr 1
    procd_close_instance
}
chmod +x /etc/init.d/tg-ws-proxy
/etc/init.d/tg-ws-proxy enable
/etc/init.d/tg-ws-proxy start

How it works

  1. Telegram Desktop connects to the proxy on 127.0.0.1:1443.
  2. The proxy reads the 64-byte MTProto obfuscation handshake, validates the secret, and extracts the target DC id and transport protocol.
  3. A WebSocket connection is opened to wss://kwsN.web.telegram.org/apiws (using the DC-specific domain as TLS SNI but routing TCP to the configured IP).
  4. The relay init packet is sent to Telegram, and bidirectional bridging begins with AES-256-CTR re-encryption (client keys ↔ relay keys).
  5. If WebSocket is unavailable and Cloudflare Worker is configured, the proxy can open wss://<worker>/apiws?dst=<dc-ip> and tunnel raw TCP traffic to the DC via the Worker.
  6. If Worker is unavailable or not configured, the proxy tries the Cloudflare proxy path (wss://kwsN.{cf-domain}/apiws) if --cf-domain is configured.
  7. If CF paths are unavailable or not configured, each upstream MTProto proxy is tried in order (generating a fresh client handshake with the upstream's secret so it can route to the correct DC).
  8. If no upstream proxy is configured or all fail, the proxy falls back to direct TCP on port 443.
  9. A small pool of pre-connected WebSocket connections is maintained per DC to reduce connection latency for subsequent clients.

Project structure

src/
  main.rs              — Entry point, CLI parsing, server startup, banner
  config.rs            — ProxyConfig struct, argument parsing, env-var aliases
  crypto.rs            — MTProto obfuscation: handshake parsing, relay init generation,
                         AES-256-CTR key derivation and cipher construction
  splitter.rs          — MTProto packet splitter for correct WebSocket framing
  ws_client.rs         — WebSocket client for Telegram DC connections (IP routing + SNI)
  pool.rs              — Pre-warmed WebSocket connection pool per DC
  proxy.rs             — Client handler, re-encryption bridge, TCP fallback logic
  default_domains.rs   — Fetches and deobfuscates the default CF proxy domain list
docs/
  CfProxy.md           — Cloudflare DNS proxy setup
  CfWorker.md          — Cloudflare Worker TCP tunnel setup
.cargo/
  config.toml          — Cross-compilation target presets (commented out)

Configuration via environment

TG_HOST=0.0.0.0
TG_PORT=1443
TG_SECRET=0123456789abcdef0123456789abcdef
TG_POOL_SIZE=4
TG_BUF_KB=256
TG_MAX_CONNECTIONS=64
TG_QUIET=true
TG_VERBOSE=false
TG_CF_DOMAIN=yourdomain.com
TG_CF_WORKER_DOMAIN=random-symbols-1234.username.workers.dev
TG_CF_PRIORITY=false
TG_CF_BALANCE=false
TG_DEFAULT_DOMAINS=false
TG_LOG_FILE=/var/log/tg-ws-proxy.log
TG_MTPROTO_PROXY=proxy.example.com:443:ddabcdef1234567890abcdef1234567890

Windows console — no garbled characters

On Windows the console does not enable ANSI/VT colour codes by default, which caused log lines to show symbols like ←[32m around the log level. This is fixed: ANSI escape codes are automatically disabled when running on Windows or when stderr is not a terminal (e.g. output is piped or redirected).

If you prefer completely clean logs or want to capture them to a file, use --log-file:

tg-ws-proxy --log-file proxy.log
# or
set TG_LOG_FILE=proxy.log && tg-ws-proxy

License

MIT

About

Telegram MTProto WebSocket Bridge Proxy — a Rust vibecoded port of Flowseal/tg-ws-proxy

Resources

Readme

License

MIT license
Activity

Stars

91 stars

Watchers

8 watching

Forks

7 forks
Report repository

Releases 21

v1.5.1 Latest
May 31, 2026
+ 20 releases

Packages

 
 
 

Contributors

Languages