The Ultimate Telegram MTProto Proxy Manager

One script. Full control. Zero hassle.

Quick Start • Features • Comparison • Telegram Bot • CLI Reference • Changelog

MTProxyMax is a full-featured Telegram MTProto proxy manager powered by the telemt 3.x Rust engine. It wraps the raw proxy engine with an interactive TUI, a complete CLI, a Telegram bot for remote management, per-user access control, traffic monitoring, proxy chaining, and automatic updates — all in a single bash script.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/SamNet-dev/MTProxyMax/main/install.sh)"

Most MTProxy tools give you a proxy and a link. That's it. MTProxyMax gives you a full management platform:

• 🔐 Multi-user secrets with individual bandwidth quotas, device limits, and expiry dates
• 🤖 Telegram bot with 17 commands — manage everything from your phone
• 🗂️ Replication — sync config to slave servers automatically via rsync+SSH
• 🖥️ Interactive TUI — no need to memorize commands, menu-driven setup
• 📊 Prometheus metrics — real per-user traffic stats, not just iptables guesses
• 🔗 Proxy chaining — route through SOCKS5 upstreams for extra privacy
• 🔄 Auto-recovery — detects downtime, restarts automatically, alerts you on Telegram
• 🐳 Pre-built Docker images — installs in seconds, not minutes

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/SamNet-dev/MTProxyMax/main/install.sh)"

The interactive wizard walks you through everything: port, domain, first user secret, and optional Telegram bot setup.

curl -fsSL https://raw.githubusercontent.com/SamNet-dev/MTProxyMax/main/mtproxymax.sh -o mtproxymax
chmod +x mtproxymax
sudo ./mtproxymax install

mtproxymax           # Open interactive TUI
mtproxymax status    # Check proxy health

Your proxy traffic looks identical to normal HTTPS traffic. The Fake TLS V2 engine mirrors real TLS 1.3 sessions — per-domain profiles, real cipher suites, dynamic certificate lengths, and realistic record fragmentation. The TLS handshake SNI points to a cover domain (e.g., cloudflare.com), making it indistinguishable from regular web browsing to any DPI system.

Traffic masking goes further — when a non-Telegram client probes your server, the connection is forwarded to the real cover domain. Your server responds exactly like cloudflare.com would.

Each user gets their own secret key with a human-readable label:

• Add/remove users instantly — config regenerates and proxy hot-reloads
• Enable/disable access without deleting the key
• Rotate a user's secret — new key, same label, old link stops working
• QR codes — scannable directly in Telegram

Fine-grained limits enforced at the engine level:

Tip: Use conns for device limits, not ips. Each Telegram app opens exactly 1 connection (multiplexed internally), so conns 3 = max 3 devices. IP limits are less reliable because mobile users roam between cell towers (briefly showing 2 IPs for 1 device), and multiple devices behind the same WiFi share 1 IP. Use ips as a secondary anti-sharing measure.

Traffic and quotas are lifetime (cumulative), not monthly. They don't auto-reset. Use mtproxymax secret reset-traffic <label> to manually reset counters, or rotate the secret.

mtproxymax secret setlimits alice 100 5 10G 2026-12-31

mtproxymax secret setlimit alice conns 1    # Single device only
mtproxymax secret setlimit family conns 5   # Family — up to 5 devices

mtproxymax secret add shared-link
mtproxymax secret setlimits shared-link 50 30 10G 2026-06-01

mtproxymax secret add alice
mtproxymax secret add bob
mtproxymax secret add charlie

# Each person gets their own link — revoke individually
mtproxymax secret setlimit alice conns 2    # 2 devices
mtproxymax secret setlimit bob conns 1      # 1 device
mtproxymax secret setlimit charlie conns 3  # 3 devices

mtproxymax secret disable bob    # Temporarily cut off
mtproxymax secret enable bob     # Restore access

mtproxymax secret rotate alice   # New key, old link dies instantly

mtproxymax secret remove bob     # Permanent removal

Full proxy management from your phone. Setup takes 60 seconds:

mtproxymax telegram setup

Automatic alerts:

• 🔴 Proxy down → instant notification + auto-restart attempt
• 🟢 Proxy started → sends connection details + QR codes
• 📊 Periodic traffic reports at your chosen interval

