<img src="docs/logo.jpg" alt="TeleGO Logo" width="200"> <h1 align="center">TeleGO</h1>  High-performance Telegram MTProxy in Go with TLS fronting <a href="https://github.com/Scratch-net/telego/actions/workflows/test.yml"><img src="https://github.com/Scratch-net/telego/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests"></a> <a href="https://github.com/Scratch-net/telego/actions/workflows/lint.yml"><img src="https://github.com/Scratch-net/telego/actions/workflows/lint.yml/badge.svg?branch=main" alt="Lint"></a> <a href="https://codecov.io/gh/Scratch-net/telego"><img src="https://codecov.io/gh/Scratch-net/telego/branch/main/graph/badge.svg" alt="Coverage"></a> <a href="https://goreportcard.com/report/github.com/Scratch-net/telego"><img src="https://goreportcard.com/badge/github.com/Scratch-net/telego" alt="Go Report Card"></a> <a href="https://github.com/Scratch-net/telego/releases/latest"><img src="https://img.shields.io/github/v/release/Scratch-net/telego?color=blue&label=release" alt="Release"></a> <a href="https://pkg.go.dev/github.com/scratch-net/telego"><img src="https://pkg.go.dev/badge/github.com/scratch-net/telego.svg" alt="Go Reference"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/Scratch-net/telego" alt="License"></a> <a href="#features">Features</a> • <a href="#installation">Installation</a> • <a href="#quick-start">Quick Start</a> • <a href="#configuration">Configuration</a> • <a href="#docker">Docker</a> • <a href="#performance">Performance</a> English | <a href="README.ru.md">Русский</a>

Telegram blocked in your country? TeleGO's TLS fronting makes your proxy indistinguishable from regular HTTPS traffic to censors. Get started in 2 minutes

Features

Networking

Event-driven I/O — Built on gnet with epoll/kqueue for maximum efficiency
Zero-copy relaying — Direct buffer manipulation without intermediate copies
Buffer pooling — Striped sync.Pool design eliminates allocations in hot paths
Optimized TCP — TCP_NODELAY, TCP_QUICKACK, 64KB buffers, SO_REUSEPORT

Security

TLS Fronting — Fetches real certificates from mask host for perfect camouflage
Probe Resistance — Forwards unrecognized clients to mask host (indistinguishable from HTTPS)
Replay Protection — 64-shard LRU cache with TTL expiration (hashicorp/golang-lru)
Key Zeroization — Sensitive data (session IDs, random bytes) zeroed on connection close
Desync Detection — Detects crypto state divergence via abnormal frame sizes
Dual Protocol Support — FakeTLS (ee) and raw Obfuscated2 (dd) with auto-detection on single port

Operations

Multi-user Support — Named secrets with per-user tracking and logging
Connection Tracking — Unique connection IDs for easy log correlation
Connection Limits — Per-IP connection limits and per-user IP limits with smart blocking (only blocks IPs with active connections when evicted, allowing legitimate reconnections)
Prometheus Metrics — Per-user connection counts, traffic, and blocked IP statistics
DC Probing — Automatic RTT-based DC address sorting at startup
Config Hot-Reload — SIGHUP and file watching for runtime config changes
Graceful Shutdown — Clean connection draining on SIGTERM/SIGINT
Structured Logging — JSON and text output with configurable levels

Deployment

Unix Socket Support — Bind to Unix sockets for reverse proxy setups
PROXY Protocol — Accept v1/v2 headers from HAProxy/nginx to preserve client IPs
SOCKS5 Upstream — Route DC connections through SOCKS5 proxy (Hysteria2, VLESS, etc.)

Installation

From Source

git clone https://github.com/Scratch-net/telego.git
cd telego
make build

Pre-built Binaries

Download from Releases.

Go Install

go install github.com/scratch-net/telego/cmd/telego@latest

Quick Start

1. Generate a secret:

telego generate www.google.com
# secret=0123456789abcdef0123456789abcdef  <- put this in config
# ee_link=tg://proxy?server=YOUR_IP&port=443&secret=ee...  <- FakeTLS (recommended)
# dd_link=tg://proxy?server=YOUR_IP&port=443&secret=dd...  <- raw Obfuscated2

2. Create config.toml:

[general]
bind-to = "0.0.0.0:443"

[secrets]
alice = "0123456789abcdef0123456789abcdef"

[tls-fronting]
mask-host = "www.google.com"

3. Run:

telego run -c config.toml -l

The -l flag prints Telegram proxy links with auto-detected public IP.

Protocol Modes

TeleGO supports two MTProxy protocol variants on a single port with auto-detection:

| Mode | Secret Prefix | Description | Best For | |------|---------------|-------------|----------| | FakeTLS (ee) | ee... | TLS-wrapped Obfuscated2 | Maximum stealth, censorship bypass | | Raw (dd) | dd... | Plain Obfuscated2 | Compatibility, lower overhead |

