Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/411a/protixy

🌐 ProtonTinyProxy - A minimal and efficient local proxy setup using Docker, powered by ProtonVPN (via OpenVPN) and Tinyproxy.
https://github.com/411a/protixy

docker openvpn openvpn-server ovpn protonvpn proxy proxy-configuration proxy-server vpn-gateway vpn-server

Last synced: 12 days ago
JSON representation

🌐 ProtonTinyProxy - A minimal and efficient local proxy setup using Docker, powered by ProtonVPN (via OpenVPN) and Tinyproxy.

Awesome Lists containing this project

README 

          
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/411A/Protixy)



# 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](https://account.protonvpn.com/downloads#openvpn-configuration-files)

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](https://account.protonvpn.com/account-password#openvpn):

```

Username

Password

```



## 2. Deploy



1. SSH into your VPS and navigate to the project folder.

2. Generate docker-compose.yml and start services:



```bash

chmod +x generate-compose.sh && ./generate-compose.sh 1 && docker compose --project-name protixy 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:



```bash

# VPN container logs

docker compose --project-name protixy logs -f vpn_proxy_1



# Leak monitor logs

docker compose --project-name protixy logs -f monitor

```



---



## VPN Leak Detection



A separate monitor container checks only this Compose project's 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:



```bash

[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 `protixy_vpn_proxy_network`:



```bash

docker network connect protixy_vpn_proxy_network your_container

# Then use: http://protixy_vpn_proxy_1:6101 as proxy

```



Or in Docker Compose:



```yaml

services:

  your_app:

    image: your-app:latest

    networks:

      - protixy_vpn_proxy_network

    environment:

      - HTTP_PROXY=http://protixy_vpn_proxy_1:6101

      - HTTPS_PROXY=http://protixy_vpn_proxy_1:6101



networks:

  protixy_vpn_proxy_network:

    name: protixy_vpn_proxy_network

    external: true

```



---



## Test Your Proxy



```bash

# 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

```bash

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):

```bash

docker compose --project-name protixy logs -f 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:

```bash

# Restart specific proxy

docker compose --project-name protixy restart vpn_proxy_1



# Restart all proxies

docker compose --project-name protixy restart

```



### View connection details:

```bash

# Specific container

docker compose --project-name protixy logs vpn_proxy_1 | grep "Connection successful"



# All containers

docker compose --project-name protixy logs | grep "Connection successful"

```



### Check container health:

```bash

# Overview of all services

docker compose --project-name protixy ps



# Specific container health check

docker compose --project-name protixy exec vpn_proxy_1 /usr/local/bin/healthcheck.sh

```



### Test multiple proxies individually:

```bash

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)

- `PROJECT_LABEL`: Docker label used by the monitor to find this project's proxies

- `ROLE_LABEL`: Docker label used by the monitor to find VPN proxy services

- `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:

```bash

./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`*

```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*



```text

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.