Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Flowseal/tg-ws-proxy/llms.txt

Use this file to discover all available pages before exploring further.

Running TG WS Proxy inside Docker is the recommended approach for server-side or headless deployments. The container exposes the proxy on port 1443, restarts automatically on failure, and is fully configured through environment variables — no config files to manage.

​
Setup

1

Clone the repository

git clone https://github.com/Flowseal/tg-ws-proxy.git
cd tg-ws-proxy
2

Build the Docker image

docker build -t tg-ws-proxy .
3

Run the container

docker run -d \
  --name tg-ws-proxy \
  --restart=always \
  -p 1443:1443 \
  tg-ws-proxy:latest
The -d flag runs the container in detached mode. --restart=always ensures it comes back up automatically after a reboot or crash.
4

Retrieve the connection link

docker logs tg-ws-proxy 2>&1 | grep 'tg://proxy'
You will see a line similar to:
tg://proxy?server=172.17.0.2&port=1443&secret=dd68f127db1d...
Use this link to configure Telegram Desktop, or share it with users who should connect through this proxy.

​
Environment Variables

All proxy settings are passed as environment variables at container start time:
VariableDefaultDescription
TG_WS_PROXY_HOST0.0.0.0Interface address the proxy listens on inside the container
TG_WS_PROXY_PORT1443Port the proxy listens on inside the container
TG_WS_PROXY_SECRET"" (empty)32-character hex secret used to authenticate clients; auto-generated when empty
TG_WS_PROXY_DC_IPS2:149.154.167.220 4:149.154.167.220Space-separated list of DC:IP pairs the proxy will forward traffic to

​
Custom Secret

It is good practice to set a fixed secret so the connection link stays stable across container restarts. Generate one with: 
openssl rand -hex 16
Then pass it to the container: 
docker run -d \
  --name tg-ws-proxy \
  --restart=always \
  -p 1443:1443 \
  -e TG_WS_PROXY_SECRET="your_secret_here" \
  tg-ws-proxy:latest

​
Connect Telegram Desktop

Because the proxy is running on a remote host (or on a separate Docker network), the Server address in Telegram Desktop must be the IP or hostname of the Docker host — not 127.0.0.1.
1

Open Telegram proxy settings

In Telegram Desktop go to Settings → Advanced → Connection type, then select Use custom proxy.
2

Add a new proxy

Click Add proxy and fill in the fields:
  • Type: MTProto
  • Server: your Docker host’s public IP or hostname (e.g. 203.0.113.10)
  • Port: 1443 (or the host-side port from -p)
  • Secret: the value of TG_WS_PROXY_SECRET from the logs
3

Save and connect

Click Save, select the new proxy entry, and click Enable.
The Dockerfile uses python:3.12-slim as the runtime base image and installs tini as the container init process. Tini ensures that the proxy receives Unix signals correctly (e.g. SIGTERM on docker stop) and that zombie processes are properly reaped, making the container behave predictably in orchestrated environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us