vpnx-cli

VPNX

VPN Proxy Exchange — self-hosted rotating VPN proxy in one Docker container.

Free public VPN servers → SOCKS5 + HTTP proxy → REST API control.

What is this?

VPNX turns any Docker host into a rotating VPN proxy — no VPN subscription, no account needed.

It grabs free OpenVPN configs from public VPN servers, creates a VPN tunnel, and exposes it as a standard SOCKS5 + HTTP proxy you can use from any tool. Want to switch country or rotate to a new server? One API call.

Multi-source fallback — VPNX tries multiple sources to find working VPN servers:

• VPN Gate API (/api/iphone/) — CSV endpoint, fastest when available
• VPN Gate HTML scrape (/en/) — parses the website table and downloads .ovpn configs directly
• GitHub mirror — cached configs as last resort

If one source is down, VPNX automatically falls back to the next. No manual intervention.

What you get:

• 🔒 SOCKS5 proxy with auth (use from curl, browsers, scrapers, anything)
• 🌐 HTTP proxy with auth
• 🔄 REST API to connect, rotate, disconnect, and check status
• 🌍 7+ countries, 80+ servers available at any time
• 🏠 Works on any Linux Docker host — no VPN client needed on your machine

Use cases: web scraping with IP rotation, geo-testing, bypassing rate limits, hiding your origin IP.

Quick Start

docker run -d --name vpnx \
  --cap-add=NET_ADMIN --device=/dev/net/tun \
  -p 1080:1080 -p 8080:8080 -p 8000:8000 \
  -e API_TOKEN=your-secret \
  mocasus/vpnx:latest

Or use the CLI wrapper:

npm install -g @mocasus/vpnx && vpnx your-secret    # npm
pip install vpnx-cli && vpnx your-secret             # pip

Ports: SOCKS5 :1080 · HTTP :8080 · API :8000

Example session

# Check status
curl http://localhost:8000/status -H "Authorization: Bearer your-secret"
# → {"vpn": {"connected": false, ...}, "proxy": {"socks5": ":1080", ...}}

# Connect to a VPN server (auto-picks fastest)
curl -X POST http://localhost:8000/connect -H "Authorization: Bearer your-secret"
# → {"status": "connected", "server": "vpn599400160.opengw.net", "country": "Japan"}

# Use the proxy — traffic goes through VPN
curl --socks5 user:pass@localhost:1080 https://ifconfig.me
# → 36.14.213.219  (your VPN IP, not your real IP)

# Rotate to a new server
curl -X POST http://localhost:8000/rotate -H "Authorization: Bearer your-secret"
# → {"status": "connected", "server": "vpn851315872.opengw.net", ...}

# List available locations
curl http://localhost:8000/locations -H "Authorization: Bearer your-secret"
# → [{"country": "JP", "name": "Japan", "servers": 50, "speed": 948}, ...]

# Disconnect
curl -X POST http://localhost:8000/disconnect -H "Authorization: Bearer your-secret"

API

All endpoints require Authorization: Bearer <API_TOKEN> header.

Method	Endpoint	Description
POST	/login	Get proxy credentials
GET	/status	VPN + proxy status
POST	/connect?country=JP	Connect to VPN (auto-picks fastest if no country)
POST	/disconnect	Disconnect VPN
POST	/rotate?country=US	Rotate to a new VPN server
GET	/locations	List available VPN servers by country

Country filter

Pass ?country=XX (ISO 3166-1 alpha-2) to /connect or /rotate:

curl -X POST "http://localhost:8000/connect?country=JP" -H "Authorization: Bearer your-secret"
curl -X POST "http://localhost:8000/rotate?country=KR" -H "Authorization: Bearer your-secret"

Using the Proxy

# SOCKS5
curl --socks5 user:pass@host:1080 https://ifconfig.me

# HTTP
curl -x http://user:pass@host:8080 https://ifconfig.me

Get proxy credentials from /login or /status endpoint.

Configuration

Env Var	Default	Description
API_TOKEN	(required)	API authentication token
SOCKS_USER	vpnx<random>	Proxy username (auto-generated if not set)
SOCKS_PASS	<random>	Proxy password (auto-generated if not set)

Requires: Docker with --cap-add=NET_ADMIN + --device=/dev/net/tun (Linux host only)

How it works

┌─────────────────────────────────────────────────┐
│                  VPNX Container                  │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌───────────┐  │
│  │ FastAPI  │───▶│ VPN Mgr  │───▶│ OpenVPN   │  │
│  │ :8000    │    │          │    │ (tun0)    │  │
│  └──────────┘    └──────────┘    └─────┬─────┘  │
│       │                               │         │
│  ┌────▼────┐                   ┌─────▼─────┐  │
│  │ Dante    │                   │ VPN Gate  │  │
│  │ SOCKS5   │                   │ Servers   │  │
│  │ :1080    │                   │ (free)    │  │
│  └─────────┘                   └───────────┘  │
│  ┌─────────┐                                    │
│  │Tinyproxy│                                    │
│  │ HTTP    │                                    │
│  │ :8080   │                                    │
│  └─────────┘                                    │
└─────────────────────────────────────────────────┘

• Fetch — VPNX queries VPN Gate for available servers (API → HTML scrape → GitHub mirror)
• Connect — Downloads .ovpn config, starts OpenVPN daemon, waits for tunnel
• Proxy — Dante (SOCKS5) and Tinyproxy (HTTP) route traffic through the VPN tunnel
• Rotate — Kills old OpenVPN, picks next server, reconnects

🇮🇩 Bahasa Indonesia

Proxy VPN berputar dalam satu container Docker. Gratis, tanpa akun — pakai server VPN publik dari VPN Gate.

Multi-source fallback — VPNX otomatis beralih sumber server jika satu mati:

• VPN Gate API (CSV endpoint)
• VPN Gate HTML scrape (parse website + download config)
• GitHub mirror (cached configs)

Mulai Cepat

docker run -d --name vpnx \
  --cap-add=NET_ADMIN --device=/dev/net/tun \
  -p 1080:1080 -p 8080:8080 -p 8000:8000 \
  -e API_TOKEN=rahasia-anda \
  mocasus/vpnx:latest

Atau via CLI:

npm install -g @mocasus/vpnx && vpnx rahasia-anda    # npm
pip install vpnx-cli && vpnx rahasia-anda             # pip

API

Semua endpoint butuh header Authorization: Bearer <API_TOKEN>.

Method	Endpoint	Keterangan
POST	/login	Dapat kredensial proxy
GET	/status	Status VPN + proxy
POST	/connect?country=JP	Hubungkan ke VPN
POST	/disconnect	Putuskan VPN
POST	/rotate?country=US	Rotasi server VPN
GET	/locations	Daftar server VPN per negara

Menggunakan Proxy

curl --socks5 user:pass@host:1080 https://ifconfig.me   # SOCKS5
curl -x http://user:pass@host:8080 https://ifconfig.me    # HTTP

v2.0.0 · MIT License