Keep multiple proxy servers in sync automatically. The master pushes config changes to all slaves via rsync+SSH on a configurable interval. Slaves receive secrets.conf, upstreams.conf, instances.conf, and config.toml — their own role settings and local state are never overwritten.

Setup takes two commands:

# On master — run wizard, select Master, add slave
mtproxymax replication setup

# On slave — run wizard, select Slave
mtproxymax replication setup

How it works:

• Master generates a self-contained sync script at /opt/mtproxymax/mtproxymax-sync.sh
• A systemd timer fires every N seconds (default: 60) and runs the sync
• On change — proxy container on slave is automatically restarted
• settings.conf and replication.conf are always excluded — slave role is never overwritten

mtproxymax replication status     # Show role, timer state, last sync
mtproxymax replication sync       # Trigger immediate sync
mtproxymax replication logs       # View sync log
mtproxymax replication test       # Test SSH connectivity to all slaves
mtproxymax replication promote    # Promote slave to master (failover)

Roles:

Route traffic through intermediate servers:

# Route 20% through Cloudflare WARP
mtproxymax upstream add warp socks5 127.0.0.1:40000 - - 20

# Route through a backup VPS
mtproxymax upstream add backup socks5 203.0.113.50:1080 user pass 80

# Hostnames are supported (resolved by the engine)
mtproxymax upstream add remote socks5 my-proxy.example.com:1080 user pass 50

Supports SOCKS5 (with auth), SOCKS4, and direct routing with weight-based load balancing. Addresses can be IPs or hostnames.

Prometheus metrics give you real per-user stats:

mtproxymax traffic       # Per-user breakdown
mtproxymax status        # Overview with connections count

• Bytes uploaded/downloaded per user
• Active connections per user
• Cumulative tracking across restarts

mtproxymax geoblock add ir    # Block Iran
mtproxymax geoblock add cn    # Block China
mtproxymax geoblock list      # See blocked countries

IP-level CIDR blocklists enforced via iptables — traffic is dropped before reaching the proxy.

mtproxymax adtag set <hex_from_MTProxyBot>

Get your ad-tag from @MTProxyBot. Users see a pinned channel — you earn from the proxy.

mtproxymax engine status              # Current engine version
mtproxymax engine rebuild             # Force rebuild engine image
mtproxymax rebuild                    # Force rebuild from source

Engine updates are delivered through mtproxymax update. Pre-built multi-arch Docker images (amd64 + arm64) are pulled automatically. Source compilation is the automatic fallback.

Telegram Client
      │
      ▼
┌─────────────────────────┐
│  Your Server (port 443) │
│  ┌───────────────────┐  │
│  │  Docker Container  │  │
│  │  ┌─────────────┐  │  │
│  │  │   telemt     │  │  │  ← Rust/Tokio engine
│  │  │  (FakeTLS)   │  │  │
│  │  └──────┬──────┘  │  │
│  └─────────┼─────────┘  │
│            │             │
│     ┌──────┴──────┐     │
│     ▼             ▼     │
│  Direct      SOCKS5     │  ← Upstream routing
│  routing     chaining   │
└─────────┬───────────────┘
          │
          ▼
   Telegram Servers


Master-Slave Replication (optional):

  Master Server              Slave Server(s)
  ┌──────────────┐           ┌──────────────┐
  │ mtproxymax   │──rsync──▶ │ mtproxymax   │
  │ (systemd     │   +SSH    │ (receives    │
  │  timer 60s)  │           │  config)     │
  └──────────────┘           └──────────────┘

mtproxymax install              # Run installation wizard
mtproxymax uninstall            # Remove everything
mtproxymax start                # Start proxy
mtproxymax stop                 # Stop proxy
mtproxymax restart              # Restart proxy
mtproxymax status               # Show proxy status
mtproxymax menu                 # Open interactive TUI

mtproxymax secret add <label>           # Add user
mtproxymax secret remove <label>        # Remove user
mtproxymax secret list                  # List all users
mtproxymax secret rotate <label>        # New key, same label
mtproxymax secret enable <label>        # Re-enable user
mtproxymax secret disable <label>       # Temporarily disable
mtproxymax secret link [label]          # Show proxy link
mtproxymax secret qr [label]            # Show QR code
mtproxymax secret setlimit <label> <type> <value>  # Set individual limit
mtproxymax secret setlimits <label> <conns> <ips> <quota> [expires]  # Set all limits
mtproxymax secret reset-traffic <label|all>  # Reset traffic counters

