tg-ws-proxy-telegram-socks5

Q: How do I install tg-ws-proxy-telegram-socks5?

Run npx skills add https://github.com/reason-machines/trending-skills --skill tg-ws-proxy-telegram-socks5 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tg-ws-proxy-telegram-socks5/ (personal) or .claude/skills/tg-ws-proxy-telegram-socks5/ (project).

by reason-machinesBackend & APIs

Local SOCKS5 proxy server that accelerates Telegram Desktop by routing traffic through WebSocket connections to Telegram DCs

Installs: 883
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/trending-skills --skill tg-ws-proxy-telegram-socks5

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads tg-ws-proxy-telegram-socks5 automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

TG WS Proxy

Skill by ara.so — Daily 2026 Skills collection.

TG WS Proxy is a local SOCKS5 proxy server for Telegram Desktop that reroutes traffic through WebSocket (WSS) connections to Telegram's Data Centers, bypassing network-level blocking without external servers.

Telegram Desktop → SOCKS5 (127.0.0.1:1080) → TG WS Proxy → WSS → Telegram DC

How It Works

Starts a local SOCKS5 proxy on 127.0.0.1:1080
Intercepts connections to Telegram IP addresses
Extracts DC ID from MTProto obfuscation init packet
Opens a WebSocket (TLS) connection to the matching DC via Telegram domains
Falls back to direct TCP if WebSocket returns a 302 redirect

Installation

From Source (All Platforms)

git clone https://github.com/Flowseal/tg-ws-proxy.git
cd tg-ws-proxy
pip install -e .

Run Console Proxy (No GUI)

tg-ws-proxy

Run with Tray GUI

# Windows
tg-ws-proxy-tray-win

# macOS
tg-ws-proxy-tray-macos

# Linux
tg-ws-proxy-tray-linux

Linux — AUR (Arch-based)

paru -S tg-ws-proxy-bin
# or
git clone https://aur.archlinux.org/tg-ws-proxy-bin.git
cd tg-ws-proxy-bin
makepkg -si

Linux — systemd CLI

sudo systemctl start tg-ws-proxy-cli@1080

Linux — .deb

Download TgWsProxy_linux_amd64.deb from releases and install:

sudo dpkg -i TgWsProxy_linux_amd64.deb

Linux — binary

chmod +x TgWsProxy_linux_amd64
./TgWsProxy_linux_amd64

CLI Reference

tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v]

Argument	Default	Description
`--port`	`1080`	SOCKS5 proxy port
`--host`	`127.0.0.1`	SOCKS5 proxy bind host
`--dc-ip`	`2:149.154.167.220`, `4:149.154.167.220`	Target IP per DC ID (repeat for multiple)
`-v`, `--verbose`	off	Enable DEBUG logging

Examples

# Default startup
tg-ws-proxy

# Custom port
tg-ws-proxy --port 9050

# Specify multiple DCs with IPs
tg-ws-proxy --dc-ip 1:149.154.175.205 --dc-ip 2:149.154.167.220 --dc-ip 4:149.154.167.220

# Verbose debug logging
tg-ws-proxy -v

# Full custom example
tg-ws-proxy --host 0.0.0.0 --port 1080 --dc-ip 2:149.154.167.220 -v

Configuration File

The tray application stores config in a platform-specific location:

Windows: %APPDATA%/TgWsProxy/config.json
macOS: ~/Library/Application Support/TgWsProxy/config.json
Linux: ~/.config/TgWsProxy/config.json (or $XDG_CONFIG_HOME/TgWsProxy/config.json)

config.json structure

{
  "port": 1080,
  "dc_ip": [
    "2:149.154.167.220",
    "4:149.154.167.220"
  ],
  "verbose": false
}

pyproject.toml Script Registration

CLI entry points are declared in pyproject.toml:

[project.scripts]
tg-ws-proxy = "proxy.tg_ws_proxy:main"
tg-ws-proxy-tray-win = "windows:main"
tg-ws-proxy-tray-macos = "macos:main"
tg-ws-proxy-tray-linux = "linux:main"

Connecting Telegram Desktop

Manual Setup

Open Telegram Desktop
Go to Settings → Advanced → Connection type → Use custom proxy
Click Add Proxy and set:
- Type: SOCKS5
- Server: 127.0.0.1
- Port: 1080
- Username/Password: leave empty
Click Save and enable the proxy

Automatic (Tray GUI)

Right-click the tray icon → "Открыть в Telegram" — this opens a tg://socks deep link that auto-configures Telegram Desktop.

Code Examples

Launching the Proxy Programmatically

from proxy.tg_ws_proxy import main
import threading

# Run proxy in background thread
proxy_thread = threading.Thread(target=main, daemon=True)
proxy_thread.start()

Using the Proxy with Python Requests (via PySocks)

pip install requests[socks]

import requests

proxies = {
    "http":  "socks5h://127.0.0.1:1080",
    "https": "socks5h://127.0.0.1:1080",
}

response = requests.get("https://api.telegram.org/botTOKEN/getMe", proxies=proxies)
print(response.json())

Using with Telethon (MTProto client)

from telethon import TelegramClient
from telethon.network.connection.tcpabridged import ConnectionTcpAbridged
import socks

