Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Run a personal VPN in the cloud. And rotate it regularly.

VPN servers are a great way to hide your activity from the prying eyes of ISPs and obfuscate your location. But it's better to run your own VPN than to pay for a service, since the VPN service may be tracking you too. However, setting up a VPN is difficult. Add to that, it's probably wise to change the IP address of your VPN after a while. Usually, this means tearing the existing server down and standing up a new one in its place.

rotvpn is a pure Python utility that sets up a WireGuard full tunnel VPN with DNS (via unbound). It is designed to be ephemeral, so you can rotate to a new server with a single command.

Currently, only DigitalOcean and AWS are supported. Other providers may be added in the future... Got a favorite? Feel free to send a patch!


rotvpn installs and runs from your workstation.

You must have python3 in your path. You will need to create a virtual environment and install the dependencies:

python3 -m venv .env                                               # create the virtualenv
source .env/bin/activate                                           # start it up
python3 -m pip install --upgrade pip                               # upgrade installer
python3 -m pip install -r requirements.txt                         # install requirements


After you've installed the Python3 dependencies, you're ready to run your own VPN. Almost. Depending on which provider you use (Digitalocean is the default), you will need to export some variables into the environment.


You'll need to get a DigitalOcean API token. Export it into your environment:

export ROT_DO_TOKEN=123abc...

And you're ready to go.

AWS (Amazon Web Services)

You need an account ID, secret, and region, and you will need to export them into your environment like so:

export ROT_AWS_ID=AKI...
export ROT_AWS_SECRET=WM0...
export ROT_AWS_REGION=us-west-2

After that, you can run

Actually run it

If the two steps above are complete, you're ready to go. Make sure you're running in your virtualenv, and in the root of this repo. Then do something like

python3 --name my-cool-vpn

After the script runs, you should have a file named peer-tunnel-configs-<PROVIDER>-<NAME>.zip. <PROVIDER> will be one of the providers above, and <NAME> will be whatever you gave rotvpn in the --name parameter. Unzip and you will have 10 peer configurations.

Here is the usage for the script:

> python3 --help

usage: [-h] [--provider PROVIDER] [--name NAME] [--do DO]
                 [--config CONFIG]

optional arguments:
  -h, --help           show this help message and exit
  --provider PROVIDER  Specify the provider, i.e. digitalocean
  --name NAME          A name for your deploy, like 'mycoolvpn'. Lets you have
                       multiple deploys for a provider.
  --do DO              Provision or remove your VPN: --do provision | --do
  --config CONFIG      Optional JSON config for your provider

The --name parameter is the only one that is required. rotvpn defaults to DigitalOcean for --provider and the default --do action is provision. Any time you run the prior command, any existing server matching --name will be deleted, and a new server deployed with a new set of client configs (

Providers may have additional configuration fields they accept. If they do, you can use the --config parameter to pass in that information. For instance, the DigitalOcean provider defaults to the sfo2 region, and the s-1vcpu-1gb (smallest) sized droplet. If you want to change that, you can do something like:

python3 --name myvpn --config '{"region":"ams3", "size":"s-1vcpu-2gb-amd"}'

AWS currently supports changing the size of your instance. It defaults to ts.micro. You can modify this via --config, e.g.

python3 --provider aws --name my-cool-vpn --config '{"size":"t2.medium"}'

If you're done with the VPN for a while, you can simply remove it, and save some money until you need it again:

python3 --name my-cool-vpn --do remove

Client configuration


Install the WireGuard client from the App Store.

Open it and click 'Import tunnel(s) from file'.

Select one of the files unzipped from

It will load in your WireGuard client interface:

WireGuard MacOS

Click 'Activate'. Test your connection and IP address.


Much was learned from these posts:



Run a personal VPN in the cloud. And rotate it regularly.






No releases published


No packages published