vpn-rotate-skill

# VPN Rotate Skill

Rotate VPN servers to bypass API rate limits. Works with any OpenVPN-compatible VPN.

## Setup

### 1. Run Setup Wizard

```bash
./scripts/setup.sh
```

This will:
- Check OpenVPN is installed
- Help you configure your VPN provider
- Set up passwordless sudo
- Test the connection

### 2. Manual Setup

If you prefer manual setup:

```bash
# 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)

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

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

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

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

```python
@with_vpn_rotation(
    rotate_every=10,      # Rotate after N requests
    delay=1.0,            # Seconds between requests
    config_dir=None,      # Override config dir...

# 🔄 VPN Rotate Skill

**Break free from API restrictions. Rotate IPs. Scrape without limits.**

## The Problem

APIs fight back against data collection:
- 🚫 IP blocks after a few requests
- 🚫 Rate limits killing throughput
- 🚫 Geo-restrictions locking you out

## The Solution

Automatically rotate VPN servers to get fresh IPs. Works with **any OpenVPN-compatible VPN**:

- ✅ ProtonVPN
- ✅ NordVPN  
- ✅ Mullvad
- ✅ Any provider with .ovpn configs

## Quick Start

```bash
# 1. Setup (interactive)
./scripts/setup.sh

# 2. Use in Python
```

```python
from scripts.decorator import with_vpn_rotation

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

# Every 10 requests → new server → new IP → no blocks
for url in urls:
    data = scrape(url)
```

## How It Works

1. Connects to VPN server via OpenVPN
2. Makes N requests
3. Disconnects, picks new server
4. Reconnects with fresh IP
5. Repeat

## Success Rates

| Rotation | Success Rate | Speed |
|----------|--------------|-------|
| Every 5 requests | 95%+ | Slower |
| Every 10 requests | 90-95% | Medium |
| Every 20 requests | 80-90% | Faster |

## Use Cases

- **Government APIs** — Catastro, court records, public data
- **Real estate** — Idealista, Zillow, property registries
- **E-commerce** — Price monitoring, stock tracking
- **Search engines** — SERP data, rankings
- **Social media** — Profiles, posts, analytics

## Requirements

- Linux with OpenVPN (`apt install openvpn`)
- VPN account with OpenVPN support
- Passwordless sudo for openvpn (setup script handles this)

## Documentation

- [SKILL.md](SKILL.md) — Full API reference
- [providers/](providers/) — Setup guides for specific VPNs

---

*Stop fighting rate limits. Start rotating IPs.*