{"id":30130898,"url":"https://github.com/411a/protixy","last_synced_at":"2026-06-15T20:31:45.133Z","repository":{"id":305668324,"uuid":"981292562","full_name":"411A/Protixy","owner":"411A","description":"🌐 ProtonTinyProxy - A minimal and efficient local proxy setup using Docker, powered by ProtonVPN (via OpenVPN) and Tinyproxy.","archived":false,"fork":false,"pushed_at":"2025-11-21T18:02:02.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-21T20:11:54.243Z","etag":null,"topics":["docker","openvpn","openvpn-server","ovpn","protonvpn","proxy","proxy-configuration","proxy-server","vpn-gateway","vpn-server"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/411A.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-10T19:16:15.000Z","updated_at":"2025-11-21T18:02:06.000Z","dependencies_parsed_at":"2025-07-21T12:29:17.436Z","dependency_job_id":"a3c60787-1f80-4dcc-81f8-4f87c62989b7","html_url":"https://github.com/411A/Protixy","commit_stats":null,"previous_names":["411a/protixy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/411A/Protixy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/411A%2FProtixy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/411A%2FProtixy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/411A%2FProtixy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/411A%2FProtixy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/411A","download_url":"https://codeload.github.com/411A/Protixy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/411A%2FProtixy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34379915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","openvpn","openvpn-server","ovpn","protonvpn","proxy","proxy-configuration","proxy-server","vpn-gateway","vpn-server"],"created_at":"2025-08-10T18:10:59.144Z","updated_at":"2026-06-15T20:31:45.115Z","avatar_url":"https://github.com/411A.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/411A/Protixy)\n\n# OpenVPN Proxy with Automatic VPN Leak Detection\n\n❓ Ever wanted to use a different IP for your apps on your VPS?\u003cbr\u003e\n❓ Bought a Germany VPS but need a USA IP to connect to your favorite free LLM API?\u003cbr\u003e\n✨ This project is for you!\n\u003cbr\u003e\n💡 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.\n\n## Features\n\n- **Multi-Container Support**: Monitor multiple VPN proxies independently\n- **Automatic VPN Leak Detection**: External monitor detects and fixes IP leaks per container\n- **Self-Repairing**: Automatically recovers from connection failures\n- **Zero Manual Intervention**: Fully autonomous operation\n- **Smart Config Rotation**: Tries different VPN servers until one works\n- **Individual Health Monitoring**: Only restarts affected containers, healthy ones keep running\n\n## Prerequisites\n\n- Docker installed on your machine\n\n## 1. Download ProtonVPN OpenVPN Configs\n\n1. Visit: [ProtonVPN OpenVPN Downloads](https://account.protonvpn.com/downloads#openvpn-configuration-files)\n2. Log in to your ProtonVPN account.\n3. Choose a protocol (UDP/TCP) and download the `.ovpn` configuration files.\n4. Place all `.ovpn` files into the `ovpn_configs` directory.\n\n⚠️ 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.\n\n5. 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):\n```\nUsername\nPassword\n```\n\n## 2. Deploy\n\n1. SSH into your VPS and navigate to the project folder.\n2. Generate docker-compose.yml and start services:\n\n```bash\nchmod +x generate-compose.sh \u0026\u0026 ./generate-compose.sh 1 \u0026\u0026 docker compose --project-name protixy up -d --build\n```\n\n\u003e Change `1` to deploy multiple proxies (e.g., `3` creates ports 6101, 6102, 6103).\n\u003e \n\u003e ⚠️ ProtonVPN Free plan allows only 1 connection.\n\n3. Monitor the logs:\n\n```bash\n# VPN container logs\ndocker compose --project-name protixy logs -f vpn_proxy_1\n\n# Leak monitor logs\ndocker compose --project-name protixy logs -f monitor\n```\n\n---\n\n## VPN Leak Detection\n\nA separate monitor container checks only this Compose project's VPN proxy containers for IP leaks:\n\n- **Every 5 minutes**: Tests each proxy container individually\n- **Smart Restart**: Only restarts the affected container if leak detected\n- **Healthy Containers**: Keep running unaffected during restarts\n\nWhen you deploy 3 proxies with `./generate-compose.sh 3`, the monitor checks each one independently:\n\n```bash\n[monitor] Checking 3 container(s)...\n[monitor] Checking vpn_proxy_1 (port 6101)...\n[monitor]   OK vpn_proxy_1 is working correctly (Country: US)\n[monitor] Checking vpn_proxy_2 (port 6102)...\n[monitor]   LEAK DETECTED in vpn_proxy_2! Country is FI\n[monitor]   Restarting: vpn_proxy_2\n[monitor] Checking vpn_proxy_3 (port 6103)...\n[monitor]   OK vpn_proxy_3 is working correctly (Country: JP)\n```\n\n---\n\n## Project Structure\n\n```\n.\n├── Dockerfile                      # Container image definition\n├── docker-compose.yml              # Auto-generated by generate-compose.sh\n├── start.sh                        # Main container entrypoint (VPN + Tinyproxy)\n├── monitor.sh                      # External leak detector (separate container)\n├── healthcheck.sh                  # Docker health check (process monitoring)\n├── generate-compose.sh             # Deployment tool (auto-detects host country)\n├── diagnose.sh                     # Troubleshooting utility\n├── fix-ovpn-warnings.sh            # Optional: Patches OpenVPN config warnings\n├── tinyproxy.conf.template         # Tinyproxy configuration template\n└── ovpn_configs/                   # Your ProtonVPN .ovpn files\n    ├── *.ovpn                      # OpenVPN configuration files\n    └── proton_openvpn_userpass.txt # Your ProtonVPN credentials\n```\n\n---\n\n## Using VPN Proxies from Other Docker Containers\n\nThe proxy is accessible from the host at `http://127.0.0.1:6101`.\n\nFor container-to-container communication, connect to the `protixy_vpn_proxy_network`:\n\n```bash\ndocker network connect protixy_vpn_proxy_network your_container\n# Then use: http://protixy_vpn_proxy_1:6101 as proxy\n```\n\nOr in Docker Compose:\n\n```yaml\nservices:\n  your_app:\n    image: your-app:latest\n    networks:\n      - protixy_vpn_proxy_network\n    environment:\n      - HTTP_PROXY=http://protixy_vpn_proxy_1:6101\n      - HTTPS_PROXY=http://protixy_vpn_proxy_1:6101\n\nnetworks:\n  protixy_vpn_proxy_network:\n    name: protixy_vpn_proxy_network\n    external: true\n```\n\n---\n\n## Test Your Proxy\n\n```bash\n# Simple test\ncurl -s --proxy http://127.0.0.1:6101 https://ipinfo.io/json | jq -r '\"IP: \\(.ip) | Country: \\(.country)\"'\n\n# Python test\npython3 -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']}\\\")\"\n```\n\n---\n\n## Troubleshooting\n\n### Quick Diagnostic\n```bash\nchmod +x diagnose.sh \u0026\u0026 ./diagnose.sh\n```\n\n### Container restarting?\nNormal during initial connection. The system will:\n1. Try all VPN configs in random order  \n2. Wait 5 minutes if all configs fail\n3. Try again indefinitely until successful\n\n### Check leak monitor (all containers):\n```bash\ndocker compose --project-name protixy logs -f monitor\n```\n\n### Rate Limiting Issues:\nIf you see \"Rate limit exceeded\" errors in the monitor logs, the system now uses multiple free IP detection services. To get more reliable monitoring:\n\n1. **Increase check interval** (edit `CHECK_INTERVAL` in docker-compose.yml to 1800 for 30-minute checks)\n2. **Optional: Get IPinfo.io API token** for 50k requests/month:\n   - Sign up at https://ipinfo.io/signup\n   - Add your token to docker-compose.yml: `IPINFO_TOKEN=your_token_here`\n\n### Force server change:\n```bash\n# Restart specific proxy\ndocker compose --project-name protixy restart vpn_proxy_1\n\n# Restart all proxies\ndocker compose --project-name protixy restart\n```\n\n### View connection details:\n```bash\n# Specific container\ndocker compose --project-name protixy logs vpn_proxy_1 | grep \"Connection successful\"\n\n# All containers\ndocker compose --project-name protixy logs | grep \"Connection successful\"\n```\n\n### Check container health:\n```bash\n# Overview of all services\ndocker compose --project-name protixy ps\n\n# Specific container health check\ndocker compose --project-name protixy exec vpn_proxy_1 /usr/local/bin/healthcheck.sh\n```\n\n### Test multiple proxies individually:\n```bash\ncurl -s --proxy http://127.0.0.1:6101 https://ipinfo.io/country  # vpn_proxy_1\ncurl -s --proxy http://127.0.0.1:6102 https://ipinfo.io/country  # vpn_proxy_2\ncurl -s --proxy http://127.0.0.1:6103 https://ipinfo.io/country  # vpn_proxy_3\n```\n\n---\n\n## Advanced Configuration\n\n### Environment Variables\n\n**Monitor Container:**\n- `HOST_COUNTRY`: Auto-detected by generate-compose.sh\n- `CHECK_INTERVAL`: Seconds between checks (default: 900, was 300)\n- `PROJECT_LABEL`: Docker label used by the monitor to find this project's proxies\n- `ROLE_LABEL`: Docker label used by the monitor to find VPN proxy services\n- `IPINFO_TOKEN`: Optional IPinfo.io API token for higher rate limits\n\n**VPN Containers:**\n- `PROXY_PORT`: Tinyproxy listen port (auto: 6101, 6102, 6103...)\n- `HOST_COUNTRY`: Host country code for leak detection\n\n### Startup Script Variables (start.sh):\n- `VPN_CONNECT_TIMEOUT=20`: Seconds to wait for VPN connection\n- `RETRY_DELAY=300`: Seconds to wait after all configs fail\n\n### Manual Config Patching:\n```bash\n./fix-ovpn-warnings.sh\n```\nThis adds compatibility options to all `.ovpn` files. Backups are created automatically.\n\n## Next Steps\n\n- [ ] **Convert OpenVPN credentials to JSON for multi-account support**\n\nConvert `ovpn_configs/proton_openvpn_userpass.txt` into a structured `.json` file so multiple free ProtonVPN accounts can be managed and rotated programmatically.\n\n*Example: `proton_openvpn_accounts.json`*\n```json\n[\n  {\n    \"username\": \"account1@example.com\",\n    \"password\": \"password1\"\n  },\n  {\n    \"username\": \"account2@example.com\",\n    \"password\": \"password2\"\n  }\n]\n````\n\n*Why this helps*\n\n* Enables easy rotation between accounts\n* Simplifies automation and parsing\n* Scales cleanly as more accounts are added\n\n---\n\n- [ ] **Unified health-checked proxy endpoint (multi-container)**\n\nCreate a single proxy container that acts as a unified entry point for multiple proxy containers.\nThis container should continuously monitor the health of all underlying proxies and always route traffic to the latest working one.\n\n*Expected behavior*\n\n* Periodic health checks (latency, connectivity, or test requests)\n* Automatic failover when a proxy becomes unavailable\n* Zero manual intervention when proxies go down\n* Stable endpoint for all clients\n\n*High-level flow*\n\n```text\nClient\n  ↓\nUnified Proxy Container\n  ↓\n[ Proxy A | Proxy B | Proxy C ]\n   ↑        ↑        ↑\n Health checks + automatic selection\n```\n\n*Benefits*\n\n* High availability\n* Clean architecture\n* No client-side proxy switching logic required\n\n---\n\n- [ ] **Reorganize internal scripts**\n\nMove all non-user-facing scripts into the `scripts/` directory.\nThese scripts should only be invoked by the main entrypoint and must not be called directly by the user.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F411a%2Fprotixy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F411a%2Fprotixy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F411a%2Fprotixy/lists"}