mtproxymax port [get|<number>]          # Get/set proxy port
mtproxymax ip [get|auto|<address>]      # Get/set custom IP for proxy links
mtproxymax domain [get|clear|<host>]    # Get/set FakeTLS domain
mtproxymax adtag set <hex>              # Set ad-tag
mtproxymax adtag remove                 # Remove ad-tag

mtproxymax replication setup            # Interactive wizard (master/slave/standalone)
mtproxymax replication status           # Role, timer state, last sync, slave list
mtproxymax replication add <host> [port] [label]   # Register a slave server
mtproxymax replication remove <host_or_label>      # Remove a slave
mtproxymax replication list             # List all slaves
mtproxymax replication enable           # Enable sync timer
mtproxymax replication disable          # Disable sync timer
mtproxymax replication sync             # Trigger immediate sync
mtproxymax replication test [host]      # Test SSH connectivity to slave(s)
mtproxymax replication logs             # Show sync log
mtproxymax replication reset            # Remove all replication config
mtproxymax replication promote          # Promote slave to master (failover)

mtproxymax geoblock add <CC>            # Block country
mtproxymax geoblock remove <CC>         # Unblock country
mtproxymax geoblock list                # List blocked countries
mtproxymax upstream list                # List upstreams
mtproxymax upstream add <name> <type> <host:port> [user] [pass] [weight]
mtproxymax upstream remove <name>       # Remove upstream
mtproxymax upstream test <name>         # Test connectivity
mtproxymax sni-policy [mask|drop]      # Unknown SNI action (mask=permissive, drop=strict)

mtproxymax traffic                      # Per-user traffic breakdown
mtproxymax metrics                      # Engine metrics dashboard
mtproxymax metrics live [seconds]       # Auto-refresh metrics (default: 5s)
mtproxymax logs                         # Stream live logs
mtproxymax health                       # Run diagnostics

mtproxymax engine status                # Show current engine version
mtproxymax engine rebuild               # Force rebuild engine image
mtproxymax rebuild                      # Force rebuild from source
mtproxymax update                       # Check for script + engine updates

mtproxymax telegram setup               # Interactive bot setup
mtproxymax telegram status              # Show bot status
mtproxymax telegram test                # Send test message
mtproxymax telegram disable             # Disable bot
mtproxymax telegram remove              # Remove bot completely

• Replication — sync config from master to slave servers via rsync+SSH with systemd timer
• Auto-exclude — settings.conf and replication.conf are never synced to slaves, preserving their role and local state
• Wizard — interactive setup for master, slave, and standalone roles
• Slave protection — setting slave role stops any local sync timer and clears stale peer list
• Promote — mtproxymax replication promote for manual failover (slave → master)
• Role guards — replication add/remove/sync are blocked with a clear error on slave servers
• Sync script auto-update — manual sync always regenerates the script from current binary

Engine Upgrade (v3.3.31 → v3.3.32):

• Bounded Hybrid Routing Loop — Hard timeout on ME no-writer recovery, prevents infinite-spin edge case
• ArcSwap Snapshots — Lock-free concurrent reads on writer pools, endpoints, and family state for less contention
• Parallel Health Checks — Reduced latency during writer recovery
• Refined Quarantine — Draining writers no longer needlessly quarantine healthy endpoints
• New Backpressure Model — Tiered base/high watermark for better overload handling

New Features:

