kenzuya/unshackle
1
0
Fork 1
mirror of https://github.com/unshackle-dl/unshackle.git synced 2026-03-10 08:29:00 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
b72a5dd84a33d1740daae3c197d8684858580f54
unshackle/docs/GLUETUN.md
Andy 965482a1e4 feat: merge upstream dev branch 
- Add Gluetun dynamic VPN-to-HTTP proxy provider
   - Add remote services and authentication system
   - Add country code utilities
   - Add Docker binary detection
   - Update proxy providers
2025-11-25 20:23:06 +00:00

4.0 KiB
Raw Blame History

Gluetun VPN Proxy

Gluetun provides Docker-managed VPN proxies supporting 50+ VPN providers.

Prerequisites

Docker must be installed and running.

# Linux
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER  # Then log out/in

# Windows/Mac
# Install Docker Desktop: https://www.docker.com/products/docker-desktop/

Quick Start

1. Configuration

Add to ~/.config/unshackle/unshackle.yaml:

proxy_providers:
  gluetun:
    providers:
      nordvpn:
        vpn_type: wireguard
        credentials:
          private_key: YOUR_PRIVATE_KEY

2. Usage

Use 2-letter country codes directly:

uv run unshackle dl SERVICE CONTENT --proxy gluetun:nordvpn:us
uv run unshackle dl SERVICE CONTENT --proxy gluetun:nordvpn:uk

Format: gluetun:provider:region

Provider Credential Requirements

Each provider has different credential requirements. See the Gluetun Wiki for complete details.

Provider VPN Type Required Credentials
NordVPN WireGuard private_key only
ProtonVPN WireGuard private_key only
Windscribe WireGuard private_key, addresses, preshared_key (all required)
Surfshark WireGuard private_key, addresses
Mullvad WireGuard private_key, addresses
IVPN WireGuard private_key, addresses
ExpressVPN OpenVPN username, password (no WireGuard support)
Any OpenVPN username, password

Configuration Examples

NordVPN/ProtonVPN (only private_key needed):

providers:
  nordvpn:
    vpn_type: wireguard
    credentials:
      private_key: YOUR_PRIVATE_KEY

Windscribe (all three credentials required):

providers:
  windscribe:
    vpn_type: wireguard
    credentials:
      private_key: YOUR_PRIVATE_KEY
      addresses: 10.x.x.x/32
      preshared_key: YOUR_PRESHARED_KEY  # Required, can be empty string

OpenVPN (any provider):

providers:
  expressvpn:
    vpn_type: openvpn
    credentials:
      username: YOUR_USERNAME
      password: YOUR_PASSWORD

Server Selection

Most providers use SERVER_COUNTRIES, but some use SERVER_REGIONS:

Variable Providers
SERVER_COUNTRIES NordVPN, ProtonVPN, Surfshark, Mullvad, ExpressVPN, and most others
SERVER_REGIONS Windscribe, VyprVPN, VPN Secure

Unshackle handles this automatically - just use 2-letter country codes.

Global Settings

proxy_providers:
  gluetun:
    providers: {...}
    base_port: 8888           # Starting port (default: 8888)
    auto_cleanup: true        # Remove containers on exit (default: true)
    verify_ip: true           # Verify IP matches region (default: true)
    container_prefix: "unshackle-gluetun"
    auth_user: username       # Proxy auth (optional)
    auth_password: password

Features

  • Container Reuse: First request takes 10-30s; subsequent requests are instant
  • IP Verification: Automatically verifies VPN exit IP matches requested region
  • Concurrent Sessions: Multiple downloads share the same container
  • Specific Servers: Use --proxy gluetun:nordvpn:us1239 for specific server selection

Container Management

# View containers
docker ps | grep unshackle-gluetun

# Check logs
docker logs unshackle-gluetun-nordvpn-us

# Remove all containers
docker ps -a | grep unshackle-gluetun | awk '{print $1}' | xargs docker rm -f

Troubleshooting

Docker Permission Denied (Linux)

sudo usermod -aG docker $USER
# Then log out and log back in

VPN Connection Failed

Check container logs for specific errors:

docker logs unshackle-gluetun-nordvpn-us

Common issues:

  • Invalid/missing credentials
  • Windscribe requires preshared_key (can be empty string)
  • VPN provider server issues

Resources