proxy2vpn 0.14.0

Proxy2VPN Python utilities

Proxy2VPN

Enterprise-grade VPN container orchestration for developers who need reliable proxy infrastructure.

Stop wrestling with VPN clients that crash, managing multiple accounts manually, or dealing with inconsistent proxy setups. Proxy2VPN turns Docker containers into a fleet of rock-solid VPN endpoints you can deploy, monitor, and scale across dozens of countries in minutes.

Why Proxy2VPN?

The Problem: You need reliable proxy infrastructure for testing, scraping, or accessing geo-restricted content. Traditional VPN clients are unreliable, managing multiple accounts is painful, and scaling across regions is a nightmare.

The Solution: Containerized VPN services that just work. Deploy 50 VPN endpoints across 20 countries with a single command. Load-balance across multiple accounts automatically. Monitor health and rotate failed servers without intervention.

Real-world use cases:

• Web scraping with rotating IP addresses across multiple countries
• Testing geo-restricted applications from different regions
• Load balancing traffic across multiple VPN accounts
• Creating development environments that mirror production geography
• Building resilient proxy infrastructure for CI/CD pipelines

Key Features

• Fleet Management: Deploy VPN containers across multiple countries and cities in parallel
• Profile-based Credentials: Manage multiple VPN accounts as reusable configurations
• Intelligent Load Balancing: Distribute connections across accounts automatically
• Health Monitoring: Auto-rotate failed servers and maintain uptime
• HTTP Proxy Support: Built-in authenticated proxy endpoints for each VPN
• Provider Agnostic: Works with ProtonVPN, NordVPN, ExpressVPN, and 30+ providers via gluetun

Requirements

• Docker and Docker Compose
• Python 3.10+
• A VPN account from any supported provider

Quick Installation

# Install via uvx (recommended - no global dependencies)
uvx proxy2vpn --help

# Or install globally
pip install proxy2vpn

Note: uvx is part of the uv toolchain. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

5-Minute Quick Start

Get a VPN endpoint running in under 5 minutes:

# 1. Initialize your workspace
proxy2vpn system init

# 2. Create your first profile with VPN credentials (all fields required)
mkdir -p profiles
cat <<'EOF' > profiles/production.env
VPN_TYPE=openvpn
VPN_SERVICE_PROVIDER=protonvpn
OPENVPN_USER=your_protonvpn_username
OPENVPN_PASSWORD=your_protonvpn_password
HTTPPROXY=on
HTTPPROXY_USER=proxy_user
HTTPPROXY_PASSWORD=proxy_pass
EOF

# 3. Register the profile and create a VPN service
proxy2vpn profile create production profiles/production.env
proxy2vpn vpn create london-proxy production --port 8888 --location "United Kingdom"

# 4. Start and test your VPN
proxy2vpn vpn start london-proxy
proxy2vpn vpn test london-proxy

# 5. Use your proxy (HTTP proxy now available on localhost:8888)
curl --proxy http://proxy_user:proxy_pass@localhost:8888 https://httpbin.org/ip

That's it! Your VPN container is running and you have an authenticated HTTP proxy endpoint.

Container Management & Monitoring

Each VPN container exposes both HTTP proxy endpoints and control APIs for programmatic management:

# Check VPN status and public IP
proxy2vpn vpn status london-proxy
proxy2vpn vpn public-ip london-proxy

# Monitor logs and restart tunnels
proxy2vpn vpn logs london-proxy --follow
proxy2vpn vpn restart-tunnel london-proxy

# Bulk operations across all services
proxy2vpn vpn start --all
proxy2vpn vpn list --diagnose

Docker Integration: All containers use consistent labeling and networking, making them easy to integrate with existing Docker workflows and monitoring tools.

Control server authentication

To enable authenticated access to the Gluetun control API, create an auth configuration file such as:

[[roles]]
name = "qbittorrent"
routes = ["GET /v1/openvpn/portforwarded"]
auth = "basic"
username = "myusername"
password = "mypassword"

