vpnx

	Status
CI checks
Latest version
Release date
Python
License
Open issues

A terminal UI for managing OpenVPN connections with 2FA support.

Features

• Interactive setup wizard for configuring multiple VPNs
• Full-screen TUI with real-time connection status and bandwidth monitoring
• Secure credential storage using GPG encryption
• Support for up scripts (DNS/routing configuration)
• XDG Base Directory compliant configuration

Requirements

• Python 3.8+
• openvpn
• gpg (for encrypted password storage)

# macOS
brew install openvpn gnupg

# Debian/Ubuntu
sudo apt install openvpn gnupg

# Fedora
sudo dnf install openvpn gnupg2

# Arch
sudo pacman -S openvpn gnupg

Installation

Using pipx (recommended):

pipx install vpnx

Or with pip:

pip install vpnx

Setup

vpnx setup

The setup wizard will guide you through:

1. Adding VPN configurations (name, path to .ovpn file, up/down scripts)
2. Setting your username (optional - will prompt at connection if not set)
3. Configuring the password store (GPG key for secure credential storage)

Usage

# Connect to all configured VPNs
vpnx all

# Connect to a specific VPN
vpnx connect <vpn-name>

# List configured VPNs
vpnx list

# Manually run a VPN's configured down script (e.g. to reset DNS / routes
# left behind by a stale tunnel). Does not stop OpenVPN.
vpnx down <vpn-name>
vpnx down <vpn-name> --dev utun3   # override the tunnel interface (default: utun0)

Configuration

Configuration is stored in XDG-compliant directories:

~/.config/vpnx/
├── config.yaml        # Main configuration
└── up.sh              # Optional default up script

~/.local/share/vpnx/
├── credentials.gpg    # GPG-encrypted password
└── credentials.gpg-id # GPG key ID

~/.cache/vpnx/
└── logs/              # Connection logs

config.yaml format

username: your-username                            # optional, will prompt if not set
credentials_path: ~/.local/share/vpnx/credentials  # path to GPG-encrypted password
up_script: /path/to/up.sh                          # optional, global up script
down_script: /path/to/down.sh                      # optional, global down script

vpns:
  - name: PROD
    display: Production VPN
    config_path: /path/to/prod.ovpn
    needs_up_script: true
    up_script: /path/to/prod-up.sh      # optional, per-VPN override
    needs_down_script: true
    down_script: /path/to/prod-down.sh  # optional, per-VPN override
    needs_2fa: true                     # default: true
  - name: DEV
    display: Development VPN
    config_path: /path/to/dev.ovpn
    needs_up_script: false
    needs_down_script: false
    needs_2fa: false

Build from source

git clone https://github.com/pirhoo/vpnx.git
cd vpnx
pip install -e ".[dev]"

Then use make targets to run the project and development tasks:

make setup          # Configure VPN client
make all            # Connect to all configured VPNs
make connect VPN=x  # Connect to a specific VPN
make list           # List configured VPNs

make test           # Run tests
make lint           # Check code style
make format         # Auto-format code
make clean          # Remove cache files
make build          # Build sdist and wheel into dist/

Project Structure

├── vpnx/
│   ├── domain/          # Business logic (entities, services)
│   ├── application/     # Use cases (commands, handlers)
│   ├── infrastructure/  # External integrations (OpenVPN, GPG)
│   └── presentation/    # UI components (TUI, CLI)
└── tests/               # Unit tests