Use this file to discover all available pages before exploring further.
TG WS Proxy (v1.7.1) is a local MTProto proxy that bridges Telegram Desktop traffic over WebSocket connections, improving connectivity in restricted networks. It runs entirely on your own machine — no third-party servers required. Follow the steps below to install, launch, and connect Telegram Desktop in under two minutes.
Windows builds are occasionally flagged as false positives by antivirus software due to the PyInstaller packer used to bundle the application. If your antivirus blocks the download or prevents the executable from running, add the file to your antivirus exclusions and re-download. You can inspect all detections on VirusTotal and verify that no major antivirus engine flags it. Alternatively, download the Windows 7 build — it is functionally identical and is typically flagged less often.
Double-click the downloaded .exe to launch. On first run an instruction window opens automatically. The application then minimises to the system tray.
Go to the GitHub Releases page and download TgWsProxy_macos_universal.dmg (universal binary for both Apple Silicon and Intel).Minimum supported versions:
Intel Mac: macOS 10.15 (Catalina) or later
Apple Silicon: macOS 11.0 (Big Sur) or later
Open the .dmg image.
Drag TG WS Proxy.app to your Applications folder.
Launch the app. If macOS shows a security prompt, open System Settings → Privacy & Security and click Open Anyway.
The tray icon requires AppIndicator support. If your desktop environment does not have it, run the proxy in headless CLI mode instead (see the CLI tab).
Build and run the proxy from the published source:
# Clone the repositorygit clone https://github.com/Flowseal/tg-ws-proxy.gitcd tg-ws-proxy# Build the imagedocker build -t tg-ws-proxy .# Run the containerdocker run -d \ --name tg-ws-proxy \ --restart=always \ -p 1443:1443 \ tg-ws-proxy:latest# Retrieve the connection linkdocker logs tg-ws-proxy 2>&1 | grep 'tg://proxy'
The log output contains a ready-to-use tg://proxy?... link. Configure optional settings with environment variables:
Once the proxy is running, point Telegram Desktop at it using one of the two methods below.Option 1 — Automatic (recommended)Right-click (or click) the TG WS Proxy tray icon and choose Open in Telegram. Telegram Desktop opens with the proxy pre-configured and asks you to confirm the connection. Click Enable and you are done.If Telegram does not open automatically:
Choose Copy Link from the tray menu.
Paste the link into your Saved Messages chat in Telegram and click it.
Confirm the connection prompt.
Option 2 — Manual
Open Telegram Desktop and go to Settings → Advanced → Connection Type → Use custom proxy.
Click Add proxy and fill in the fields:
Field
Value
Type
MTProto
Server
127.0.0.1
Port
1443
Secret
Copy from the proxy tray menu (Settings) or from the log file
Click Save and then Enable.
3
Verify the connection
After enabling the proxy, Telegram Desktop shows a green connection indicator in the connection type settings. You can also inspect the proxy log to confirm traffic is flowing:
Tray app: right-click the tray icon and choose Open Logs.
CLI mode: logs are printed to stderr by default. Add --log-file proxy.log to write them to a file.
A successful session looks like this in the log:
12:34:56 INFO [127.0.0.1:54321] DC2 -> pool hit via 149.154.167.22012:34:57 INFO [127.0.0.1:54321] DC2 WS session closed: ^1.2KB (3 pkts) v18.4KB (12 pkts) in 2.3s
If you see WS connect failed lines followed by fallback, the primary WebSocket path is blocked in your network and the proxy has automatically switched to a Cloudflare-proxied fallback — this is expected behaviour and connections will still work.
Enable verbose logging with the -v flag (tg-ws-proxy -v) or via Settings → Verbose logging in the tray app to see full handshake details and per-DC pool activity.