Bind mount this file to /gluetun/auth/config.toml (or set a custom path via the HTTP_CONTROL_SERVER_AUTH_CONFIG_FILEPATH environment variable) and restart the container for the configuration to take effect.

Enterprise Fleet Management

The real power of Proxy2VPN: Deploy and manage dozens of VPN endpoints across the globe like infrastructure, not individual connections.

Multi-Provider Fleet Orchestration (New!)

Automatic provider orchestration: Mix ExpressVPN, NordVPN, ProtonVPN in a single deployment. Each profile specifies its provider - the system coordinates everything automatically.

# Create profiles with provider information
cat <<'EOF' > profiles/expressvpn-main.env
VPN_TYPE=openvpn
VPN_SERVICE_PROVIDER=expressvpn
OPENVPN_USER=your_expressvpn_username
OPENVPN_PASSWORD=your_expressvpn_password
HTTPPROXY=on
HTTPPROXY_USER=proxy_user
HTTPPROXY_PASSWORD=proxy_pass
EOF

cat <<'EOF' > profiles/nordvpn-backup.env
VPN_TYPE=openvpn
VPN_SERVICE_PROVIDER=nordvpn
OPENVPN_USER=your_nordvpn_username
OPENVPN_PASSWORD=your_nordvpn_password
HTTPPROXY=on
HTTPPROXY_USER=proxy_user
HTTPPROXY_PASSWORD=proxy_pass
EOF

# Register profiles
proxy2vpn profile create expressvpn-main profiles/expressvpn-main.env
proxy2vpn profile create nordvpn-backup profiles/nordvpn-backup.env
proxy2vpn profile create protonvpn-fleet profiles/protonvpn-fleet.env

# Single command deploys across ALL providers automatically
proxy2vpn fleet plan \
  --countries "Germany,France,Netherlands,United Kingdom,United States" \
  --profiles "expressvpn-main:6,nordvpn-backup:4,protonvpn-fleet:8"

# Deploy multi-provider fleet in one operation
proxy2vpn fleet deploy --parallel

Result: 18 endpoints automatically distributed across 3 VPN providers, with coordinated port allocation and intelligent load balancing.

Scenario: Global Web Scraping Infrastructure

You need maximum IP diversity for scraping across 15 countries:

# Plan deployment: 20 endpoints across multiple providers for maximum diversity
proxy2vpn fleet plan \
  --countries "Germany,France,Netherlands,United Kingdom,United States,Canada" \
  --profiles "expressvpn-main:8,nordvpn-backup:6,protonvpn-fleet:6" \
  --unique-ips

# Deploy everything in parallel (typically completes in 2-3 minutes)
proxy2vpn fleet deploy --parallel --validate-first

# Check your fleet status - shows provider distribution
proxy2vpn fleet status --show-allocation

Result: 20 HTTP proxy endpoints across 3 different VPN providers, each with unique IP addresses for maximum scraping diversity.

Scenario: CI/CD Pipeline Testing

Your application needs testing from different geographic regions:

# Create a test fleet for your CI pipeline
proxy2vpn fleet plan \
  --countries "Germany,Singapore,United States" \
  --profiles "ci-testing:3" \
  --output ci-fleet.yaml

# Deploy only when tests run
proxy2vpn fleet deploy --plan-file ci-fleet.yaml --dry-run

Automatic Health Management

Fleet management includes intelligent health monitoring:

# Monitor and rotate failed endpoints automatically
proxy2vpn fleet rotate --criteria performance

# Scale up during high-demand periods
proxy2vpn fleet scale up --countries "United States,Germany" --factor 2

# Scale down to save resources
proxy2vpn fleet scale down --factor 0.5

Fleet management handles the complexity so you focus on your application, not infrastructure.

Common Use Cases

Web Scraping at Scale

# Multiple IPs across regions to avoid rate limiting
proxy2vpn fleet plan --countries "US,UK,DE,FR,CA" --profiles "scraping:10"
proxy2vpn fleet deploy --parallel

# Use any endpoint: curl --proxy http://user:pass@localhost:20001 https://api.example.com

