Tg Ws Proxy Telegram Socks5
Run a local SOCKS5 proxy so Telegram Desktop reaches DCs over WebSocket when direct MTProto traffic is blocked.
Overview
tg-ws-proxy-telegram-socks5 is an agent skill for the Operate phase that installs and runs a local SOCKS5-to-WebSocket proxy so Telegram Desktop works through blocking networks.
Install
npx skills add https://github.com/aradotso/trending-skills --skill tg-ws-proxy-telegram-socks5What is this skill?
- Local SOCKS5 on 127.0.0.1:1080 terminating into WSS tunnels to Telegram DCs
- MTProto obfuscation init used to derive DC ID for the correct websocket endpoint
- Direct TCP fallback when WebSocket returns HTTP 302 redirect
- Install from source via pip install -e . after git clone
- Tray GUIs: tg-ws-proxy-tray-win, tg-ws-proxy-tray-macos, and Linux tray variant
- Default local SOCKS5 endpoint 127.0.0.1:1080
- 3 platform tray launch variants (Windows, macOS, Linux)
Adoption & trust: 784 installs on skills.sh; 31 GitHub stars; 0/3 security scanners passed (skills.sh audits).
What problem does it solve?
Telegram Desktop cannot connect because MTProto is filtered, but you still need Desktop—not just mobile VPN workarounds.
Who is it for?
Solo builders in restricted networks who want a self-hosted Telegram acceleration path documented step-by-step for their agent.
Skip if: Browser-only Telegram, team-wide corporate proxy design, or legal jurisdictions where circumventing blocks is prohibited.
When should I use this skill?
User asks to set up tg-ws-proxy, fix Telegram proxy issues, bypass blocking with WebSocket, or install the SOCKS5 Telegram tunnel from source.
What do I get? / Deliverables
A local SOCKS5 listener routes Telegram traffic over WSS to the matching DC with optional tray GUI for daily use.
- Running tg-ws-proxy or tray process
- Working Desktop connection via WSS to Telegram DCs
Recommended Skills
Journey fit
How it compares
Local Python SOCKS5 bridge to Telegram DCs—not a generic commercial VPN installer skill.
Common Questions / FAQ
Who is tg-ws-proxy-telegram-socks5 for?
Developers and operators who use Telegram Desktop for community or alerts and need WebSocket-based routing when direct TCP to Telegram fails.
When should I use tg-ws-proxy-telegram-socks5?
During operate when connectivity breaks mid-incident, when onboarding a new machine in a filtered region, or when debugging SOCKS settings for Desktop.
Is tg-ws-proxy-telegram-socks5 safe to install?
It runs locally and pulls from a public GitHub repo; verify the source, Python env isolation, and Security Audits on this Prism page before install.
SKILL.md
READMESKILL.md - Tg Ws Proxy Telegram Socks5
# TG WS Proxy > Skill by [ara.so](https://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) ```bash git clone https://github.com/Flowseal/tg-ws-proxy.git cd tg-ws-proxy pip install -e . ``` ### Run Console Proxy (No GUI) ```bash tg-ws-proxy ``` ### Run with Tray GUI ```bash # Windows tg-ws-proxy-tray-win # macOS tg-ws-proxy-tray-macos # Linux tg-ws-proxy-tray-linux ``` ### Linux — AUR (Arch-based) ```bash 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 ```bash sudo systemctl start tg-ws-proxy-cli@1080 ``` ### Linux — .deb Download `TgWsProxy_linux_amd64.deb` from releases and install: ```bash sudo dpkg -i TgWsProxy_linux_amd64.deb ``` ### Linux — binary ```bash chmod +x TgWsProxy_linux_amd64 ./TgWsProxy_linux_amd64 ``` --- ## CLI Reference ```bash tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v] ``` | Argument | Default | Description | |---|---|---| | `--port` | `1080` | SOCKS5 proxy port | | `--host` | `127.0.0.1` | SOCKS5 proxy bind host | | `--dc-ip` | `2:149.154.167.220`, `4:149.154.167.220` | Target IP per DC ID (repeat for multiple) | | `-v`, `--verbose` | off | Enable DEBUG logging | ### Examples ```bash # 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 ```json { "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`: ```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" ``` --- ## Connecting Telegram Desktop ### Manual Setup 1. Open Telegram Desktop 2. Go to **Settings → Advanced → Connection type → Use custom proxy** 3. Click **Add Proxy** and set: - **Type:** SOCKS5 - **Server:** `127.0.0.1` - **Port:** `1080` - **Username/Password:** leave empty 4. Click **Save** and enable the proxy ### Automatic (Tray GUI) Right-click the tray icon → **"Открыть в Telegram"** — this opens a `tg://socks` deep link that auto-configures Telegram Desktop. --- ## Code Examples ### Launching th