The Ultimate Telegram MTProto Proxy Manager
One script. Full control. Zero hassle.
-orange){kind=icon}
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
- 🖥️ 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 installmtproxymax # Open interactive TUI
mtproxymax status # Check proxy healthYour 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:
| Limit | Description | Example | Best For |
|---|---|---|---|
| Max Connections | Concurrent connections (1 app = 1 conn) | 3 |
Device limiting |
| Max IPs | Unique IP addresses allowed | 5 |
Anti-sharing / abuse |
| Data Quota | Lifetime bandwidth cap | 10G, 500M |
Fair usage |
| Expiry Date | Auto-disable after date | 2026-12-31 |
Temporary access |
Tip: Use
connsfor device limits, notips. Each Telegram app opens exactly 1 connection (multiplexed internally), soconns 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. Useipsas a secondary anti-sharing measure.Traffic and quotas are lifetime (cumulative), not monthly. They don't auto-reset. To reset a user's traffic, rotate their secret.
mtproxymax secret setlimits alice 100 5 10G 2026-12-31Limit Devices Per User (Recommended)
mtproxymax secret setlimit alice conns 1 # Single device only
mtproxymax secret setlimit family conns 5 # Family — up to 5 devicesIf someone with conns 1 shares their link, the second device can't connect. Each Telegram app = exactly 1 connection.
Device Limit Tiers
| Scenario | conns |
ips (optional) |
|---|---|---|
| Single person, one device | 1 |
2 (allow roaming) |
| Single person, multiple devices | 3 |
5 |
| Small family | 5 |
10 |
| Small group / office | 30 |
50 |
| Public/open link | 0 |
0 (unlimited) |
Set
ipsslightly higher thanconnsto allow for mobile roaming (cell tower switches temporarily show 2 IPs for 1 device).
Time-Limited Sharing Link
mtproxymax secret add shared-link
mtproxymax secret setlimits shared-link 50 30 10G 2026-06-01When the expiry date hits, the link stops working automatically.
Per-Person Keys (Recommended)
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 devicesDisable, Rotate, Remove
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 removalFull proxy management from your phone. Setup takes 60 seconds:
mtproxymax telegram setup| Command | Description |
|---|---|
/mp_status |
Proxy status, uptime, connections |
/mp_secrets |
List all users with active connections |
/mp_link |
Get proxy details + QR code image |
/mp_add <label> |
Add new user |
/mp_remove <label> |
Delete user |
/mp_rotate <label> |
Generate new key for user |
/mp_enable <label> |
Re-enable disabled user |
/mp_disable <label> |
Temporarily disable user |
/mp_limits |
Show all user limits |
/mp_setlimit |
Set user limits |
/mp_traffic |
Per-user traffic breakdown |
/mp_upstreams |
List proxy chains |
/mp_health |
Run diagnostics |
/mp_restart |
Restart proxy |
/mp_update |
Check for updates |
/mp_help |
Show all commands |
Automatic alerts:
- 🔴 Proxy down → instant notification + auto-restart attempt
- 🟢 Proxy started → sends connection details + QR codes
- 📊 Periodic traffic reports at your chosen interval
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 50Supports 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 countriesIP-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 sourceEngine updates are delivered through mtproxymax update. Pre-built multi-arch Docker images (amd64 + arm64) are pulled automatically. Source compilation is the automatic fallback.
| Feature | MTProxyMax | mtg v2 (Go) | Official MTProxy (C) | Bash Installers |
|---|---|---|---|---|
| Engine | telemt 3.x (Rust) | mtg (Go) | MTProxy (C) | Various |
| FakeTLS | ✅ | ✅ | ❌ (needs patches) | Varies |
| Traffic Masking | ✅ | ✅ | ❌ | ❌ |
| Multi-User Secrets | ✅ (unlimited) | ❌ (1 secret) | Multi-secret | Usually 1 |
| Per-User Limits | ✅ (conns, IPs, quota, expiry) | ❌ | ❌ | ❌ |
| Per-User Traffic Stats | ✅ (Prometheus) | ❌ | ❌ | ❌ |
| Telegram Bot | ✅ (17 commands) | ❌ | ❌ | ❌ |
| Interactive TUI | ✅ | ❌ | ❌ | ❌ |
| Proxy Chaining | ✅ (SOCKS5/4, weighted) | ✅ (SOCKS5) | ❌ | ❌ |
| Geo-Blocking | ✅ | IP allowlist/blocklist | ❌ | ❌ |
| Ad-Tag Support | ✅ | ❌ (removed in v2) | ✅ | Varies |
| QR Code Generation | ✅ | ❌ | ❌ | Some |
| Auto-Recovery | ✅ (with alerts) | ❌ | ❌ | ❌ |
| Auto-Update | ✅ | ❌ | ❌ | ❌ |
| Docker | ✅ (multi-arch) | ✅ | ❌ | Varies |
| User Expiry Dates | ✅ | ❌ | ❌ | ❌ |
| Bandwidth Quotas | ✅ | ❌ | ❌ | ❌ |
| Device Limits | ✅ | ❌ | ❌ | ❌ |
| Active Development | ✅ | ✅ | Abandoned | Varies |
Why Not mtg?
mtg is solid and minimal — by design. It's "highly opinionated" and intentionally barebones. Fine for a single-user fire-and-forget proxy.
But mtg v2 dropped ad-tag support, only supports one secret, has no user limits, no management interface, and no auto-recovery.
Why Not the Official MTProxy?
Telegram's official MTProxy (C implementation) was last updated in 2019. No FakeTLS, no traffic masking, no per-user controls, manual compilation, no Docker.
Why Not a Simple Bash Installer?
Scripts like MTProtoProxyInstaller install a proxy and give you a link. That's it. No user management, no monitoring, no bot, no updates, no recovery.
MTProxyMax is not just an installer — it's a management platform that happens to install itself.
Telegram Client
│
▼
┌─────────────────────────┐
│ Your Server (port 443) │
│ ┌───────────────────┐ │
│ │ Docker Container │ │
│ │ ┌─────────────┐ │ │
│ │ │ telemt │ │ │ ← Rust/Tokio engine
│ │ │ (FakeTLS) │ │ │
│ │ └──────┬──────┘ │ │
│ └─────────┼─────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ ▼ ▼ │
│ Direct SOCKS5 │ ← Upstream routing
│ routing chaining │
└─────────┬───────────────┘
│
▼
Telegram Servers
| Component | Role |
|---|---|
| mtproxymax.sh | Single bash script: CLI, TUI, config manager |
| telemt | Rust MTProto engine running inside Docker |
| Telegram bot service | Independent systemd service polling Bot API |
| Prometheus endpoint | /metrics on port 9090 (localhost only) |
Proxy Management
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 TUIUser Secrets
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 limitsConfiguration
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-tagSecurity & Routing
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 connectivityMonitoring
mtproxymax traffic # Per-user traffic breakdown
mtproxymax logs # Stream live logs
mtproxymax health # Run diagnosticsEngine & Updates
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 updatesTelegram Bot
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| Requirement | Details |
|---|---|
| OS | Ubuntu, Debian, CentOS, RHEL, Fedora, Rocky, AlmaLinux, Alpine |
| Docker | Auto-installed if not present |
| RAM | 256MB minimum |
| Access | Root required |
| Bash | 4.2+ |
| File | Purpose |
|---|---|
/opt/mtproxymax/settings.conf |
Proxy settings (port, domain, limits) |
/opt/mtproxymax/secrets.conf |
User keys, limits, expiry dates |
/opt/mtproxymax/upstreams.conf |
Upstream routing rules |
/opt/mtproxymax/mtproxy/config.toml |
Generated telemt engine config |
- 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
flockto 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-restartflag —secret add/remove/add-batch/remove-batch --no-restartfor scripting and automation- TUI options — Interactive menu options [6] and [7] for batch operations
Engine Upgrade (v3.3.3 → v3.3.28):
- ME Anti-Stuck + Orphan Watchdog — Root cause fix for random connection drops: writer cleanup races resolved, orphaned writers detected and force-closed
- Quarantine Fixes — Quarantined endpoints no longer bypass the circuit breaker, preventing flapping reconnection loops
- Authoritative Teardown — New deterministic writer teardown sequence with force-close safety policy
- ME Draining on Dual-Stack — Proper draining behavior on IPv4+IPv6 servers
- TLS Fetcher Upstream Selection — Smarter upstream selection for TLS fetching
- Teardown Monitoring — New API and Prometheus metrics for writer teardown visibility
- Instadrain + Hard-Remove — Writers stuck draining are force-removed instead of hanging
- 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
- Hot-Reload Fixes — Reliable config reload without restart
- Event-Driven ME — Pool switches from busy-polling to event-driven, reducing CPU on idle servers
- CPU/RAM Hot-Path Optimization — Removed hot-path obstacles for lower resource usage under load
- Source-IP ME Routing — Routing decisions factor in source IP for multi-homed servers
- ME/DC Reroute — Dynamic rerouting when preferred datacenter path degrades
- Per-Upstream Runtime Selftest — Built-in diagnostics for upstream connectivity
- 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:
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
