OpenVPN Proxy with Automatic VPN Leak Detection

❓ Ever wanted to use a different IP for your apps on your VPS?
❓ Bought a Germany VPS but need a USA IP to connect to your favorite free LLM API?
✨ This project is for you!
💡 It allows you to use any country's IP through ProtonVPN's OpenVPN configs and use it as a proxy so that your app requests go through it without exposing your real VPS IP.

Features

• Multi-Container Support: Monitor multiple VPN proxies independently
• Automatic VPN Leak Detection: External monitor detects and fixes IP leaks per container
• Self-Repairing: Automatically recovers from connection failures
• Zero Manual Intervention: Fully autonomous operation
• Smart Config Rotation: Tries different VPN servers until one works
• Individual Health Monitoring: Only restarts affected containers, healthy ones keep running

Prerequisites

• Docker installed on your machine

1. Download ProtonVPN OpenVPN Configs

1. Visit: ProtonVPN OpenVPN Downloads
2. Log in to your ProtonVPN account.
3. Choose a protocol (UDP/TCP) and download the .ovpn configuration files.
4. Place all .ovpn files into the ovpn_configs directory.

⚠️ The jp-free-1.protonvpn.udp.ovpn file included is a sample placeholder and will not work for actual connections. Replace it with a real .ovpn file from your ProtonVPN account.

5. Inside the ovpn_configs directory, open the existing proton_openvpn_userpass.txt file and add your ProtonVPN login credentials from ProtonVPN's account page:

Username
Password

2. Deploy

1. SSH into your VPS and navigate to the project folder.
2. Generate docker-compose.yml and start services:

chmod +x generate-compose.sh && ./generate-compose.sh 1 && docker compose up -d --build

Change 1 to deploy multiple proxies (e.g., 3 creates ports 6101, 6102, 6103).

⚠️ ProtonVPN Free plan allows only 1 connection.

3. Monitor the logs:

# VPN container logs
docker compose logs -f vpn_proxy_1

# Leak monitor logs
docker logs -f vpn_proxy_leak_monitor

---

VPN Leak Detection

A separate monitor container checks ALL VPN proxy containers for IP leaks:

• Every 5 minutes: Tests each proxy container individually
• Smart Restart: Only restarts the affected container if leak detected
• Healthy Containers: Keep running unaffected during restarts

When you deploy 3 proxies with ./generate-compose.sh 3, the monitor checks each one independently:

[monitor] Checking 3 container(s)...
[monitor] Checking vpn_proxy_1 (port 6101)...
[monitor]   OK vpn_proxy_1 is working correctly (Country: US)
[monitor] Checking vpn_proxy_2 (port 6102)...
[monitor]   LEAK DETECTED in vpn_proxy_2! Country is FI
[monitor]   Restarting: vpn_proxy_2
[monitor] Checking vpn_proxy_3 (port 6103)...
[monitor]   OK vpn_proxy_3 is working correctly (Country: JP)

---

Project Structure

.
├── Dockerfile                      # Container image definition
├── docker-compose.yml              # Auto-generated by generate-compose.sh
├── start.sh                        # Main container entrypoint (VPN + Tinyproxy)
├── monitor.sh                      # External leak detector (separate container)
├── healthcheck.sh                  # Docker health check (process monitoring)
├── generate-compose.sh             # Deployment tool (auto-detects host country)
├── diagnose.sh                     # Troubleshooting utility
├── fix-ovpn-warnings.sh            # Optional: Patches OpenVPN config warnings
├── tinyproxy.conf.template         # Tinyproxy configuration template
└── ovpn_configs/                   # Your ProtonVPN .ovpn files
    ├── *.ovpn                      # OpenVPN configuration files
    └── proton_openvpn_userpass.txt # Your ProtonVPN credentials

---

Using VPN Proxies from Other Docker Containers

The proxy is accessible from the host at http://127.0.0.1:6101.

For container-to-container communication, connect to the vpn_proxy_network:

docker network connect vpn_proxy_network your_container
# Then use: http://vpn_proxy_1:6101 as proxy

Or in Docker Compose:

services:
  your_app:
    image: your-app:latest
    networks:
      - vpn_proxy_network
    environment:
      - HTTP_PROXY=http://vpn_proxy_1:6101
      - HTTPS_PROXY=http://vpn_proxy_1:6101

networks:
  vpn_proxy_network:
    external: true

