Turns Raspberry Pi into AWS based VPN control centre. Builds VPN server on EC2 with Shadowsocks QR code support. Also works on Ubuntu, Mac OSX and Debian.
Switch branches/tags
Clone or download
Latest commit b1c8cdb Dec 14, 2018


VPN Launchpad

Turns your Raspberry Pi (1/2/3/zero) into an AWS based VPN server control centre. Builds VPN server on EC2 with Shadowsocks and L2TP support.

Also works on Ubuntu (Xenial and above), Mac OSX(Yosemite and above) or Debian(Jessie and above).

How it works

Command vlp creates EC2 instance with Shadowsocks and L2TP support installed out of box. Command lproxy creates proxy (SOCKS/HTTP/DNS) container running locally on the Raspberry Pi box, which tunneling all traffic through the VPN server on EC2. AWS account ID/key is a necessary.

Quick start on Raspbian or Ubuntu

1. Dependencies installation

$ sudo apt-get update; sudo apt-get install docker.io git
$ sudo usermod -aG docker `whoami`; exit

Note: It is necessary to log out current session and back to get docker group setting take effect.

2. Initialize AWS credential and VPN server region

$ git clone https://github.com/samuelhbne/vpn-launchpad.git
$ cd vpn-launchpad
$ ./vlp init
AWS Secret Access Key [None]: INPUT-YOUR-AWS-KEY-HERE
Default region name [ap-northeast-1]: 
Default output format [json]: 

3. Build VPN server on AWS

$ ./vlp build
Randomise VPN passwords?(Y/n) 
Randomising VPN passwords...
Shadowsocks-URI: ss://YWVzLTI1Ni1nY206U1NTTElCRVYtUEFTUw==@
Scan QR code above from Shadowsocks compatible mobile app to connect your mobile phone/tablet.

QR code example

4. Connect your mobile phone

Scan the QR code generated above from Shadowsocks compatible mobile app (Shadowrocket for iOS or Shadowsocks for Android etc.) to connect your mobile phone/tablet and enjoy.

5. Build local proxy on Pi box (optional)

Jump to step 8 please if PC/Mac browser connection is not your goal.

$ ./lproxy build
Local proxy started.

Checking local HTTP PROXY on TCP:8123 ...
curl -x http://ifconfig.co

Checking local SOCKS PROXY on TCP:1080 ...
curl -x socks5h:// http://ifconfig.co

Checking local DNS PROXY on UDP:65353 ...
dig +short @ -p 65353 twitter.com


6. Browser configuration (optional)

Now modify connnection settings for Firefox, Safari or Chrome according to the proxy port settings given above.

7. Stop and remove local proxy container from Pi box after surfing (optional)

$ ./lproxy purge
Local proxy found. Purging...

8. Stop and remove VPN server from AWS after surfing

$ ./vlp purge
Waiting Instance shutdown...

Removing Security Group of vlp-bionic...
Security Group Removed.

Deleting SSH Key-Pair of vlp-bionic...

Note: Removing VPN server from AWS after surfing is always recommended. It removes the potential trails from cloud to protect your privacy as well as reduces the cost for AWS service hiring.

Quick tour for getting AWS account ID and key

  1. Create an new AWS free account here if you don't have. I'm not affiliate.
  2. Login into AWS IAM console with your account.
  3. Click "User" from left side then click "Add user" button on the top
  4. Choose the "User name" and tick "Programmatic access" box below
  5. Click "Next: Permissions" button
  6. Click "Create group" button
  7. Fill "Group name" with "vlpadmin" and tick "AdministratorAccess" selection box which on the top of the policy list
  8. Click "Create group" blue button at the bottom right of the page.
  9. Tick the "vlpadmin" selection box in "Add user to group" page
  10. Click "Next: Review" then click "Create user" button
  11. Click "Show" link
  12. Now you get the "Access key ID" and "Secret access key" that necessary for vpn-launchpad running

Follow the official AWS doc page for more details

vpn-launchpad command Usage

VPN server management

./vlp <command> [options]
  init        -- Init aws account credential.
  build       -- Build VPN server.
  status      -- Check VPN server status.
  purge       -- Destory VPN server instance.
  random      -- Randomise VPN passwords.

Local proxy management

./lproxy <command> [options]
  build       -- Build local proxy container.
  status      -- Check local proxy container status.
  purge       -- Destory local proxy container.

Note: Please build VPN server before local proxy building.

VPN server and local proxy configuration

Password, encryption method and listening port for ShadowSocks VPN.

$ cat server-ssslibev/ssslibev.env
SSPORT=" 8388"

NOTE: './vlp purge && ./vlp build' is necessary to get new VPN configuration applied.

Credits to shadowsocks-libev

Username, password and pre-shared secret for L2TP VPN.

$ cat server-softether/softether.env

NOTE: './vlp purge && ./vlp build' is necessary to get new VPN configuration applied.

Credits to Tomohisa Kusano and SoftEtherVPN

SOCKS/HTTP/DNS port for local proxy

$ cat proxy-ssllibev/proxy-sslibev.env

NOTE: './lproxy build' is necessary to get new proxy configuration applied.

Credits to shadowsocks-libev

Before running

Docker installation is necessary for running vlp and lproxy. curl and dig are convenient tools for connection test and diagnosis but not compulsory.

Docker installation for Raspbian or Ubuntu

$ sudo apt-get update; sudo apt-get install docker.io
$ sudo usermod -aG docker `whoami`; exit

Docker installation for Mac OSX


Connect to the VPN server via Shadowsocks from mobile devices:

Both "vlp build" and "vlp status --qrcode" print QR code as well as the shadowsocks URI. Scanning this QR code from Shadowsocks compatible mobile apps (Shadowrocket for iOS or Shadowsocks for Android etc.) will gives you a new connection entry named VLP-shadowsocks. Connect and Enjoy please. QR code example

All credits to qrcode-terminal

Connect to the VPN server via L2TP:



Frequently Asked Questions