STUN Max

微信公众号：你起来我讲两句

STUN Max

P2P TCP tunnel with STUN hole punching and automatic server relay fallback.
Cross-platform GUI + CLI. Zero configuration networking.

Features

P2P Direct Connection — STUN hole punch with Birthday Attack (256 sockets) + port prediction (±1000), data never touches the server
Auto Relay Fallback — If P2P fails, seamlessly falls back to server relay; background retry upgrades back to P2P
NAT Traversal — Detects NAT1 (Cone) / NAT4 (Symmetric), adapts punch strategy; ~98% success for NAT3+NAT4 pairs
gVisor TCP/IP Stack — Production-grade userspace TCP (same as Tailscale/tun2socks) for VPN proxy and port forwarding
TUN VPN — Full subnet routing with SNAT, multi-VPN support (multiple peers simultaneously), VPN auto-restore on reconnect
Port Forwarding — Map any remote peer's host:port to your localhost, with gVisor reliable transport
Speed Test — P2P bandwidth test with cancel support and real-time progress
File Transfer — Send files with compression, CRC verification, rate-limited P2P UDP, auto relay fallback
Proxy Bypass — Auto-detects physical NIC, bypasses TUN proxies (Clash/V2Ray), skips CGNAT ranges
LAN Auto-Detection — Same public IP peers connect via local address (zero latency)
Auto Reconnect — Network changes trigger reconnect with backoff (1s→5s), P2P + VPN auto-restore
Room Management — Client-created rooms auto-delete when owner leaves; dashboard rooms persist; per-room relay control
GUI + CLI — Gio UI desktop app (Windows/Mac/Android) + readline CLI with tab completion
Android App — Full-featured with VPN, auto permission, native icon, WiFi-priority networking
Server Dashboard — Room management, peer monitoring, IP geolocation, STUN stats, Kick/Ban, relay control
NAT Diagnostic — natcheck tool with RFC 5780 support, Chinese UI, proxy bypass, comprehensive report
E2E Encryption — X25519 + XChaCha20-Poly1305, thread-safe, 24-byte nonce
SQLite Persistence — Rooms and blacklists survive server restart
Self-Hosted STUN — Lightweight STUN server with HTTP stats API

Architecture

┌──────────┐    1. UDP hole punch       ┌──────────┐
│ Client A │◄ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ►│ Client B │
│ (GUI/CLI)│    2. P2P UDP direct       │ (GUI/CLI)│
│          │◄══════════════════════════►│          │
└────┬─────┘    (gVisor TCP/IP stack)   └────┬─────┘
     │                                       │
     │   WebSocket (signaling + relay)       │
     └───────────────┬───────────────────────┘
                     │
              ┌──────┴──────┐
              │   Server    │
              │ Signal+Relay│
              │ + Dashboard │
              └─────────────┘

Connection flow:

Both clients connect to signal server via WebSocket
STUN discovery finds public IP:port (supports custom/self-hosted STUN)
UDP hole punch with Birthday Attack + port prediction
Data flows over P2P UDP — server not in the data path
gVisor userspace TCP/IP stack handles congestion control, retransmission, SACK
If punch fails 5 times → auto relay, background retry continues
If P2P later succeeds → auto upgrade back from relay

Screenshots

Dashboard	GUI - Connect

GUI - Logs	GUI - Peers

GUI - Forwards	GUI - TUN VPN

GUI - Settings	GUI - Files

Android

Peers	Forwards	Files	VPN

Speed Test	Tools	Settings	Logs

Quick Start

1. Deploy Server (One-Click)

curl -fsSL https://raw.githubusercontent.com/uk0/stun_max/main/install.sh | sudo bash

Custom password:

curl -fsSL https://raw.githubusercontent.com/uk0/stun_max/main/install.sh | STUN_MAX_PASSWORD=your_password sudo bash

Custom ports:

curl -fsSL https://raw.githubusercontent.com/uk0/stun_max/main/install.sh | STUN_MAX_PORT=9090 STUN_MAX_STUN_PORT=3479 sudo bash

The script auto-downloads the latest release, configures systemd, and opens firewall ports.

1b. Manual Deploy

./build.sh

