TG WS Proxy

Skill by ara.so — Daily 2026 Skills collection.

TG WS Proxy is a local SOCKS5 proxy server for Telegram Desktop that reroutes traffic through WebSocket (WSS) connections to Telegram's Data Centers, bypassing network-level blocking without external servers.

Telegram Desktop → SOCKS5 (127.0.0.1:1080) → TG WS Proxy → WSS → Telegram DC

How It Works

1. Starts a local SOCKS5 proxy on 127.0.0.1:1080
2. Intercepts connections to Telegram IP addresses
3. Extracts DC ID from MTProto obfuscation init packet
4. Opens a WebSocket (TLS) connection to the matching DC via Telegram domains
5. Falls back to direct TCP if WebSocket returns a 302 redirect

Installation

From Source (All Platforms)

git clone https://github.com/Flowseal/tg-ws-proxy.git
cd tg-ws-proxy
pip install -e .

Run Console Proxy (No GUI)

tg-ws-proxy

Run with Tray GUI

# Windows
tg-ws-proxy-tray-win

# macOS
tg-ws-proxy-tray-macos

# Linux
tg-ws-proxy-tray-linux

Linux — AUR (Arch-based)

paru -S tg-ws-proxy-bin
# or
git clone https://aur.archlinux.org/tg-ws-proxy-bin.git
cd tg-ws-proxy-bin
makepkg -si

Linux — systemd CLI

sudo systemctl start tg-ws-proxy-cli@1080

Linux — .deb

Download TgWsProxy_linux_amd64.deb from releases and install:

sudo dpkg -i TgWsProxy_linux_amd64.deb

Linux — binary

chmod +x TgWsProxy_linux_amd64
./TgWsProxy_linux_amd64

CLI Reference

tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v]

Examples

# Default startup
tg-ws-proxy

# Custom port
tg-ws-proxy --port 9050

# Specify multiple DCs with IPs
tg-ws-proxy --dc-ip 1:149.154.175.205 --dc-ip 2:149.154.167.220 --dc-ip 4:149.154.167.220

# Verbose debug logging
tg-ws-proxy -v

# Full custom example
tg-ws-proxy --host 0.0.0.0 --port 1080 --dc-ip 2:149.154.167.220 -v

Configuration File

The tray application stores config in a platform-specific location:

• Windows: %APPDATA%/TgWsProxy/config.json
• macOS: ~/Library/Application Support/TgWsProxy/config.json
• Linux: ~/.config/TgWsProxy/config.json (or $XDG_CONFIG_HOME/TgWsProxy/config.json)

config.json structure

{
  "port": 1080,
  "dc_ip": [
    "2:149.154.167.220",
    "4:149.154.167.220"
  ],
  "verbose": false
}

pyproject.toml Script Registration

CLI entry points are declared in pyproject.toml:

[project.scripts]
tg-ws-proxy = "proxy.tg_ws_proxy:main"
tg-ws-proxy-tray-win = "windows:main"
tg-ws-proxy-tray-macos = "macos:main"
tg-ws-proxy-tray-linux = "linux:main"