Flowseal/tg-ws-proxy: a local MTProto WebSocket bridge for Telegram Desktop

What tg-ws-proxy is for, and who is meant to run it

Telegram Desktop talks MTProto to Telegram's data centers over TCP. On some networks that path is slow or blocked while ordinary HTTPS traffic to Telegram's domains still gets through. tg-ws-proxy sits on the same machine as the client, accepts an MTProto connection on a local port, and re-sends the same encrypted payload over a WebSocket (TLS) connection to the data center. The README states that data stays encrypted the same way and that no third-party servers are required.

The audience is narrow and specific. The README's quick-start navigation lists Windows, macOS, Linux and Docker, and the release page ships prebuilt binaries: TgWsProxy_windows.exe for Windows 10+ x64, TgWsProxy_windows_arm64.exe, and two Windows 7 builds for x64 and x32. There is also a tray application whose menu offers Open in Telegram, Copy link, Restart proxy, Settings, Open logs and Exit. This is desktop-client tooling. It is not a mobile proxy, and the README says nothing about running it on a phone.

The data flow: local port, DC id extraction, WebSocket, fallback

The README gives the flow as a single line: Telegram Desktop to MTProto proxy on 127.0.0.1:1443, then WebSocket, then the Telegram DC. The steps behind that are stated in the README: the app raises an MTProto proxy on 127.0.0.1:1443, intercepts connections to Telegram IP addresses, extracts the DC ID from the MTProto obfuscation init packet, and opens a WebSocket (TLS) connection to the matching DC through Telegram's domains.

The interesting part is what happens when the WebSocket route is unavailable. According to the README, a 302 redirect causes an automatic switch to CfProxy or a direct TCP connection. That fallback is the difference between a tool that fails closed and one that degrades to whatever still works on the network.

The README also documents a real failure mode rather than hiding it: photos and videos may fail to load. The stated fix is to edit the proxy's DC to IP settings and delete everything except 4:149.154.167.220, and if that does not help, to clear the field entirely. The README attributes the problem to accounts without Premium. When neither fix works, it points to configuring your own domain using the CfProxy instructions.

Running tg-ws-proxy in Docker

The repository ships a Dockerfile with a builder stage on python:3.12-slim that installs cryptography==46.0.5 and certifi into a virtualenv, and a runtime stage that copies the venv, the proxy and utils directories, and docs/README.md plus LICENSE. The runtime image sets TG_WS_PROXY_HOST to 0.0.0.0, TG_WS_PROXY_PORT to 1443, an empty TG_WS_PROXY_SECRET, TG_WS_PROXY_DC_IPS to "2:149.154.167.220 4:149.154.167.220", and an empty TG_WS_PROXY_CF_WORKER. It exposes 1443/tcp and runs as a non-root app user under tini.

The entrypoint assembles the command line from those environment variables. Each space-separated entry in TG_WS_PROXY_DC_IPS becomes a --dc-ip argument, a non-empty secret becomes --secret, and a non-empty worker domain becomes --cfproxy-worker-domain. So the environment variables are the configuration surface:

docker run --rm -p 1443:1443 \
  -e TG_WS_PROXY_SECRET="<your secret>" \
  -e TG_WS_PROXY_DC_IPS="2:149.154.167.220 4:149.154.167.220" \
  tg-ws-proxy

The container binds 0.0.0.0 inside its own network namespace, so publishing the port is what makes it reachable. Note that the default host in the image is not 127.0.0.1; if you publish 1443 on a machine with a public interface, you are exposing an MTProto proxy, and the README's manual setup instructions use 127.0.0.1 for the desktop case.

Installing from source and connecting Telegram Desktop

pyproject.toml declares requires-python >= 3.8 and a hatchling build backend, and it defines three console entry points: tg-ws-proxy maps to proxy.tg_ws_proxy:main, and the tray variants map to windows:main, macos:main and linux:main. The README links a separate BuildFromSource document rather than putting the steps in the main page, so treat the commands below as the packaging metadata's own contract:

python -m venv .venv
source .venv/bin/activate
pip install .
tg-ws-proxy