# Upload to your server
scp build/stun_max-server-linux-amd64 root@SERVER:/usr/local/bin/stun_max-server
scp build/stun_max-stunserver-linux-amd64 root@SERVER:/usr/local/bin/stun_max-stunserver
ssh root@SERVER "mkdir -p /opt/stun_max/web"
scp -r build/web/* root@SERVER:/opt/stun_max/web/

Create systemd services:

# Signal Server
cat > /etc/systemd/system/stun-max.service << 'EOF'
[Unit]
Description=STUN Max Signal Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/stun_max-server --addr :8080 --web-dir /opt/stun_max/web --db /opt/stun_max/stun_max.db --ipdb /opt/stun_max/ip2region.xdb --stun-http http://127.0.0.1:3479
Restart=always
RestartSec=3
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

# STUN Server (optional, recommended for restricted networks)
cat > /etc/systemd/system/stun-max-stun.service << 'EOF'
[Unit]
Description=STUN Max STUN Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/stun_max-stunserver --addr :3478 --http :3479
Restart=always

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now stun-max stun-max-stun

Get the auto-generated dashboard password:

journalctl -u stun-max | grep Password

Firewall: Open TCP 8080 and UDP 3478.

2. Create a Room

Open http://SERVER:8080, login, create a room with name + password.

3. Connect

GUI (Windows/Mac/Android):

Run stun_max-client-windows-amd64.exe or stun_max-client-darwin-arm64, fill in server URL, room, password, name → Connect.

Android: Install stun_max-android-v*.apk, same UI as desktop with touch-optimized layout.

CLI:

./stun_max-cli --server ws://SERVER:8080/ws --room myroom --password secret --name laptop

4. Port Forwarding

# Forward peer's port to local
> forward peer-name 127.0.0.1:3389
> forward peer-name 192.168.1.100:8080 9090

# Manage
> forwards          # list with traffic stats
> unforward 3389    # stop

5. TUN VPN (Subnet Routing)

# Route a remote subnet through peer
> vpn peer-name 192.168.1.0/24
> vpn peer-name 192.168.1.0/24 --exit-ip 192.168.1.1

# Check status
> vpn status

# Stop
> vpn stop

6. Speed Test

> speedtest peer-name          # default 10MB, auto mode
> speedtest peer-name 50       # 50MB test
> speedtest peer-name 10 p2p   # force P2P transport

7. File Transfer

> send peer-name /path/to/file
> transfers                     # list active transfers

Build

./build.sh                                    # all platforms (server + desktop + CLI)
bash android/build-apk.sh v1.0.0             # Android APK
go build ./server/                            # server only
go build ./client/                            # GUI client
go build -tags cli ./client/                  # CLI client
go build ./tools/natcheck/                    # NAT diagnostic
go build ./tools/stunserver/                  # STUN server

Android build requires: Android SDK (ANDROID_HOME), NDK, gogio (go install gioui.org/cmd/gogio@latest).

CLI Commands

Command	Description
`peers`	List peers with P2P/RELAY mode
`forward <peer> <host:port> [local]`	Forward remote port
`unforward <port>`	Stop forward
`forwards`	List forwards with traffic stats
`expose <host:port> <peer> [port]`	Reverse forward (expose local service)
`stun`	STUN/P2P connection details
`speedtest <peer> [size] [p2p\|relay]`	Bandwidth test
`send <peer> <file>`	Send file to peer
`transfers`	List file transfers
`vpn <peer> [subnets...] [--exit-ip IP]`	Start TUN VPN
`vpn status`	VPN status with traffic
`vpn stop`	Stop VPN
`hop <peer-b> <peer-c> <host:port>`	Multi-hop forward via B to C
`help`	All commands
`quit`	Disconnect

Tab completion for commands, peer names, and ports.

GUI Tabs

Tab	Description
Peers	Peer list with P2P/RELAY badges, STUN endpoints
Forwards	Create/stop forwards, live traffic (bytes + speed), peer dropdown selector
VPN	Start/stop TUN VPN, subnet routing, traffic stats
Speed Test	P2P bandwidth test with progress bar and transport display
Files	Send/receive files with progress
Settings	Forward control, STUN server selector, autostart, auto-connect
Tools	Windows RDP remote desktop setup
Logs	Scrollable event log with severity colors

All tabs support vertical scrolling on both desktop and mobile.

Security

Feature	Detail
E2E encryption	X25519 + XChaCha20-Poly1305 for all P2P and relay data
Room isolation	Relay verifies sender and receiver in same room
Room auth	Dashboard-only creation, SHA-256 password hash
Rate limiting	Login 5/min, WebSocket 20/min, Join 10/min per IP
Connection limit	Global max (default 5000, `--max-connections`)
Session expiry	Dashboard tokens expire after 24 hours
Blacklist	Ban/unban clients per room
Forward control	Per-client allow/deny + local-only mode

Server Flags

Flag	Default	Description
`--addr`	`:8080`	Listen address
`--web-password`	(built-in)	Dashboard password
`--web-dir`	`../web`	Static files path
`--db`	`stun_max.db`	SQLite database file
`--ipdb`	`ip2region.xdb`	IP geolocation database
`--stun-http`	`http://127.0.0.1:3479`	STUN server stats URL
`--max-connections`	`5000`	Max WebSocket connections
`--tls-cert`		TLS certificate file
`--tls-key`		TLS key file

Client Flags (CLI)

Flag	Default	Description
`--server`	`ws://localhost:8080/ws`	Server URL
`--room`	(required)	Room name
`--password`		Room password
`--name`	(hostname)	Display name
`--stun`	`stun.cloudflare.com:3478`	STUN servers (comma-separated)
`--no-stun`	`false`	Relay only
`-v`	`false`	Verbose

Project Structure

server/                  Signal + relay + dashboard
  main.go                HTTP/WS, auth, rate limiting, TLS, graceful shutdown
  hub.go                 Rooms, peers, blacklist, room ownership
  client.go              Message routing, join validation, same-name kick
  relay.go               Data relay with per-room toggle
  store.go               SQLite persistence (rooms, blacklists)
  ipinfo.go              Offline IP geolocation (ip2region)
  stats.go               Server statistics

client/core/             Networking (shared by GUI + CLI)
  client.go              Connection, reconnect, signaling
  tunnel.go              Port forwarding with gVisor transport
  forward_netstack.go    Per-peer gVisor TCP/IP stack for forwards
  tun.go                 TUN VPN device, SNAT, MSS clamping
  tun_netstack.go        gVisor TCP/IP stack for VPN subnet proxy
  tun_proxy.go           Legacy ICMP proxy (raw socket)
  tun_config_*.go        Platform-specific TUN setup (darwin/linux/windows)
  stun.go                STUN discovery, hole punch, UDP read loop
  speedtest.go           P2P bandwidth testing
  crypto.go              X25519 + XChaCha20-Poly1305 encryption
  proxy_bypass.go        TUN proxy bypass (physical NIC detection)
  compress.go            Deflate compression with smart bypass
  udp_reliable.go        RUTP reliable UDP (legacy, used by old tunnels)
  types.go               Protocol types
  events.go              Event system

client/ui/               Gio UI cross-platform app
  app.go                 Window, events, auto-connect
  connect.go             Login screen
  dashboard.go           Tab navigation
  peers.go               Peer list
  forwards.go            Forward management with traffic stats
  vpn.go                 TUN VPN control
  speedtest.go           Speed test with P2P mode
  files.go               File transfer
  tools.go               Windows RDP tools
  peer_selector.go       Dropdown peer selector with P2P/RELAY badge
  settings.go            Settings + STUN selector
  config.go              Config persistence
  logs.go                Event log viewer
  logo.go                Embedded app logo
  platform_android.go    Android platform detection
  platform_other.go      Desktop platform detection

client/core/
  vpn_android.go         Android VPN via JNI (VpnService bridge)
  vpn_stub.go            No-op VPN stub for non-Android
  tun_config_android.go  Android TUN device via VpnService fd
  autohop.go             Auto-hop P2P relay discovery

android/                 Android build pipeline
  build-apk.sh           gogio + dex injection + manifest + signing
  AndroidManifest.xml    VpnService + permissions declaration
  app/src/main/java/     VpnPermissionActivity, StunMaxVpnService, GoBridge

web/                     Admin dashboard (HTML/JS/CSS)
tools/natcheck/          NAT type diagnostic (RFC 5780, Chinese, proxy bypass)
tools/stunserver/        Self-hosted STUN server with HTTP stats
tools/punchtest/         Standalone NAT3/NAT4 hole punch test tool

License

AGPL-3.0 — See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github/workflows		.github/workflows
android		android
client		client
deps		deps
docs		docs
img		img
screenshots		screenshots
server		server
tools		tools
web		web
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
stun-max-wechat-article.docx		stun-max-wechat-article.docx

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

STUN Max

Features

Architecture

Screenshots

Android

Quick Start

1. Deploy Server (One-Click)

1b. Manual Deploy

2. Create a Room

3. Connect

4. Port Forwarding

5. TUN VPN (Subnet Routing)

6. Speed Test

7. File Transfer

Build

CLI Commands

GUI Tabs

Security

Server Flags

Client Flags (CLI)

Project Structure

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

STUN Max

Features

Architecture

Screenshots

Android

Quick Start

1. Deploy Server (One-Click)

1b. Manual Deploy

2. Create a Room

3. Connect

4. Port Forwarding

5. TUN VPN (Subnet Routing)

6. Speed Test

7. File Transfer

Build

CLI Commands

GUI Tabs

Security

Server Flags

Client Flags (CLI)

Project Structure

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages