scratchnet/telego repository overview

⁠telEgo

High-performance Telegram MTProxy in Go with Telegram Middle-End, TLS fronting, and native WEB protocol support.

• Source: github.com/Scratch-net/telego⁠
• Releases: github.com/Scratch-net/telego/releases⁠
• Middle-End guide: docs/middle-end.md⁠
• WEB proxy guide: docs/web-proxy.md⁠
• Docker examples: examples⁠
• License: Apache-2.0

The image uses telego as its entry point. It contains a static binary and no shell.

⁠Supported image tags

Release v0.6.8 publishes these tags:

• scratchnet/telego:v0.6.8 — fixed release
• scratchnet/telego:v0.6 — latest v0.6.x release
• scratchnet/telego:v0 — latest v0.x release
• scratchnet/telego:latest — moving image from a release or a successful main build

The current manifests support Linux on AMD64, ARM64, and ARMv7.

For repeatable deployments, use a fixed release tag. The latest tag can contain unreleased changes from main.

⁠Custom paths for WEB in v0.6.8

The optional web-proxy.base-path lets separate instances share one hostname and HTTPS port. The Telego path and Nginx route must match. The generate command accepts --web-base-path with --web-host. Read the path guide⁠ before deployment.

The gateway installer and WEB examples now select websocket, which shares one connection across Telegram streams. Repeat installations preserve the saved carrier. Explicit carrier values remain unchanged, and an absent carrier still selects https. The browser bridge can recover after a carrier failure or server restart, within a 15-second total limit per attempt.

This release also corrects configuration reload, TLS cache refresh, connection closure, WEB memory bounds, and metrics listener errors. Telego rejects unknown TOML keys, negative limits, and invalid TLS ports. Zero retains its documented default or unlimited meaning.

Existing WEB installations need the corrected Nginx fallback configuration as well as the Telego update. Updating the binary or image does not update Nginx. Reconnect WEB clients after the upgrade to load the new browser code. Read the v0.6.8 release notes⁠ for the Nginx change and complete upgrade instructions.

⁠Generate a secret

Replace www.google.com with the FakeTLS mask hostname:

docker run --rm scratchnet/telego:v0.6.8 \
  generate www.google.com

To also print Telegram WEB proxy links, add the public WEB hostname:

docker run --rm scratchnet/telego:v0.6.8 \
  generate www.google.com --web-host proxy.example.com

The command prints one base secret. Store the 32-character hexadecimal value in the configuration without the ee or dd prefix.

Each name in [secrets] has one base key. Telego uses that name for per-user tracking. The ee, dd, and WEB links use forms of the same base key.

⁠Run MTProxy

Create config.toml:

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

[secrets]
alice = "0123456789abcdef0123456789abcdef"

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

Start the container:

docker run -d \
  --name telego \
  --restart unless-stopped \
  -p 443:443 \
  -v "$PWD/config.toml:/config.toml:ro" \
  scratchnet/telego:v0.6.8 \
  run -c /config.toml -l

The -l option prints the Telegram proxy links during startup:

docker logs telego

⁠Docker Compose for MTProxy

services:
  telego:
    image: scratchnet/telego:v0.6.8
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - ./config.toml:/config.toml:ro
    command: ["run", "-c", "/config.toml", "-l"]

Start the service:

docker compose config --quiet
docker compose up -d
docker compose logs telego

⁠Run MTProxy and WEB proxy

The native WEB proxy needs a DNS hostname, a valid TLS certificate, and Nginx.

By default, Telego owns public port 443. With separate ports, Nginx owns port 443 and sends WEB traffic to Telego.

Do not publish the private WEB listener to the Internet.

⁠Managed gateway

Use the managed gateway for a new VPS. It stores configuration and certificates on the host and renews the certificate automatically.

curl -fsSL https://raw.githubusercontent.com/Scratch-net/telego/main/examples/gateway/install.sh \
  | sh -s -- --domain proxy.example.com --email [email protected]

The script generates the secret, requests the first certificate, starts the services, and prints the proxy links.

By default, MTProxy and WEB share public port 443. Add --mtproxy-port 9443 to keep WEB on 443 and move MTProxy.

With this option, WEB clients use proxy.example.com:443. MTProxy clients use proxy.example.com:9443.

Add --no-web to install MTProxy without the WEB listener. The gateway keeps the ordinary TLS probe site.

Read the managed gateway guide⁠ for updates, backups, and removal.

⁠Manual Compose setup

The repository contains a complete Compose stack for all four WEB carrier modes:

git clone https://github.com/Scratch-net/telego.git
cd telego/examples/web-proxy

Replace proxy.example.com in these files:

• docker-compose.yml;
• telego.toml;
• nginx/nginx.conf.

Generate the secret and WEB links:

docker run --rm scratchnet/telego:v0.6.8 \
  generate proxy.example.com --web-host proxy.example.com

Add the base secret to telego.toml. Then issue the first certificate while port 80 is free:

mkdir -p certbot/conf certbot/lib certbot/www

docker run --rm -p 80:80 \
  -v "$PWD/certbot/conf:/etc/letsencrypt" \
  -v "$PWD/certbot/lib:/var/lib/letsencrypt" \
  certbot/certbot certonly --standalone --non-interactive --agree-tos \
  --email [email protected] -d proxy.example.com

Start and validate the services:

docker compose config --quiet
docker compose up -d nginx
docker compose exec -T nginx nginx -t
docker compose up -d
docker compose ps
docker compose logs telego

The log must contain WEB proxy started.

The example selects websocket, which shares one connection across Telegram streams. Its Nginx configuration forwards WebSocket upgrades. websocket-lanes remains available for separate stream queues, with additional connections and handshakes.

Set [web-proxy].carrier to one of these values:

• https;
• https-lanes;
• websocket;
• websocket-lanes.

Read the complete WEB proxy guide⁠ before you adapt the Nginx configuration or add an existing website.

⁠Update the container

For a Compose installation, set the Telego image to scratchnet/telego:v0.6.8 in the Compose file. Then update the service:

docker compose pull telego
docker compose up -d --force-recreate telego
docker compose logs telego

WEB proxy support stays disabled until you set [web-proxy].enabled = true.

ME starts automatically unless [middle-end].enabled = false. During ME setup or failure, new clients use direct DC connections. INFO logs report the ME result.