╔═══════════════════════════════════════════════════════════════════════════════════════╗ ║                                                                                       ║ ║  ███████╗ █████╗ ███╗   ███╗███╗   ██╗███████╗████████╗      ██╗    ██╗ ██████╗       ║ ║  ██╔════╝██╔══██╗████╗ ████║████╗  ██║██╔════╝╚══██╔══╝      ██║    ██║██╔════╝       ║ ║  ███████╗███████║██╔████╔██║██╔██╗ ██║█████╗     ██║   █████╗██║ █╗ ██║██║  ███╗      ║ ║  ╚════██║██╔══██║██║╚██╔╝██║██║╚██╗██║██╔══╝     ██║   ╚════╝██║███╗██║██║   ██║      ║ ║  ███████║██║  ██║██║ ╚═╝ ██║██║ ╚████║███████╗   ██║         ╚███╔███╔╝╚██████╔╝      ║ ║  ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝   ╚═╝          ╚══╝╚══╝  ╚═════╝       ║ ║                                                                                       ║ ║                      Z E R O - T O U C H   W I R E G U A R D                          ║ ║                        V P N   O R C H E S T R A T O R                                ║ ║                                                                                       ║ ║                             [ v1.0.4 - samnet-wg ]                                    ║ ║                                                                                       ║ ╚═══════════════════════════════════════════════════════════════════════════════════════╝ 

❓ What is it?

SamNet-WG is a complete, enterprise-grade WireGuard VPN management solution that transforms any Linux server into a secure VPN appliance in under 5 minutes.

It features a unique Dual-Control Plane architecture:

• High-Performance TUI: A beautiful, flicker-free terminal interface for zero-latency management.
• Modern Web Dashboard: A synced, React-based web UI for remote administration.

📸 Screenshots

✨ Features

🛡️ Security First

• Zero-Trust Architecture: Strict IP validation and "Ghost Peer" prevention.
• Scoped Uninstall: Only project=samnet-wg labeled containers/images are removed.
• Non-Root Services: API and UI run as unprivileged users in Docker.

🎮 Interactive CLI (TUI)

• Smart Refresh: Flicker-free interface updates using tput and SIGWINCH handling.
• System Transparency: "About" screen explicitly lists all file paths.
• Auto-Init: Bandwidth tracking and databases initialize automatically.
• Context Preservation: Deep navigation menus that don't reset on refresh.

🔥 Firewall Management

• Integrated Port Manager: Manage open ports directly from the TUI (TCP/UDP support).
• Smart Detection: Automatically detects and whitelists existing services (Web, DB, Monitoring) during install.
• Docker Compatible: Runs safely alongside other containers without interfering with Docker networking.
• Mode Awareness: Detects existing firewalls (UFW/iptables) and adapts automatically.

🌐 Management

• Sync Engine: Edit files manually, use the CLI, or use the Web UI—it all stays in sync.
• Bandwidth Limits: Enforce data caps per peer (e.g., "10GB/month").
• Visualizations: ASCII graphs for bandwidth usage directly in the terminal.
• QR Codes: Instant mobile client onboarding.

🚀 Quick Start

One-Line Install (Recommended)

curl -sSL https://raw.githubusercontent.com/SamNet-dev/wg-orchestrator/main/install.sh | sudo bash

This downloads SamNet-WG and launches the interactive setup wizard where you can:

• Configure your VPN subnet
• Choose Web UI or CLI-only mode
• Set up firewall rules
• Create your first peer

Manual Install

git clone https://github.com/SamNet-dev/wg-orchestrator.git
cd wg-orchestrator
sudo ./samnet.sh

Zero-Touch Install (Scripted/Automated)

curl -sSL https://raw.githubusercontent.com/SamNet-dev/wg-orchestrator/main/install.sh | sudo bash -s -- --zero-touch

Web UI Default Login: admin / changeme

💻 Usage

Terminal Interface

sudo samnet    # Launch main menu

| Key | Menu Option | Description | |:---:|-------------|-------------| | 1 | 📊 Status Dashboard | System overview & health | | 2 | 🔧 Install / Repair | Zero-touch setup & self-healing | | 3 | 👥 Peer Management | Create, list, limit, & edit peers | | 4 | 🔐 Security & Access | Audit logs, user roles | | 5 | 📈 Observability | Live stats, graphs, & logs | | 6 | ⚙️ Advanced Tools | Firewall diff, backup, dry-run | | 7 | 📖 About / Docs | System paths & project info | | 8 | 🗑️ Uninstall | Safe, scoped removal | | Q | 🚪 Quit | Exit the application |

Common Operations

# Add a new peer
sudo samnet → Peers → Add Peer → Enter name → Scan QR
Create temporary access (auto-expires)
sudo samnet → Peers → Add Peer → Temporary → Set days
View live traffic
sudo samnet → Observability → Traffic Stats
Uninstall securely
sudo samnet --uninstall
Update to latest version
sudo samnet --update

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              SamNet-WG                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │   samnet.sh  │◄──►│   API (Go)   │◄──►│  UI (React)  │               │
│  │   CLI / TUI  │    │  Port 8766   │    │  Port 8080   │               │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘               │
│         │                   │                   │                       │
│         └─────────┬─────────┼───────────────────┘                       │
│                   │         │ (Sync Engine)                             │
│          ┌────────▼─────────▼────────┐                                  │
│          │    State (SQLite + FS)    │                                  │
│          │  /var/lib/samnet-wg/      │                                  │
│          │  /opt/samnet/clients/     │                                  │
│          └────────┬──────────────────┘                                  │
│                   │                                                     │
│          ┌────────▼────────┐                                            │
│          │   WireGuard     │                                            │
│          │   Kernel Mod    │                                            │
│          └─────────────────┘                                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

📁 File Locations

We believe in full system transparency. Here is exactly where SamNet-WG stores its data:

| Path | Description | |------|-------------| | /opt/samnet/ | Main installation directory (scripts, binaries). | | /opt/samnet/clients/ | Generated peer configuration files (.conf). | | /var/lib/samnet-wg/ | SQLite database and persistent application state. | | /var/log/samnet-wg/ | Application logs (rotated automatically). | | /etc/wireguard/ | WireGuard interface configuration (wg0.conf). | | /root/.samnet-wginitialcredentials | Initial admin credentials (delete after use). |

🔒 Security

• Argon2id password hashing.
• CSRF tokens on all state-changing API requests.
• Strict Input Validation preventing "Ghost Peers" (0.0.0.0 IPs).
• Constant-time auth comparisons.
• Docker Pruning Scoped to project=samnet-wg labels to avoid touching your other containers.

📋 Requirements

• OS: Debian 11+, Ubuntu 20.04+, Raspberry Pi OS
• RAM: 512 MB minimum
• Disk: 100 MB for CLI, 500 MB with Docker
• Network: Public IP or port forwarding (UDP 51820)

🗺️ Roadmap

✅ Recently Shipped (v1.0.4)

| Feature | Description | |---------|-------------| | 🚀 One-Line Install | curl -sSL ... \| bash for instant deployment | | 🔄 Auto-Update | samnet --update to upgrade without reinstalling |

Stay tuned for updates!

🤝 Contributing

Contributions welcome!

# Development setup
git clone https://github.com/SamNet-dev/wg-orchestrator.git
cd wg-orchestrator
Test changes in debug mode
sudo ./samnet.sh --debug

📄 License

MIT License - See LICENSE for details.

💖 Support

If this project helps you, consider supporting continued development:

samnet.dev/donate