{"id":47928627,"url":"https://github.com/uk0/stun_max","last_synced_at":"2026-04-14T01:02:57.790Z","repository":{"id":348373835,"uuid":"1197620612","full_name":"uk0/stun_max","owner":"uk0","description":"P2P TCP tunnel with STUN hole punching and automatic server relay fallback. Cross-platform GUI + CLI. Zero configuration networking.","archived":false,"fork":false,"pushed_at":"2026-04-11T11:54:02.000Z","size":39678,"stargazers_count":41,"open_issues_count":1,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-11T13:17:25.389Z","etag":null,"topics":["golang","gui","p2p","stunnel"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uk0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T18:25:21.000Z","updated_at":"2026-04-11T11:56:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/uk0/stun_max","commit_stats":null,"previous_names":["uk0/stun_max"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/uk0/stun_max","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uk0%2Fstun_max","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uk0%2Fstun_max/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uk0%2Fstun_max/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uk0%2Fstun_max/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uk0","download_url":"https://codeload.github.com/uk0/stun_max/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uk0%2Fstun_max/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31777348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T00:11:49.126Z","status":"ssl_error","status_checked_at":"2026-04-14T00:10:29.837Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","gui","p2p","stunnel"],"created_at":"2026-04-04T07:06:12.378Z","updated_at":"2026-04-14T01:02:57.783Z","avatar_url":"https://github.com/uk0.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/logo.png\" width=\"128\" alt=\"STUN Max Logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSTUN Max\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  P2P TCP tunnel with STUN hole punching and automatic server relay fallback.\u003cbr\u003e\n  Cross-platform GUI + CLI. Zero configuration networking.\n\u003c/p\u003e\n\n---\n\n## Features\n\n- **P2P Direct Connection** — STUN hole punch with Birthday Attack + port prediction, data never touches the server\n- **Auto Relay Fallback** — If P2P fails after 5 attempts, seamlessly falls back to server relay\n- **gVisor TCP/IP Stack** — Production-grade userspace TCP (same as Tailscale/tun2socks) for VPN proxy and port forwarding\n- **TUN VPN** — Full subnet routing with SNAT, TCP MSS clamping, smart compression bypass\n- **Port Forwarding** — Map any remote peer's `host:port` to your localhost, with gVisor reliable transport\n- **Speed Test** — P2P bandwidth test between peers with real-time progress\n- **File Transfer** — Send files between peers with compression and progress tracking\n- **LAN Auto-Detection** — Same public IP peers connect via local address (zero latency)\n- **Auto Reconnect** — Network changes trigger automatic reconnect (3s interval, infinite retry)\n- **Room-Based Access** — Password-protected rooms, created via admin dashboard only\n- **GUI + CLI** — Gio UI desktop app (Windows/Mac) + readline CLI with tab completion\n- **NAT Diagnostic** — Built-in `natcheck` tool detects NAT type and punch success probability\n- **Config Persistence** — Connection, forwards, STUN servers saved and restored across restarts\n- **Traffic Stats** — Real-time upload/download speed and total bytes per forward\n- **Self-Hosted STUN** — Lightweight STUN server included for restricted networks\n\n\u003c!-- PLACEHOLDER_README_PART2 --\u003e\n\n## Architecture\n\n```\n┌──────────┐    1. UDP hole punch       ┌──────────┐\n│ Client A │◄ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ►│ Client B │\n│ (GUI/CLI)│    2. P2P UDP direct       │ (GUI/CLI)│\n│          │◄══════════════════════════►│          │\n└────┬─────┘    (gVisor TCP/IP stack)   └────┬─────┘\n     │                                       │\n     │   WebSocket (signaling + relay)       │\n     └───────────────┬───────────────────────┘\n                     │\n              ┌──────┴──────┐\n              │   Server    │\n              │ Signal+Relay│\n              │ + Dashboard │\n              └─────────────┘\n```\n\n**Connection flow:**\n\n1. Both clients connect to signal server via WebSocket\n2. STUN discovery finds public IP:port (supports custom/self-hosted STUN)\n3. UDP hole punch with Birthday Attack + port prediction\n4. Data flows over P2P UDP — server not in the data path\n5. gVisor userspace TCP/IP stack handles congestion control, retransmission, SACK\n6. If punch fails 5 times → auto relay, background retry continues\n7. If P2P later succeeds → auto upgrade back from relay\n\n## Screenshots\n\n| Dashboard | GUI - Connect |\n|-----------|---------------|\n| ![Dashboard](img/img_2.png) | ![Connect](img/img_1.png) |\n\n| GUI - Logs             | GUI - Peers |\n|------------------------|-------------|\n| ![Logs](img/img_9.png) | ![Peers](img/img_4.png) |\n\n| GUI - Forwards | GUI - TUN VPN |\n|----------------|---------------|\n| ![Forwards](img/img_5.png) | ![VPN](img/img_6.png) |\n\n| GUI - Settings | GUI - Files |\n|----------------|-------------|\n| ![Settings](img/img_7.png) | ![Files](img/img_8.png) |\n\n\n## Quick Start\n\n### 1. Deploy Server\n\n```bash\n./build.sh\n\n# Upload to your server\nscp build/stun_max-server-linux-amd64 root@SERVER:/usr/local/bin/stun_max-server\nscp build/stun_max-stunserver-linux-amd64 root@SERVER:/usr/local/bin/stun_max-stunserver\nssh root@SERVER \"mkdir -p /opt/stun_max/web\"\nscp -r build/web/* root@SERVER:/opt/stun_max/web/\n```\n\nCreate systemd services:\n\n```bash\n# Signal Server\ncat \u003e /etc/systemd/system/stun-max.service \u003c\u003c 'EOF'\n[Unit]\nDescription=STUN Max Signal Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/stun_max-server --addr :8080 --web-dir /opt/stun_max/web\nRestart=always\nRestartSec=3\nLimitNOFILE=65536\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\n# STUN Server (optional, recommended for restricted networks)\ncat \u003e /etc/systemd/system/stun-max-stun.service \u003c\u003c 'EOF'\n[Unit]\nDescription=STUN Max STUN Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/stun_max-stunserver --addr :3478\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\nsystemctl daemon-reload\nsystemctl enable --now stun-max stun-max-stun\n```\n\nGet the auto-generated dashboard password:\n\n```bash\njournalctl -u stun-max | grep Password\n```\n\n**Firewall:** Open TCP `8080` and UDP `3478`.\n\n### 2. Create a Room\n\nOpen `http://SERVER:8080`, login, create a room with name + password.\n\n### 3. Connect\n\n**GUI (Windows/Mac):**\n\nRun `stun_max-client-windows-amd64.exe` or `stun_max-client-darwin-arm64`, fill in server URL, room, password, name → Connect.\n\n**CLI:**\n\n```bash\n./stun_max-cli --server ws://SERVER:8080/ws --room myroom --password secret --name laptop\n```\n\n### 4. Port Forwarding\n\n```bash\n# Forward peer's port to local\n\u003e forward peer-name 127.0.0.1:3389\n\u003e forward peer-name 192.168.1.100:8080 9090\n\n# Manage\n\u003e forwards          # list with traffic stats\n\u003e unforward 3389    # stop\n```\n\n### 5. TUN VPN (Subnet Routing)\n\n```bash\n# Route a remote subnet through peer\n\u003e vpn peer-name 192.168.1.0/24\n\u003e vpn peer-name 192.168.1.0/24 --exit-ip 192.168.1.1\n\n# Check status\n\u003e vpn status\n\n# Stop\n\u003e vpn stop\n```\n\n### 6. Speed Test\n\n```bash\n\u003e speedtest peer-name          # default 10MB, auto mode\n\u003e speedtest peer-name 50       # 50MB test\n\u003e speedtest peer-name 10 p2p   # force P2P transport\n```\n\n### 7. File Transfer\n\n```bash\n\u003e send peer-name /path/to/file\n\u003e transfers                     # list active transfers\n```\n\n## Build\n\n```bash\n./build.sh                                    # all platforms\ngo build ./server/                            # server only\ngo build ./client/                            # GUI client\ngo build -tags cli ./client/                  # CLI client\ngo build ./tools/natcheck/                    # NAT diagnostic\ngo build ./tools/stunserver/                  # STUN server\n```\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `peers` | List peers with P2P/RELAY mode |\n| `forward \u003cpeer\u003e \u003chost:port\u003e [local]` | Forward remote port |\n| `unforward \u003cport\u003e` | Stop forward |\n| `forwards` | List forwards with traffic stats |\n| `expose \u003chost:port\u003e \u003cpeer\u003e [port]` | Reverse forward (expose local service) |\n| `stun` | STUN/P2P connection details |\n| `speedtest \u003cpeer\u003e [size] [p2p\\|relay]` | Bandwidth test |\n| `send \u003cpeer\u003e \u003cfile\u003e` | Send file to peer |\n| `transfers` | List file transfers |\n| `vpn \u003cpeer\u003e [subnets...] [--exit-ip IP]` | Start TUN VPN |\n| `vpn status` | VPN status with traffic |\n| `vpn stop` | Stop VPN |\n| `hop \u003cpeer-b\u003e \u003cpeer-c\u003e \u003chost:port\u003e` | Multi-hop forward via B to C |\n| `help` | All commands |\n| `quit` | Disconnect |\n\nTab completion for commands, peer names, and ports.\n\n## GUI Tabs\n\n| Tab | Description |\n|-----|-------------|\n| **Peers** | Peer list with P2P/RELAY badges, STUN endpoints |\n| **Forwards** | Create/stop forwards, live traffic (bytes + speed), peer dropdown selector |\n| **VPN** | Start/stop TUN VPN, subnet routing, traffic stats |\n| **Speed Test** | P2P bandwidth test with progress bar and transport display |\n| **Files** | Send/receive files with progress |\n| **Settings** | Forward control, STUN server selector, autostart, auto-connect |\n| **Logs** | Scrollable event log with severity colors |\n\n## Security\n\n| Feature | Detail |\n|---------|--------|\n| E2E encryption | X25519 + AES-256-GCM for all P2P and relay data |\n| Room isolation | Relay verifies sender and receiver in same room |\n| Room auth | Dashboard-only creation, SHA-256 password hash |\n| Rate limiting | Login 5/min, WebSocket 20/min, Join 10/min per IP |\n| Connection limit | Global max (default 5000, `--max-connections`) |\n| Session expiry | Dashboard tokens expire after 24 hours |\n| Blacklist | Ban/unban clients per room |\n| Forward control | Per-client allow/deny + local-only mode |\n\n## Server Flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--addr` | `:8080` | Listen address |\n| `--web-password` | (random) | Dashboard password |\n| `--web-dir` | `../web` | Static files path |\n| `--max-connections` | `5000` | Max WebSocket connections |\n| `--tls-cert` | | TLS certificate file |\n| `--tls-key` | | TLS key file |\n\n## Client Flags (CLI)\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--server` | `ws://localhost:8080/ws` | Server URL |\n| `--room` | (required) | Room name |\n| `--password` | | Room password |\n| `--name` | (hostname) | Display name |\n| `--stun` | `stun.cloudflare.com:3478` | STUN servers (comma-separated) |\n| `--no-stun` | `false` | Relay only |\n| `-v` | `false` | Verbose |\n\n## Project Structure\n\n```\nserver/                  Signal + relay + dashboard\n  main.go                HTTP/WS, auth, rate limiting, TLS\n  hub.go                 Rooms, peers, blacklist\n  client.go              Message routing, join validation\n\nclient/core/             Networking (shared by GUI + CLI)\n  client.go              Connection, reconnect, signaling\n  tunnel.go              Port forwarding with gVisor transport\n  forward_netstack.go    Per-peer gVisor TCP/IP stack for forwards\n  tun.go                 TUN VPN device, SNAT, MSS clamping\n  tun_netstack.go        gVisor TCP/IP stack for VPN subnet proxy\n  tun_proxy.go           Legacy ICMP proxy (raw socket)\n  tun_config_*.go        Platform-specific TUN setup (darwin/linux/windows)\n  stun.go                STUN discovery, hole punch, UDP read loop\n  speedtest.go           P2P bandwidth testing\n  crypto.go              X25519 + AES-256-GCM key exchange\n  compress.go            Deflate compression with smart bypass\n  udp_reliable.go        RUTP reliable UDP (legacy, used by old tunnels)\n  types.go               Protocol types\n  events.go              Event system\n\nclient/ui/               Gio UI desktop app\n  app.go                 Window, events, auto-connect\n  connect.go             Login screen\n  dashboard.go           Tab navigation\n  peers.go               Peer list\n  forwards.go            Forward management with traffic stats\n  vpn.go                 TUN VPN control\n  speedtest.go           Speed test with P2P mode\n  files.go               File transfer\n  peer_selector.go       Dropdown peer selector with P2P/RELAY badge\n  settings.go            Settings + STUN selector\n  config.go              Config persistence\n  logs.go                Event log viewer\n\nweb/                     Admin dashboard (HTML/JS/CSS)\ntools/natcheck/          NAT type diagnostic\ntools/stunserver/        Self-hosted STUN server\n```\n\n## License\n\nAGPL-3.0 — See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuk0%2Fstun_max","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuk0%2Fstun_max","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuk0%2Fstun_max/lists"}