If you prefer manual setup:

# Install OpenVPN
sudo apt install openvpn

# Create config directory
mkdir -p ~/.vpn/servers

# Download .ovpn files from your VPN provider
# Put them in ~/.vpn/servers/

# Create credentials file
echo "your_username" > ~/.vpn/creds.txt
echo "your_password" >> ~/.vpn/creds.txt
chmod 600 ~/.vpn/creds.txt

# Enable passwordless sudo for openvpn
echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/openvpn, /usr/bin/killall" | sudo tee /etc/sudoers.d/openvpn

Usage

Decorator (Recommended)

from scripts.decorator import with_vpn_rotation

@with_vpn_rotation(rotate_every=10, delay=1.0)
def scrape(url):
    return requests.get(url).json()

# Automatically rotates VPN every 10 calls
for url in urls:
    data = scrape(url)

VPN Class

from scripts.vpn import VPN

vpn = VPN()

# Connect
vpn.connect()
print(vpn.get_ip())  # New IP

# Rotate (disconnect + reconnect to different server)
vpn.rotate()
print(vpn.get_ip())  # Different IP

# Disconnect
vpn.disconnect()

Context Manager

from scripts.vpn import VPN

vpn = VPN()

with vpn.session():
    # VPN connected
    for url in urls:
        vpn.before_request()  # Handles rotation
        data = requests.get(url).json()
# VPN disconnected

CLI

python scripts/vpn.py connect
python scripts/vpn.py status
python scripts/vpn.py rotate
python scripts/vpn.py disconnect
python scripts/vpn.py ip

Configuration

Decorator Options

@with_vpn_rotation(
    rotate_every=10,      # Rotate after N requests
    delay=1.0,            # Seconds between requests
    config_dir=None,      # Override config directory
    creds_file=None,      # Override credentials file
    country=None,         # Filter servers by country prefix (e.g., "us")
    auto_connect=True,    # Connect automatically on first request
)

VPN Class Options

VPN(
    config_dir="~/.vpn/servers",
    creds_file="~/.vpn/creds.txt", 
    rotate_every=10,
    delay=1.0,
    verbose=True,
)

Recommended Settings

API Aggressiveness	rotate_every	delay
Aggressive (Catastro, LinkedIn)	5	2.0s
Standard	10	1.0s
Lenient	20-50	0.5s

Files

vpn-rotate-skill/
├── SKILL.md              # This file
├── README.md             # Overview
├── scripts/
│   ├── vpn.py            # VPN controller
│   ├── decorator.py      # @with_vpn_rotation
│   └── setup.sh          # Setup wizard
├── examples/
│   └── catastro.py       # Spanish property API example
└── providers/
    ├── protonvpn.md      # ProtonVPN setup
    ├── nordvpn.md        # NordVPN setup
    └── mullvad.md        # Mullvad setup

Troubleshooting

"sudo: a password is required"

Run the setup script or manually add sudoers entry:

echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/openvpn, /usr/bin/killall" | sudo tee /etc/sudoers.d/openvpn

Connection fails

Check credentials are correct
Test manually: sudo openvpn --config ~/.vpn/servers/server.ovpn --auth-user-pass ~/.vpn/creds.txt
Check VPN provider account is active

Usage

Decorator (Recommended)

VPN Class

Context Manager

CLI

Configuration

Decorator Options

VPN Class Options

Recommended Settings

Files

Troubleshooting

"sudo: a password is required"

Connection fails

Still getting blocked

No .ovpn files

vpn-rotate-skill

VPN Rotate Skill

Setup

1. Run Setup Wizard

2. Manual Setup