🚀 SotaConnect VPN CLI

A fast, single-binary cross-platform CLI client for Sota Connect / MeowConnect VPN service. Works seamlessly on Windows, Linux, and macOS.

✨ Features

• 🌐 Modern Web UI Dashboard: Embedded browser interface with live connection stats, 1-click server switching, real-time log streaming, latency gauges, and config editor.
• 🌍 Interactive Location Browser: Displays country names, flags, server types (Best / Bridge), and real-time TCP latency measurements.
• ⚡ Sing-box Core Management: Automatically downloads and manages official Sing-box releases matching your OS/architecture.
• 🛡️ Two Connection Modes:
  • TUN Mode (Full VPN): Complete system-wide transparent VPN routing.
  • Proxy Mode (Mixed SOCKS5 + HTTP): Local proxy (default 127.0.0.1:2080) with automatic system proxy configuration on Windows and desktop environments.
• 📋 VLESS Reality Share Link Exporter: Generates standard vless:// reality URLs for use with third-party clients (v2rayN, Clash, Nekoray, Shadowrocket, Streisand, etc.).
• 🔑 Zero-friction Credential Setup: Prompts for access key on first launch and safely persists configuration in standard OS locations (%APPDATA% on Windows, ~/.config/sotaconnect on Linux/macOS, or local ./config.json).
• 🛑 Graceful Shutdown: Restores DNS and system proxy settings cleanly on Ctrl+C.

---

🌐 Web UI Dashboard

SotaConnect includes an embedded, high-performance Web UI dashboard built directly into the single binary. You can run it interactively or as a detached background service (daemon).

Running in Foreground (Interactive)

# Launch the Web UI dashboard and automatically open your default browser
./sotaconnect web
# or: ./sotaconnect -web

# Access from other devices on your Wi-Fi / local network:
# It listens on 0.0.0.0:8899 by default and displays your LAN IP on startup (e.g. http://192.168.1.50:8899)

# Launch on custom port or restrict to localhost only
./sotaconnect web -web-port 9090
./sotaconnect web -web-host 127.0.0.1 -no-open

Running as a Background Service (Daemon)

# Start Web UI in background (detached daemon)
./sotaconnect web start
# or: ./sotaconnect web -d

# Check running Web UI service status (PID, URL, LAN IP, Uptime)
./sotaconnect web status

# View Web UI service logs
./sotaconnect web logs

# Stop background Web UI service
./sotaconnect web stop

Features available in the Web UI:

• Visual Connection Switch: 1-click connect/disconnect with live status glow, uptime counter, and active server banner.
• Server Explorer: Real-time ping testing, country search, filter by fast servers (<100ms), and 1-click connection.
• VLESS Reality Links: Copy links directly to clipboard for Happ, v2rayNG, and Hiddify, or export all server URLs to vless_links.txt.
• Live Service Logs: Real-time streaming log terminal with auto-scroll and pause toggle.
• Settings & Maintenance: Change access key, device name, proxy port, preferred mode (TUN/Proxy), and clean orphaned Wintun adapters.

---

📥 Installation & Building

1. Build from Source

Requires Go 1.20+ installed.

# Clone or navigate to the project directory
cd sotaConnect

# Build for current OS
go build -o sotaconnect ./cmd/sotaconnect

2. Cross-Compilation

# Windows 64-bit
GOOS=windows GOARCH=amd64 go build -o sotaconnect.exe ./cmd/sotaconnect

# Linux 64-bit / ARM64
GOOS=linux GOARCH=amd64 go build -o sotaconnect-linux-amd64 ./cmd/sotaconnect
GOOS=linux GOARCH=arm64 go build -o sotaconnect-linux-arm64 ./cmd/sotaconnect

# macOS (Apple Silicon / Intel)
GOOS=darwin GOARCH=arm64 go build -o sotaconnect-darwin-arm64 ./cmd/sotaconnect
GOOS=darwin GOARCH=amd64 go build -o sotaconnect-darwin-amd64 ./cmd/sotaconnect

---

🎮 Usage

1. Interactive Mode

Simply run the executable:

./sotaconnect

If no access key is configured, you will be prompted to enter your access key. Afterwards, an interactive menu allows you to:

1. ⚡ Quick connect to the lowest latency server.
2. 🌍 Browse servers and select a country.
3. 🔀 Toggle between TUN mode (Full VPN) and Proxy mode.
4. 📋 Export VLESS Reality share links.
5. 🔑 Manage credentials, change access key, or reset device HWID.

2. CLI Flags & Automation

# Start background VPN service (daemon) on fastest server
./sotaconnect start
# or: ./sotaconnect -start

# Start background VPN service on a specific location (gate ID 10)
./sotaconnect start -gate 10

# Check background service status (PID, location, mode, uptime)
./sotaconnect status
# or: ./sotaconnect -status

# View background service logs
./sotaconnect logs
# or: ./sotaconnect -logs

# Stop running background VPN service
./sotaconnect stop
# or: ./sotaconnect -stop

# Restart background VPN service
./sotaconnect restart

# List all locations with latency measurements
./sotaconnect -list

# Connect directly to the lowest latency server (foreground)
./sotaconnect -best

# Connect to a specific gate ID (foreground)
./sotaconnect -gate 10

# Force TUN mode (dynamically requests UAC / sudo if needed)
./sotaconnect -gate 10 -mode tun

# Run in Proxy mode on custom port 10808
./sotaconnect -gate 10 -mode proxy -port 10808

# Get VLESS Reality URL for fastest server (copy to v2rayNG / Happ / Hiddify)
./sotaconnect -export

# Get VLESS Reality URL for gate ID 10
./sotaconnect -gate 10 -export

# Batch export all server URLs to vless_links.txt
./sotaconnect -export-all

# Provide or override access key via CLI
./sotaconnect -key "YOUR_ACCESS_KEY" -best

---

⚙️ Configuration (config.json)

Saved automatically in:

• Windows: %APPDATA%\sotaconnect\config.json (or ./config.json in local directory)
• Linux/macOS: ~/.config/sotaconnect/config.json

Example:

{
  "access_key": "YOUR_ACCESS_KEY",
  "device_name": "Sota-Win-a1b2",
  "hwid": "0123456789abcdef0123456789abcdef",
  "preferred_mode": "tun",
  "mixed_port": 2080
}

---

🔒 Privileges Note for TUN Mode

• Windows: Run terminal / PowerShell as Administrator for TUN interface creation.
• Linux / macOS: Run with sudo ./sotaconnect (or grant CAP_NET_ADMIN on Linux).
• If run without elevated privileges, switch to Proxy mode for zero-privilege operation.