| Status | |
|---|---|
| CI checks | |
| Latest version | |
| Release date | |
| Python | |
| License | |
| Open issues |
A terminal UI for managing OpenVPN connections with 2FA support.
- 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
- 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 gnupgUsing pipx (recommended):
pipx install vpnxOr with pip:
pip install vpnxvpnx setupThe setup wizard will guide you through:
- Adding VPN configurations (name, path to .ovpn file, up/down scripts)
- Setting your username (optional - will prompt at connection if not set)
- Configuring the password store (GPG key for secure credential storage)
# Connect to all configured VPNs
vpnx all
# Connect to a specific VPN
vpnx connect <vpn-name>
# List configured VPNs
vpnx listConfiguration 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
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: falsegit 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├── vpnx/
│ ├── domain/ # Business logic (entities, services)
│ ├── application/ # Use cases (commands, handlers)
│ ├── infrastructure/ # External integrations (OpenVPN, GPG)
│ └── presentation/ # UI components (TUI, CLI)
└── tests/ # Unit tests