{"id":47595793,"url":"https://github.com/frops/telegram-proxy","last_synced_at":"2026-04-01T18:04:20.183Z","repository":{"id":343719585,"uuid":"1178842836","full_name":"frops/telegram-proxy","owner":"frops","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-11T16:58:49.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-11T19:39:13.134Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T12:28:51.000Z","updated_at":"2026-03-11T16:43:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/frops/telegram-proxy","commit_stats":null,"previous_names":["frops/telegram-proxy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/frops/telegram-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frops%2Ftelegram-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frops%2Ftelegram-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frops%2Ftelegram-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frops%2Ftelegram-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frops","download_url":"https://codeload.github.com/frops/telegram-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frops%2Ftelegram-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-01T18:04:10.644Z","updated_at":"2026-04-01T18:04:20.156Z","avatar_url":"https://github.com/frops.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram MTProto Proxy\n\nEasy-to-deploy MTProto proxy for Telegram with FakeTLS support to bypass DPI blocking.\n\nBuilt on [mtg v2](https://github.com/9seconds/mtg) — a fast and reliable Go-based proxy.\n\n## Features\n\n- **FakeTLS** — traffic is disguised as regular HTTPS, making it indistinguishable from normal web traffic for DPI\n- **Replay attack protection** — built-in defense against active probing\n- **Minimal resources** — runs on a VPS with 512MB RAM and 1 vCPU\n- **Single secret for everyone** — one link to connect all clients\n\n## Requirements\n\n- VPS outside of Russia (DigitalOcean, Hetzner, Vultr, etc.)\n- Docker and Docker Compose\n- Own domain with an A record pointing to server IP (optional, but recommended for better disguise)\n\n## Quick Start\n\n### 1. Prepare domain (optional)\n\nFor better disguise, create an A record for a subdomain pointing to your VPS IP:\n\n```\nproxy.example.com → 123.45.67.89\n```\n\nThis strengthens FakeTLS — DPI will see a legitimate TLS handshake with your domain. The proxy works without your own domain too (`cloudflare.com` is used by default).\n\n### 2. Installation\n\n```bash\ngit clone https://github.com/frops/telegram-proxy.git\ncd telegram-proxy\nbash setup.sh\n```\n\nOr with parameters (non-interactive):\n\n```bash\n# With your own domain\nbash setup.sh --domain proxy.example.com\n\n# With a custom port\nbash setup.sh --domain proxy.example.com --port 8443\n\n# Without a domain — cloudflare.com is used\nbash setup.sh --port 443\n```\n\nThe script will:\n1. Check for Docker\n2. Ask for a FakeTLS domain (or use `--domain`)\n3. Generate a secret\n4. Create configuration\n5. Start the proxy\n6. Output a connection link\n\n### 3. Connect client\n\nAfter startup, the script will output a link like:\n\n```\ntg://proxy?server=123.45.67.89\u0026port=443\u0026secret=ee...\n```\n\nOpen this link on a device with Telegram — the proxy will be added automatically.\n\n**Or manually:** Telegram → Settings → Data and Storage → Proxy → Add Proxy → MTProto\n\n## Management\n\n```bash\n# View logs\ndocker compose logs -f mtg\n\n# Stop\ndocker compose down\n\n# Restart\ndocker compose restart mtg\n\n# Status\ndocker compose ps\n```\n\n## Choosing a FakeTLS domain\n\nBest option is to use **your own domain** with an A record pointing to the server IP. Then DPI will see:\n- TLS SNI: `proxy.example.com`\n- Domain resolves to your server's IP\n- Everything matches, no suspicion\n\nIf you don't have your own domain — no problem. `cloudflare.com` is used by default. DPI rarely checks IP-to-SNI correspondence, so the proxy will work fine.\n\n## Security\n\n- `config.toml` contains the secret and is not committed to git (added to `.gitignore`)\n- The secret is the only authentication; do not share it in public channels\n- Use port 443 for maximum HTTPS disguise\n\n## Using with nginx reverse proxy\n\nIf port 443 is already occupied by nginx (serving other sites), you can route Telegram proxy traffic through nginx using the `stream` module with SNI-based routing.\n\n**Why not a regular `proxy_pass`?** mtg operates at the TCP/TLS level (FakeTLS), not HTTP. A standard nginx `http` block reverse proxy will not work. You need the `stream` module with `ssl_preread` to inspect the TLS SNI header and route traffic accordingly.\n\n### Architecture\n\n```\nClient -\u003e your-domain.com:443\n  -\u003e nginx stream (ssl_preread reads SNI)\n    -\u003e SNI = your-domain.com -\u003e 127.0.0.1:8443 (mtg)\n    -\u003e SNI = anything else   -\u003e 127.0.0.1:8444 (nginx HTTPS)\n```\n\n### Setup\n\n1. Run mtg on a non-standard port with your domain as the FakeTLS domain:\n   ```bash\n   bash setup.sh --domain your-domain.com --port 8443\n   ```\n\n2. Copy the stream block from [`nginx-stream.conf.example`](nginx-stream.conf.example) into your nginx's main `nginx.conf` (at the top level, next to the `http` block).\n\n3. Replace `proxy.example.com` with your actual domain in the `map` block.\n\n4. Change all existing HTTPS server blocks from `listen 443 ssl` to `listen 8444 ssl`. Port 8444 is internal only.\n\n5. Test and reload nginx:\n   ```bash\n   nginx -t \u0026\u0026 nginx -s reload\n   ```\n\n**Important:** The FakeTLS domain in mtg must match the domain in the nginx `map` block. If they don't match, SNI routing will not work.\n\nSee [`nginx-stream.conf.example`](nginx-stream.conf.example) for the full configuration with comments.\n\n## Diagnostics\n\nRun the diagnostic script to check proxy health:\n\n```bash\nbash diagnose.sh\n```\n\nIt checks:\n- Docker status and container health\n- Port binding and firewall rules\n- Connectivity to Telegram data centers\n- TLS handshake\n- Config validity (secret format, FakeTLS prefix)\n- External reachability\n\nThe proxy also has a built-in Docker healthcheck via the stats endpoint (`127.0.0.1:3129`). Check health status:\n\n```bash\ndocker inspect --format='{{.State.Health.Status}}' mtg-proxy\n```\n\n## Troubleshooting\n\n**Container doesn't start:**\n```bash\ndocker compose logs mtg\n```\n\n**Port 443 is occupied:**\n```bash\n# Find out what's using the port\nss -tlnp | grep 443\n# Specify a different port during setup (e.g., 8443)\n```\n\n**Client can't connect:**\n- Run `bash diagnose.sh` for a full check\n- Check that VPS firewall allows port 443 (TCP)\n- Check cloud provider firewall (AWS Security Groups, DigitalOcean Firewall, etc.)\n- Make sure the domain A record points to the correct IP\n- Try connecting from a different network\n\n**Status: unavailable in Telegram:**\n- Most common cause: firewall blocking the port (both OS-level and cloud provider)\n- Verify the port is reachable: `curl -v telnet://YOUR_IP:443` from another machine\n- Check that the proxy can reach Telegram DCs: `bash diagnose.sh` (see \"Telegram DC connectivity\" section)\n\n## Project structure\n\n```\n├── docker-compose.yml            # Docker Compose configuration\n├── config.toml.template          # mtg configuration template\n├── setup.sh                      # Automated setup script\n├── diagnose.sh                   # Diagnostic and troubleshooting script\n├── nginx-stream.conf.example     # Example nginx stream config for SNI routing\n├── LICENSE                       # MIT License\n└── README.md                     # This file\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrops%2Ftelegram-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrops%2Ftelegram-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrops%2Ftelegram-proxy/lists"}