The proxy entry point starts the server; the tray entry points are what draw the system tray icon. On Linux the README notes that AppIndicator is required for the tray. Once the process is up, the manual client setup is: Telegram, Settings, Advanced settings, Connection type, Proxy, then add a proxy with type MTProto, server 127.0.0.1, port 1443, and the secret from the settings or logs. The automatic route is the tray menu item Open in Telegram, which configures the proxy through a tg://proxy link. If that does not open Telegram with the connection, the README suggests Copy link, sending the link to Saved Messages, and clicking it there.

Antivirus flags, the DC IP field, and other rough edges

The README carries an explicit caution about antivirus reactions: engines frequently flag the application because of the packer. The suggested workarounds are to download the Windows 7 build, which the README says is functionally identical, or to disable the antivirus during download, add an exception, and re-enable it. The README also says to check VirusTotal detections from well-known engines. That is an honest disclosure, and it is also a real cost: you are asking users to add an exception for a binary that opens a listening socket.

The DC IP field is the second rough edge. The media-loading problem is not a bug report the project hides; it is in the README with two escalation steps and a pointer to self-hosting a domain. A tool whose fix for broken media is "delete all entries except one IP" is telling you that the WebSocket path depends on which endpoints your network tolerates.

The third is scope. The README describes partial bypassing, and the pyproject classifiers list Operating System :: OS Independent, but the actual OS support is enumerated per binary in the README: Windows 10+ x64, Windows 10+ ARM64, Windows 7 x64 and x32, Intel macOS 10.15+, Apple Silicon macOS 11.0+, and Linux x86_64. There is no iOS or Android artifact in the release list, and no statement about mobile clients anywhere in the README.

How this differs from a hosted MTProto proxy or a plain VPN

A conventional MTProto proxy is a remote endpoint: you run a client on a VPS or use someone else's, and Telegram connects out to it. The traffic leaves your machine and terminates somewhere you may not control. tg-ws-proxy inverts that. The listener is on 127.0.0.1, and the outbound leg is a WebSocket to Telegram's own domains, so the destination is Telegram rather than an intermediary. The README's claim that no third-party servers are needed follows from that design.

The trade-off is that you inherit the reachability of Telegram's WebSocket domains from your own network. A hosted proxy can be placed on a network that is not filtered; a local bridge cannot route around a network that blocks the domains it needs. The README's 302 fallback to CfProxy or direct TCP is the project's answer to that, and the CfWorker and CfProxy documents exist precisely because some networks need a domain of your own in front of the WebSocket leg.

Maintenance, packaging and licence

The repository is not archived, and the last push was on 2026-09-19, which is two days before this writing. Releases are frequent and small: v1.10.4 and v1.10.3 both landed on 2026-09-19, with v1.10.2 on 2026-09-07. The tray settings dialog includes an optional update check against GitHub, so the upgrade path for binary users is download the new executable rather than run a package manager.

The dependency set is pinned, not ranged: pyperclip==1.9.0, pystray==0.19.5, customtkinter==5.2.2, and version-split pins for psutil, cryptography and Pillow depending on whether the platform is Windows and whether Python is below 3.9. That pinning makes builds reproducible and also means security updates to those libraries arrive only when the project bumps them. The Dockerfile pins cryptography==46.0.5 and certifi separately, so the container and the source install can drift apart.

Licensing is MIT, declared in pyproject.toml as license = { name = "MIT", file = "LICENSE" } with the OSI classifier. MIT is permissive and places few obligations on redistribution; the bundled third-party dependencies carry their own licences, and nothing in the repository states how those are aggregated. That is a question for your own review, not something to infer from the project's own licence field.

Editorial conclusion

Adopt it if you run Telegram Desktop on Windows, macOS or Linux and your problem is a network that blocks Telegram's own endpoints, and you accept that the tool sits between the client and Telegram. Do not adopt it if you need a proxy for Telegram mobile clients, or if you expect it to hide your traffic from Telegram itself. Verify first that your client can reach the WebSocket domains from the machine running the proxy, and check whether the DC IP list needs editing for your account.

Frequently asked questions

Official sources

1. Flowseal/tg-ws-proxy on GitHub
2. Issues
3. License: MIT
4. README
5. Releases