Skip to content

pubgo/stun_max

BranchesTags
 
 

Repository files navigation

STUN Max Logo

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

WeChat QR Code

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:

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

Screenshots

Dashboard GUI - Connect
Dashboard Connect
GUI - Logs GUI - Peers
Logs Peers
GUI - Forwards GUI - TUN VPN
Forwards VPN
GUI - Settings GUI - Files
Settings Files

Android

Peers Forwards Files VPN
Peers Forwards Files VPN
Speed Test Tools Settings Logs
SpeedTest 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.

About

stun

Resources

Readme

License

AGPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Go 88.0%
  • Shell 4.3%
  • JavaScript 3.1%
  • CSS 2.2%
  • Java 1.7%
  • HTML 0.7%