---

Test Your Proxy

# Simple test
curl -s --proxy http://127.0.0.1:6101 https://ipinfo.io/json | jq -r '"IP: \(.ip) | Country: \(.country)"'

# Python test
python3 -c "import requests; info = requests.get('https://ipinfo.io/json', proxies={'http':'http://127.0.0.1:6101','https':'http://127.0.0.1:6101'}).json(); print(f\"IP: {info['ip']} | Country: {info['country']}\")"

---

Troubleshooting

Quick Diagnostic

chmod +x diagnose.sh && ./diagnose.sh

Container restarting?

Normal during initial connection. The system will:

1. Try all VPN configs in random order
2. Wait 5 minutes if all configs fail
3. Try again indefinitely until successful

Check leak monitor (all containers):

docker logs -f vpn_proxy_leak_monitor

Rate Limiting Issues:

If you see "Rate limit exceeded" errors in the monitor logs, the system now uses multiple free IP detection services. To get more reliable monitoring:

1. Increase check interval (edit CHECK_INTERVAL in docker-compose.yml to 1800 for 30-minute checks)
2. Optional: Get IPinfo.io API token for 50k requests/month:
   • Sign up at https://ipinfo.io/signup
   • Add your token to docker-compose.yml: IPINFO_TOKEN=your_token_here

Force server change:

# Restart specific proxy
docker compose restart vpn_proxy_1

# Restart all proxies
docker compose restart

View connection details:

# Specific container
docker compose logs vpn_proxy_1 | grep "Connection successful"

# All containers
docker compose logs | grep "Connection successful"

Check container health:

# Overview of all services
docker compose ps

# Specific container health check
docker compose exec vpn_proxy_1 /usr/local/bin/healthcheck.sh

Test multiple proxies individually:

curl -s --proxy http://127.0.0.1:6101 https://ipinfo.io/country  # vpn_proxy_1
curl -s --proxy http://127.0.0.1:6102 https://ipinfo.io/country  # vpn_proxy_2
curl -s --proxy http://127.0.0.1:6103 https://ipinfo.io/country  # vpn_proxy_3

---

Advanced Configuration

Environment Variables

Monitor Container:

• HOST_COUNTRY: Auto-detected by generate-compose.sh
• CHECK_INTERVAL: Seconds between checks (default: 900, was 300)
• CONTAINER_PREFIX: Container name prefix (default: vpn_proxy_)
• IPINFO_TOKEN: Optional IPinfo.io API token for higher rate limits

VPN Containers:

• PROXY_PORT: Tinyproxy listen port (auto: 6101, 6102, 6103...)
• HOST_COUNTRY: Host country code for leak detection

Startup Script Variables (start.sh):

• VPN_CONNECT_TIMEOUT=20: Seconds to wait for VPN connection
• RETRY_DELAY=300: Seconds to wait after all configs fail

Manual Config Patching:

./fix-ovpn-warnings.sh

This adds compatibility options to all .ovpn files. Backups are created automatically.

Next Steps

• Convert OpenVPN credentials to JSON for multi-account support

Convert ovpn_configs/proton_openvpn_userpass.txt into a structured .json file so multiple free ProtonVPN accounts can be managed and rotated programmatically.

Example: proton_openvpn_accounts.json

[
  {
    "username": "account1@example.com",
    "password": "password1"
  },
  {
    "username": "account2@example.com",
    "password": "password2"
  }
]

Why this helps

• Enables easy rotation between accounts
• Simplifies automation and parsing
• Scales cleanly as more accounts are added

---

• Unified health-checked proxy endpoint (multi-container)

Create a single proxy container that acts as a unified entry point for multiple proxy containers. This container should continuously monitor the health of all underlying proxies and always route traffic to the latest working one.

Expected behavior

• Periodic health checks (latency, connectivity, or test requests)
• Automatic failover when a proxy becomes unavailable
• Zero manual intervention when proxies go down
• Stable endpoint for all clients

High-level flow

Client
  ↓
Unified Proxy Container
  ↓
[ Proxy A | Proxy B | Proxy C ]
   ↑        ↑        ↑
 Health checks + automatic selection

Benefits

• High availability
• Clean architecture
• No client-side proxy switching logic required

---

• Reorganize internal scripts

Move all non-user-facing scripts into the scripts/ directory. These scripts should only be invoked by the main entrypoint and must not be called directly by the user.