• Unknown SNI Policy — Configurable mask (permissive, default) or drop (strict) for TLS connections with non-matching SNI. TUI: Security & Routing > Unknown SNI Policy. CLI: mtproxymax sni-policy [mask|drop] (#40)
• Engine Metrics Dashboard — mtproxymax metrics shows connections, upstream routing, per-user stats, and ME pool status. mtproxymax metrics live for auto-refresh
• Reset Traffic Counters — mtproxymax secret reset-traffic <label|all> to manually reset per-user cumulative traffic

Bug Fixes:

• Fix broken pipe on Alpine — Replaced process-substitution FIFOs with here-strings to avoid SIGPIPE race (#37)
• Fix double-input on Alpine — Drain leftover escape-sequence bytes from multi-byte key presses in TUI menus (#38)
• Fix SNI rejection after engine upgrade — unknown_sni_action default changed to drop in telemt v3.3.31+, now explicitly set to mask for backward compatibility (#40)

• Secret Notes — Attach descriptions to secrets (secret note <label> <text>, TUI option [8])
• Expiry Warnings — Secret list shows (3d left) / (expired), Telegram alerts 3 days before expiry
• Quota Enforcement — Auto-disables secrets at 100% quota, warns at 80%, works even without Telegram bot
• Auto-disable on Quota Hit — secret reenable <label> to restore with optional traffic reset
• JSON Status — mtproxymax status --json for Grafana/Zabbix/monitoring integration
• Connection Log — Per-user activity log with auto-rotation (connlog CLI, TUI Logs & Traffic > [2])
• Backup & Restore — mtproxymax backup, restore <file>, backups — includes all config, secrets, and stats
• Multi-Port Instances — Run proxy on multiple ports with shared secrets (instance add/remove/list)
• Hot-Reload for Secrets — Add/remove/rotate secrets without dropping active connections
• Whitelist Geo-Blocking — Allow only specific countries, block everything else (#29)

• Persistent Traffic Counters — Traffic stats (TRAFFIC IN / TRAFFIC OUT) now survive container restarts (#13)
• Always-On Traffic Tracking — Cumulative traffic saved to disk every 60s, even without Telegram bot enabled
• Pre-Stop Traffic Flush — Final traffic snapshot saved before every stop/restart, no data loss on clean shutdown
• TUI Batch Stats Loading — Single metrics fetch + single file read replaces per-user subprocess spawning
• Atomic File Writes with Locking — Traffic files use flock to prevent race conditions between daemon and CLI
• Fixed In/Out Direction Mapping — Consistent from_client=in, to_client=out across all functions

• Batch Add — secret add-batch <l1> <l2> ... adds multiple secrets with a single restart (#12)
• Batch Remove — secret remove-batch <l1> <l2> ... removes multiple secrets with a single restart
• --no-restart flag — secret add/remove/add-batch/remove-batch --no-restart for scripting and automation
• TUI options — Interactive menu options [6] and [7] for batch operations

Engine Upgrade (v3.3.28 → v3.3.30):

• TLS Fetcher Redesign — Adaptive profile cascade (Chrome → Firefox → TLS 1.2 → legacy) with per-target caching, automatic fallback on handshake failures — significantly harder to fingerprint/block via DPI
• TLS SNI Validator — Enforces SNI from configured domain, drops invalid probes cheaply
• Atomic Per-User Quotas — Removed locking from hot path for better throughput under load
• PROXY Protocol Trusted CIDRs — Restrict PROXY header trust to specific source networks
• DPI Evasion Hardening — Shape/timing hardening, masking prefetch, tiny-frame debt protection
• Shadowsocks Upstream — New upstream transport option alongside SOCKS5
• ME Anti-Stuck + Orphan Watchdog — Root cause fix for random connection drops
• Adaptive Buffers — Dynamic buffer sizing: less RAM at low load, more throughput at high load
• Flow Performance — 3x faster D2C flush + immediate ACK flushing for lower latency
• Event-Driven ME — Pool switches from busy-polling to event-driven, reducing CPU on idle servers
• ME/DC Reroute — Dynamic rerouting when preferred datacenter path degrades

• Per-user connection, IP, quota, and expiry limits
• Telegram bot with 17 commands for remote management
• Proxy chaining via SOCKS5/SOCKS4 upstreams
• Geo-blocking with CIDR blocklists
• Auto-recovery with Telegram alerts

• Full MTProto proxy management with telemt 3.x Rust engine
• Interactive TUI + complete CLI
• Multi-user secret management with QR codes
• FakeTLS obfuscation with traffic masking
• Prometheus metrics endpoint
• Auto-update system

Built on top of telemt — a high-performance MTProto proxy engine written in Rust/Tokio. All proxy protocol handling, FakeTLS, traffic masking, and per-user enforcement is powered by telemt.

If you find MTProxyMax useful, consider supporting its development:

samnet.dev/donate

MIT License — see LICENSE for details.

The telemt engine (included as a Docker image) is licensed under the Telemt Public License 3 (TPL-3) — a permissive license that allows use, redistribution, and modification with attribution.

Copyright (c) 2026 SamNet Technologies