Geo-location Testing

# Test your app from different countries
proxy2vpn vpn create us-east production --location "New York"
proxy2vpn vpn create eu-west production --location "Amsterdam"
proxy2vpn vpn start --all

CI/CD Pipeline Integration

# Include in your test pipeline
proxy2vpn fleet plan --countries "Germany,Singapore" --profiles "ci:2" --output tests/fleet.yaml
proxy2vpn fleet deploy --plan-file tests/fleet.yaml --validate-first
# Run your geo-specific tests
proxy2vpn fleet scale down --factor 0  # Clean up after tests

Development Environment

# Persistent development proxies
proxy2vpn vpn create dev-proxy dev-account --port 8888 --location "Netherlands"
# Always available at localhost:8888 for your development

Essential Commands

System operations

• proxy2vpn system init [--force]
• proxy2vpn system validate
• proxy2vpn system diagnose [--lines N] [--all] [--verbose] [--json]

Profiles

• proxy2vpn profile create NAME ENV_FILE
• proxy2vpn profile list
• proxy2vpn profile remove NAME
• proxy2vpn profile delete NAME
• proxy2vpn profile apply PROFILE SERVICE [--port PORT]

VPN services

• proxy2vpn vpn create NAME PROFILE [--port PORT] [--location LOCATION]
• proxy2vpn vpn list [--diagnose] [--ips-only]
• proxy2vpn vpn start [NAME | --all]
• proxy2vpn vpn stop [NAME | --all]
• proxy2vpn vpn restart [NAME | --all]
• proxy2vpn vpn logs NAME [--lines N] [--follow]
• proxy2vpn vpn delete [NAME | --all]
• proxy2vpn vpn test NAME

Server database

• proxy2vpn servers update
• proxy2vpn servers list-providers
• proxy2vpn servers list-countries PROVIDER
• proxy2vpn servers list-cities PROVIDER COUNTRY
• proxy2vpn servers validate-location PROVIDER LOCATION

Fleet management

• proxy2vpn fleet plan --countries "Germany,France" --profiles "acc1:2,acc2:8" [--output PLAN_FILE] [--unique-ips]
• proxy2vpn fleet deploy [--plan-file PLAN_FILE] [--parallel] [--validate-first] [--dry-run] [--force]
• proxy2vpn fleet status [--format table|json|yaml] [--show-allocation] [--show-health]
• proxy2vpn fleet rotate [--country COUNTRY] [--criteria random|performance|load] [--dry-run]
• proxy2vpn fleet scale up|down [--countries COUNTRIES] [--factor N]

Development

Setup

# Install with development dependencies
uv sync
# or
pip install -e ".[dev]"

Testing

# Run tests (if available)
pytest

Changelog Management

This project uses Towncrier for changelog management:

# Add a news fragment for your changes
echo "Your feature description" > news/<PR_NUMBER>.feature.md

# Preview the changelog
make changelog-draft

# Build the changelog (maintainers)
make changelog VERSION=x.y.z

---

Why Proxy2VPN Works

Infrastructure as Code: Treat VPN endpoints like any other infrastructure - version controlled, reproducible, and scalable.

Built for Developers: No GUI nonsense. Pure command-line interface that integrates with your existing workflows, CI/CD pipelines, and Docker toolchain.

Production Ready: Used for large-scale web scraping operations, geo-distributed testing, and enterprise proxy infrastructure. Battle-tested reliability with automatic health monitoring.

Zero Vendor Lock-in: Works with 30+ VPN providers. Switch providers, add accounts, or migrate configurations without rewriting your setup.

From Minutes to Milliseconds: Stop spending hours configuring VPN clients. Get from zero to working proxy infrastructure in under 5 minutes.

Scale When You Need: Start with a single endpoint, scale to hundreds across dozens of countries when your requirements grow.

Get Started Now

uvx proxy2vpn system init
uvx proxy2vpn --help

Join developers who've eliminated VPN configuration headaches and built reliable proxy infrastructure that just works.

License

MIT