TheDocumentation 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.
tg-ws-proxy command starts the MTProto WebSocket bridge proxy as a headless console process — no system tray, no GUI. It is the right choice for server deployments, Docker containers, or any environment where a graphical interface is unavailable. All settings that are stored in the tray app’s config.json can be expressed as command-line flags.
Usage
127.0.0.1:1443 with a randomly generated secret and default DC mappings.
Connection settings
IP address to bind and listen on. Use
0.0.0.0 to accept connections from all network interfaces.TCP port to listen on. The same value must be used in the Telegram Desktop proxy settings.
MTProto proxy secret — exactly 32 hexadecimal characters (16 bytes). If omitted, a random secret is generated at startup and printed to the log. The secret is embedded in the
tg://proxy connection link.Generate one with:Maps a Telegram DC number to an IP address. The format is
<dc_number>:<ip_address>, for example 2:149.154.167.220. This flag is repeatable — pass it once per DC you want to configure.Default (when not specified):Cloudflare options
Disables the Cloudflare proxy fallback entirely. When set, the proxy will not attempt to route traffic through Cloudflare-proxied domains if a direct WebSocket connection to a Telegram DC fails.
Custom Cloudflare-proxied domain to use for the CF proxy fallback instead of the built-in default pool. Repeatable — pass it multiple times to supply several domains. See Cloudflare Proxy for DNS setup instructions.
Cloudflare Worker domain for the WebSocket fallback. Worker fallback is tried before the CF proxy fallback. Repeatable — pass it multiple times for multiple workers. See Cloudflare Worker for setup instructions.
Masking
Enables Fake TLS (
ee-secret) masking. The proxy will validate incoming TLS ClientHello messages against the secret and respond with a synthetic ServerHello, making the connection appear as normal HTTPS traffic to the specified SNI domain. The domain must resolve to the server where the proxy is running. See Fake TLS + Nginx for a complete setup guide.Enables acceptance of HAProxy PROXY protocol v1 headers. Use this when the proxy is deployed behind nginx or HAProxy with
proxy_protocol on so that the real client IP is passed through correctly. Required for the Fake TLS + Nginx setup.Performance
Socket send and receive buffer size in kilobytes. The effective size in bytes is
KB × 1024. Values smaller than 4 are clamped to 4.Number of WebSocket connections to pre-establish per configured DC. Set to
0 to disable connection pre-warming. Minimum accepted value is 0.Logging
Enables
DEBUG-level logging. Produces significantly more output than the default INFO level; useful for diagnosing handshake failures or fallback behaviour.Path to a file where logs are written with automatic rotation. When not specified, all output goes to stderr only.
Maximum log file size in megabytes before the file is rotated. Values below
0.032 (32 KB) are clamped to 0.032. Only relevant when --log-file is set.Number of rotated backup log files to keep alongside the main log file.
0 means the file is overwritten in place with no backups. Only relevant when --log-file is set.Examples
Connection link format
After starting, the proxy logs atg://proxy link you can open in Telegram Desktop to configure it automatically. The link format depends on the mode:
Standard (dd-secret):