---

Protator

Automatic IP rotation tool for ProtonVPN CLI on Linux.

A clean, minimal, professional tool that automates IP rotation using `protonvpn-cli` or `protonvpn` installed on Linux systems.

---

Features

• 10 core commands for full VPN control
• Automatic rotation with configurable intervals
• Multiple rotation modes: sequential, random, latency
• Daemon support (background operation)
• Configuration management (~/.protator/config.yaml)
• Environment diagnostics
• Log output with optional follow mode
• Clean, professional output

Requirements

• Linux
• protonvpn-cli or protonvpn (v0.1.6+) installed and logged in
• C++17 compiler (for building from source)
• CMake 3.10+
• curl (for IP lookup)

Note on ProtonVPN Plans & Rotation Behavior:

• Protator works with both free and paid ProtonVPN plans
• Random mode (default): Lets ProtonVPN choose server randomly, Protator reads actual location
• Country-specific: If --country CODE used with paid plan, requests specific country. Falls back to random if unavailable
• Free plan: Rotation works seamlessly, ProtonVPN picks from available free servers automatically

Installation

Automatic Setup (Recommended)

Simply run the setup script - it will handle everything:

git clone https://github.com/BangAguse/Protator.git
cd Protator
chmod +x setup.sh
./setup.sh

The setup script will:

• Check for required build tools (cmake, g++)
• Build protator from source
• Install globally to /usr/local/bin/protator
• Configure ProtonVPN credentials
• Create default config file

Manual Setup (Advanced)

If you prefer to build manually:

cd Protator
mkdir build && cd build
cmake ..
make -j
cd ..
sudo make -C build install
./setup.sh  # Still need to run this for ProtonVPN config

Quick Start

After installation with ./setup.sh, use protator directly from anywhere:

protator doctor          # Check system status
protator start --interval 300 --background  # Start rotating IP every 5 min
protator status          # Check daemon status
protator ip              # Check current IP
protator stop            # Stop daemon and disconnect VPN

protator <command> [options]

1. start — Start automatic rotation

protator start [--interval SECONDS] [--country CODE] [--mode MODE] [--background]

Options:

• --interval SECONDS - Rotation interval (default: 300)
• --country CODE - Specific country code (e.g., US, FR, DE)
• --mode MODE - Rotation strategy: sequential, random, latency (default: random)
• --background - Run as daemon in background

Example:

protator start --interval 600 --mode sequential --background

2. stop — Stop running rotation

protator stop

Stops the daemon process if running in background.

3. rotate — Perform one immediate rotation

protator rotate

Rotates IP immediately without recurring loop.

4. status — Show current status

protator status

Output:

ACTIVE
Current IP: 36.83.91.227

5. ip — Show current public IP

protator ip

Output:

36.83.91.227

6. list — List available servers

protator list [--country CODE]

Shows available ProtonVPN servers. Optionally filter by country.

7. config — Manage configuration

protator config show
protator config get <key>
protator config set <key> <value>

Keys: interval, mode, country, background, logging

Example:

protator config set interval 600
protator config get mode

8. doctor — Run diagnostics

protator doctor

Checks:

• ProtonVPN CLI installed
• Logged in status
• Internet connectivity
• Permissions

9. logs — Show log output

protator logs [--follow]

Show log file. Use --follow for live tailing (like tail -f).

10. version — Show version info

protator version

Output:

Protator v0.1.0
Creator  : https://github.com/BangAguse
Language : C++
License  : MIT
Platform : Linux

Global Flags

• --help - Show help (per command)
• -v, --debug - Enable debug logging
• -h - Show help

Configuration

Config file: ~/.protator/config.yaml

Default structure:

interval: 300
mode: random
country: null
background: false
logging: true

Fields:

• interval - Seconds between rotations (default: 300)
• mode - sequential, random, or latency (default: random)
• country - Specific country code or null for any (default: null)
• background - Auto-daemonize if true (default: false)
• logging - Enable logs to ~/.protator/protator.log (default: true)

Rotation Logic

When rotation is triggered:

1. Disconnect from current VPN
2. Wait 2 seconds
3. Connect to new server based on mode:
   • sequential: Connect to servers in order
   • random: Pick a random server
   • latency: Connect to lowest-latency server (fallback: first available)
4. Log the event
5. Repeat if running in loop

Files

• Binary: /usr/local/bin/protator (installed globally by setup.sh)
• Config: ~/.protator/config.yaml (auto-created by setup.sh)
• Log: ~/.protator/protator.log (created on first run)
• PID: ~/.protator/protator.pid (daemon process ID file)

Examples

Rotate IP every 5 minutes in background

protator start --interval 300 --background
protator status

Rotate only through US servers

protator start --country US --mode random --background

Manual rotation

protator rotate

Check current IP

protator ip

View live logs

protator logs --follow

Stop background daemon

protator stop

Troubleshooting

Command not found

If protator is not found after installation:

1. Verify installation:

   which protator
   /usr/local/bin/protator --version

2. Re-run setup.sh:

   ./setup.sh

3. Add to PATH manually (if needed):

   export PATH="/usr/local/bin:$PATH"

Not logged in to ProtonVPN

1. Re-run the setup script (will prompt for login):

   ./setup.sh

2. Or login manually:

   protonvpn signin <your-username>

3. Verify login:

   protator doctor

Permissions issue

If you get permission errors:

1. Ensure ProtonVPN CLI is properly installed:

   which protonvpn-cli

2. Try running with sudo:

   sudo protator doctor

3. Check file permissions:

   ls -la ~/.protator/

No servers available

Check that ProtonVPN CLI is working:

protonvpn cities

Project Structure

Protator/
├── CMakeLists.txt          # Build configuration
├── setup.sh                # Setup & installation script
├── README.md               # Documentation
└── src/
    ├── main.cpp            # Entry point
    ├── cli.cpp/hpp         # CLI parsing & command routing
    ├── rotator.cpp/hpp     # Rotation logic
    ├── vpn.cpp/hpp         # VPN wrapper & integration
    ├── config.cpp/hpp      # Config file management
    ├── logger.cpp/hpp      # Logging system
    ├── diagnostics.cpp/hpp # System diagnostics
    └── scheduler.cpp/hpp   # Scheduler placeholder

Note: build/ directory is created temporarily during compilation and should not be committed to version control.

Technology

• Language: C++17
• Build System: CMake
• Logging: Internal lightweight logger
• Threading: std::thread
• VPN Integration: protonvpn-cli via system calls
• Platform: Linux

Author

Creator: BangAguse

License: MIT

Development Notes

Build

mkdir build && cd build
cmake ..
make -j

The binary protator will be created in the project root directory.

Clean

rm -rf build

Support & Donations

If you find Protator useful, consider supporting its development via donation.

DANA: 085756444803

Your support helps keep the project maintained and improved.