tg-ws-proxy Documentation

TG WS Proxy is a local MTProto proxy for Telegram Desktop designed to accelerate Telegram performance by redirecting traffic through WebSocket connections. It maintains the same encrypted data format and does not require third-party servers.

Traffic Flow: Telegram Desktop → MTProto Proxy (127.0.0.1:1443) → WebSocket → Telegram DC

Key Features:

• Automatically extracts DC ID from MTProto obfuscation init-packets.
• Establishes TLS WebSocket connections to Telegram DCs via Telegram domains.
• Automatically falls back to CfProxy or direct TCP connections if WebSocket is unavailable (302 redirect).

To run the CLI package as a background service using systemd, use the following syntax: sudo systemctl start tg-ws-proxy@<PORT>:<SECRET>.

• Replace <PORT> with your desired port (e.g., 8888).
• Replace <SECRET> with your generated secret. You can generate a 16-byte hex secret using openssl rand -hex 16.

Automatic Configuration

Right-click the tray icon and select «Открыть в Telegram».

If Telegram does not open with the connection automatically:

1. Right-click the tray icon and select «Скопировать ссылку».
2. Send the copied link to your 'Saved Messages' in Telegram.
3. Click the link to connect.

Manual Configuration

1. In Telegram, navigate to Settings → Advanced Settings → Connection Type → Proxy.
2. Add a new proxy with these details:
   • Type: MTProto
   • Server: 127.0.0.1 (or your custom address)
   • Port: 1443 (or your custom port)
   • Secret: Retrieve this from the application settings or logs.

After the first launch, the application minimizes to the system tray. Right-click the tray icon to access the following options:

• Открыть в Telegram (Open in Telegram): Automatically configures the proxy via a tg://proxy link.
• Скопировать ссылку (Copy link): Copies the connection link to your clipboard.
• Перезапустить прокси (Restart proxy): Restarts the proxy without exiting the application.
• Настройки... (Settings...): Opens the GUI configuration editor (manages app version and optional GitHub update checks).
• Открыть логи (Open logs): Opens the log file.
• Выход (Exit): Stops the proxy and closes the application.

To install TG WS Proxy from source using Docker, clone the repository, build the image, and run the container. After starting, you must extract the connection link from the container logs to use it in Telegram.

# Скачиваем репозиторий
git clone https://github.com/Flowseal/tg-ws-proxy.git

# Переходим в папку с проектом
cd tg-ws-proxy

# Собираем образ
docker build -t tg-ws-proxy .

# Запускаем контейнер
docker run -d \
  --name tg-ws-proxy \
  --restart=always \
  -p 1443:1443 \
  tg-ws-proxy:latest

# Получаем ссылку для подключения
docker logs tg-ws-proxy 2>&1 | grep 'tg://proxy'

If automatic configuration fails, manually add the proxy in Telegram Desktop using these settings:

1. Navigate to Settings → Advanced → Connection Type → Proxy.
2. Add a new proxy with the following details:
   • Type: MTProto
   • Server: 127.0.0.1 (or your overridden server address)
   • Port: 1443 (or your overridden port)
   • Secret: Retrieve this from the application settings or the log file.

If certain Telegram data centers are inaccessible, you can use Cloudflare proxying to restore access to features like reactions and certain stickers.

Media Loading Note: If you are on a non-Premium account and photos/videos are not loading, ensure that in the DC → IP configuration block, you only have 4:149.154.167.220 listed. If the Cloudflare proxy is working correctly, media should begin loading again.

To install the pre-built version of TG WS Proxy on macOS:

1. Download TgWsProxy_macos_universal.dmg from the releases page.
2. Open the .dmg file.
3. Drag TG WS Proxy.app into your Applications folder.

Security Note: If macOS prevents the app from opening on the first launch, navigate to System Settings → Privacy & Security → Open Anyway.

System Requirements:

• Intel macOS: 10.15 or newer
• Apple Silicon macOS: 11.0 or newer

You can install the proxy on Arch-based distributions using AUR packages. Choose between the binary version (tg-ws-proxy-bin), the git version (tg-ws-proxy-git), or the CLI version (tg-ws-proxy-cli).

# Installation without an AUR-helper
git clone https://aur.archlinux.org/tg-ws-proxy-bin.git
cd tg-ws-proxy-bin
makepkg -si

# Installation with an AUR-helper (e.g., paru)
paru -S tg-ws-proxy-bin

To route traffic through Nginx to the tg-ws-proxy, use the Nginx stream module with ssl_preread. The domain specified in the --fake-tls-domain parameter of the proxy must point to the same IP address where Nginx is listening.

Use a map block to route traffic based on the SNI (Server Name Indication) to different upstreams. Ensure proxy_protocol on; is enabled in the server block to allow the proxy to receive the client's real IP address.

upstream mtproto {
    server 127.0.0.1:8446;
}

map $ssl_preread_server_name $sni_name {
    hostnames;
    example.com mtproto;
    # Example for xray with selfsni:
    # sub.example.com  www;
    # default xray;
}

server {
    proxy_protocol on;
    set_real_ip_from unix:;
    listen          443;
    proxy_pass      $sni_name;
    ssl_preread     on;
}