FakeTLS (ee) wraps traffic in TLS 1.3 records, making it indistinguishable from HTTPS. The secret includes the mask hostname for SNI validation. Unrecognized connections are forwarded to the mask host for probe resistance.

Raw (dd) sends Obfuscated2 directly without TLS wrapping. Lower overhead but easier to fingerprint. Useful for compatibility with older clients or when TLS fronting isn't needed.

Both modes use the same 16-byte secret key. The ee or dd prefix in the client link determines which mode the client uses. TeleGO auto-detects the protocol from the first bytes of each connection.

Configuration

Config Reference

[general]
# Network binding (TCP or Unix socket)
bind-to = "0.0.0.0:443"
# bind-to = "/run/telego/telego.sock"  # Unix socket

# Log level: trace, debug, info, warn, error
log-level = "info"

# Accept incoming PROXY protocol headers (from HAProxy/nginx)
# proxy-protocol = false

# Maximum connections per IP+user (0 = unlimited)
# Protects against abuse when many users share one IP (NAT, VPN)
# max-connections-per-ip = 100

# Maximum unique IPs per user (0 = unlimited)
# Prevents secret sharing - limits how many devices/locations can use one secret
# max-ips-per-user = 3

# How long blocked IPs stay blocked (for max-ips-per-user)
# ip-block-timeout = "5m"

# Named secrets (hex format, 32 chars = 16 bytes)
# Generate with: telego generate <hostname>
[secrets]
user1 = "0123456789abcdef0123456789abcdef"
user2 = "fedcba9876543210fedcba9876543210"

# TLS fronting configuration
[tls-fronting]
mask-host = "www.google.com"  # Host to mimic (SNI validation, proxy links)
# mask-port = 443             # Port for mask-host (default: 443)
# cert-host = "127.0.0.1"     # Where to fetch TLS cert (default: mask-host)
# cert-port = 8443            # Cert fetch port (default: mask-port)
# splice-host = "127.0.0.1"   # Forward unrecognized clients here (default: mask-host)
# splice-port = 8080          # Splice port (default: mask-port)
# splice-proxy-protocol = 1   # PROXY protocol to splice: 0=off, 1=v1(text), 2=v2(binary)

# Performance tuning (all optional)
[performance]
prefer-ip = "prefer-ipv4"    # prefer-ipv4, prefer-ipv6, only-ipv4, only-ipv6
idle-timeout = "5m"          # Connection idle timeout (hot-reloadable)
num-event-loops = 0          # 0 = auto (all CPU cores)

# Upstream (DC connection) settings
[upstream]
# socks5 = "127.0.0.1:1080"  # Route DC traffic through SOCKS5 proxy

# Prometheus metrics (optional)
[metrics]
# bind-to = "127.0.0.1:9090"  # Metrics endpoint (empty = disabled)
# path = "/metrics"           # Metrics path

CLI Reference

telego run       Start the proxy server
  -c, --config   Path to config file (required)
  -b, --bind     Override bind address
  -l, --link     Print Telegram proxy links on startup (both ee and dd)

telego generate <hostname>   Generate a new secret for hostname
                             Outputs both ee (FakeTLS) and dd (raw) links

telego version   Show version information

Docker

Docker Hub

docker run -d \
  --name telego \
  -p 443:443 \
  -v /path/to/config.toml:/config.toml \
  scratchnet/telego:latest

Docker Compose

version: '3.8'
services:
  telego:
    image: scratchnet/telego:latest
    container_name: telego
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - ./config.toml:/config.toml:ro
    cap_add:
      - NET_BIND_SERVICE

Build Locally

docker build -f dist/Dockerfile.build -t telego .
docker run -d -p 443:443 -v ./config.toml:/config.toml telego

Behind a Reverse Proxy

TeleGO can run behind HAProxy or nginx using Unix sockets and PROXY protocol:

config.toml:

[general]
bind-to = "/run/telego/telego.sock"
proxy-protocol = true
max-connections-per-ip = 100  # DoS protection
max-ips-per-user = 3          # Sharing protection

[secrets]
user1 = "..."

[tls-fronting]
mask-host = "www.google.com"

HAProxy example:

backend telego
    mode tcp
    server telego /run/telego/telego.sock send-proxy-v2

nginx example:

upstream telego {
    server unix:/run/telego/telego.sock;
}

server {
    listen 443;
    proxy_pass telego;
    proxy_protocol on;
}

Systemd

Install as a systemd service:

sudo make install CONFIG=/etc/telego/config.toml
sudo systemctl enable telego
sudo systemctl start telego

Service file is installed to /etc/systemd/system/telego.service.

Config Hot-Reload

TeleGO supports runtime configurat

Telego

Install / Use

README