client = TelegramClient(
    'session',
    api_id=int(os.environ["TG_API_ID"]),
    api_hash=os.environ["TG_API_HASH"],
    proxy=(socks.SOCKS5, '127.0.0.1', 1080)
)

async def main():
    await client.start()
    me = await client.get_me()
    print(me.username)

import asyncio
asyncio.run(main())

Custom DC IP Mapping (Python)

import subprocess

dc_map = {
    1: "149.154.175.205",
    2: "149.154.167.220",
    3: "149.154.175.100",
    4: "149.154.167.220",
    5: "91.108.56.130",
}

dc_args = []
for dc_id, ip in dc_map.items():
    dc_args += ["--dc-ip", f"{dc_id}:{ip}"]

subprocess.Popen(["tg-ws-proxy", "--port", "1080"] + dc_args)

Building Binaries (PyInstaller)

# Windows
pyinstaller packaging/windows.spec

# macOS
pyinstaller packaging/macos.spec

# Linux
pyinstaller packaging/linux.spec

Builds are also produced automatically via GitHub Actions in .github/workflows/build.yml.

Minimum OS Support

Binary	Minimum Version
`TgWsProxy_windows.exe`	Windows 10+
`TgWsProxy_windows_7_64bit.exe`	Windows 7 x64
`TgWsProxy_windows_7_32bit.exe`	Windows 7 x32
`TgWsProxy_macos_universal.dmg` (Intel)	macOS 10.15+
`TgWsProxy_macos_universal.dmg` (Apple Silicon)	macOS 11.0+
`TgWsProxy_linux_amd64`	Linux x86_64 + AppIndicator

Troubleshooting

Telegram still not connecting

Confirm the proxy is running: tg-ws-proxy -v and watch for connection logs
Make sure Telegram Desktop is set to SOCKS5, not HTTP/MTProxy
Try restarting the proxy from the tray menu (Перезапустить прокси)
Check no firewall or other process is blocking port 1080

Port already in use

# Find what's using port 1080
lsof -i :1080        # macOS/Linux
netstat -ano | findstr :1080  # Windows

# Run on a different port
tg-ws-proxy --port 1081

Then update Telegram Desktop's proxy port to 1081.

Windows Defender false positive (Wacatac)

Download the win7 variant — functionally identical, lower detection rate
Or temporarily disable Defender, download, add to exclusions, re-enable
Verify the build on VirusTotal using the file hash

macOS "unverified developer" block

Open System Settings → Privacy & Security
Scroll down and click Open Anyway next to TG WS Proxy

Linux tray icon not visible

AppIndicator is required. Install it:

# Ubuntu/Debian
sudo apt install gir1.2-appindicator3-0.1

# Fedora
sudo dnf install libappindicator-gtk3

WebSocket not available — proxy falls back to TCP

This is expected behavior. If WS returns a 302 redirect, the proxy automatically uses direct TCP. No action needed; Telegram will still connect.

Verbose debug logging

tg-ws-proxy -v

Or set "verbose": true in config.json for the tray app.

FAQ

What does the tg-ws-proxy-telegram-socks5 skill do?

Local SOCKS5 proxy server that accelerates Telegram Desktop by routing traffic through WebSocket connections to Telegram DCs

How do I install tg-ws-proxy-telegram-socks5?

Run npx skills add https://github.com/reason-machines/trending-skills --skill tg-ws-proxy-telegram-socks5 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tg-ws-proxy-telegram-socks5/ (personal) or .claude/skills/tg-ws-proxy-telegram-socks5/ (project).

Which AI agents can use tg-ws-proxy-telegram-socks5?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is tg-ws-proxy-telegram-socks5 safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains tg-ws-proxy-telegram-socks5?

It is published by reason-machines in reason-machines/trending-skills. It has 883 recorded installs.

Popular backend & apis skills

View category →

find-skills

vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

OfficialBackend & APIs4.1M installs

entra-app-registration

microsoft/azure-skills

Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.

OfficialBackend & APIs566.7K installs

google-agents-cli-adk-code

google/agents-cli

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

entra-agent-id

microsoft/azure-skills

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).

OfficialBackend & APIs336.6K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs

tg-ws-proxy-telegram-socks5

Install

Install

Describe the task

Review the result

SKILL.md

TG WS Proxy

How It Works

Installation

From Source (All Platforms)

Run Console Proxy (No GUI)

Run with Tray GUI

Linux — AUR (Arch-based)

Linux — systemd CLI

Linux — .deb

Linux — binary

CLI Reference

Examples

Configuration File

config.json structure

pyproject.toml Script Registration

Connecting Telegram Desktop

Manual Setup

Automatic (Tray GUI)

Code Examples

Launching the Proxy Programmatically

Using the Proxy with Python Requests (via PySocks)

Using with Telethon (MTProto client)

Custom DC IP Mapping (Python)

Building Binaries (PyInstaller)

Minimum OS Support

Troubleshooting

Telegram still not connecting

Port already in use

Windows Defender false positive (Wacatac)

macOS "unverified developer" block

Linux tray icon not visible

WebSocket not available — proxy falls back to TCP

Verbose debug logging

FAQ

More from reason-machines/trending-skills

Popular backend & apis skills