Terminal UI for WireGuard and OpenVPN with multi-tunnel control, real-time telemetry, and leak guarding.
See multi-connection, leak detection, split-tunnel, and profile-management demos
Multi-connection
|
Leak detection
|
Split tunnel
|
Profile management
|
Vortix gives WireGuard and OpenVPN users one keyboard-driven view of their tunnels and the network around them. It is useful when plain wg-quick or openvpn provides too little visibility, while a full desktop VPN client is too heavy or tied to one provider.
- Connect multiple profiles and distinguish the default-route tunnel from split-route tunnels.
- See throughput, latency, jitter, packet loss, exit identity, DNS policy, and encryption state.
- Detect IPv4, IPv6, and DNS-policy exposure instead of assuming a successful handshake means traffic is protected.
- Control the same engine from the TUI, CLI, or versioned JSON output.
- Work locally, over SSH, and across macOS and Linux.
Vortix orchestrates the system wg, wg-quick, and openvpn implementations; it does not implement either VPN protocol itself.
Install the protocol tools first:
# macOS
brew install wireguard-tools openvpn
# Ubuntu / Debian
sudo apt install wireguard-tools openvpn
# Arch / CachyOS / Manjaro
sudo pacman -S wireguard-tools openvpn
# Fedora
sudo dnf install wireguard-tools openvpnInstalling Vortix does not pull these in, whichever channel you use — Vortix drives
wg-quick and openvpn as subprocesses, so without them a profile imports but cannot
connect. vortix up names the missing package and the install command for your distro.
Then install Vortix using your preferred channel:
| Channel | Install |
|---|---|
| Homebrew | brew install Harry-kp/tap/vortix |
| Arch Linux | sudo pacman -S vortix |
| Cargo | cargo install vortix |
| npm | npm install -g @harry-kp/vortix |
| Nix | nix profile install github:Harry-kp/vortix |
| Shell installer | curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Harry-kp/vortix/releases/latest/download/vortix-installer.sh | sh |
| Static Linux binary | Download the musl archive from Releases |
Import a profile and connect:
vortix import ./work.conf # .conf, .ovpn, URL, or directory
sudo vortix # interactive dashboard
# Or stay in the CLI
sudo vortix up work
vortix status
sudo vortix down workTunnel and firewall changes require root. Read-only commands such as list, show, and status do not. If sudo vortix cannot find a Cargo-installed binary on Linux, link it once with sudo ln -s ~/.cargo/bin/vortix /usr/local/bin/vortix.
See the usage guide for command and keybinding references.
| Area | What Vortix provides |
|---|---|
| Protocols | WireGuard .conf and OpenVPN .ovpn / .conf profiles |
| Multi-tunnel | Concurrent tunnels, default-route ownership, split routes, conflict checks, and per-profile state |
| Telemetry | Throughput, latency, jitter, packet loss, public IP, ISP, and location |
| Security Guard | IPv4/IPv6 exposure, active DNS policy, encryption posture, and kill-switch state |
| Kill switch | off, block-on-drop, and vpn-only, using PF on macOS or atomic nftables on Linux |
| Automation | Human output, a versioned JSON envelope, NDJSON watch streams, and shell completions |
| Diagnostics | Event logs, session journals, per-process socket audit, and vortix report |
| Appearance | Seven built-in themes, including terminal-native light/dark colors |
| macOS | Linux | |
|---|---|---|
| VPN tools | Homebrew wireguard-tools, openvpn |
Distribution wireguard-tools, openvpn |
| Kill switch | PF (pfctl) |
nftables (nft) |
| DNS integration | System Configuration | systemd-resolved, NetworkManager, resolvconf, or /etc/resolv.conf fallback |
| CI coverage | macOS | Ubuntu and Fedora |
macOS is the primary development platform. Linux is tested continuously, but distributions vary in resolver, firewall, kernel, and privilege configuration. Reports from other distributions are valuable—include vortix report when possible.
Source builds require Rust 1.85 or newer. Linux kernel 5.6 or newer is recommended for native WireGuard.
Vortix runs privileged only because tunnel, route, DNS, and firewall mutation require it. The privileged path is intentionally narrow:
- Protocol execution stays in protocol-specific adapters around the installed
wg,wg-quick, andopenvpnbinaries. - Platform adapters own firewall, DNS, route, and kernel inspection behavior.
- Profile identity, process ownership, durable operations, and read-back checks fail closed when Vortix cannot prove the state it is managing.
- Sensitive profile and credential material is bounded, owner-checked, and kept out of normal logs and JSON output.
- Telemetry uses public IP/geolocation providers; Vortix has no hosted control plane or DNS-test service.
Kill-switch rules survive a Vortix restart within the same boot, but the OS may flush them during reboot. Re-arm vpn-only after each boot.
For the trust boundaries and threat analysis, read the privileged-helper threat model.
vortix import <PATH|URL> Add one profile or a directory
vortix list List profiles
vortix show <PROFILE> Inspect a profile with secrets masked
sudo vortix up <PROFILE> Connect
sudo vortix down [PROFILE] Disconnect one or every active tunnel
sudo vortix reconnect [NAME] Reconnect one or every active tunnel
vortix status [--watch] Show or stream state
vortix killswitch [MODE] Inspect or set off/block-on-drop/vpn-only
vortix audit Inspect process sockets and tunnel routing
vortix report Generate diagnostics for a bug report
Every command supports --json; watch commands emit NDJSON. Run vortix <COMMAND> --help for authoritative options.
Common TUI keys:
| Key | Action | Key | Action |
|---|---|---|---|
j / k |
Move through profiles | c / Enter |
Connect or disconnect |
Tab / Shift-Tab |
Move between panels | x |
Context action menu |
b |
Bulk action menu | p |
Switch color theme |
i |
Import profile | K |
Cycle kill-switch mode |
/ |
Search profiles | ? |
Full in-app help |
q |
Quit | z |
Zoom focused panel |
| Guide | Covers |
|---|---|
| Usage | TUI keys, CLI commands, JSON, multi-tunnel behavior, and automation |
| Configuration | Paths, files, themes, settings, DNS integration, and precedence |
| Troubleshooting | Startup, permissions, DNS, WireGuard, OpenVPN, firewall, and reporting |
| Migration | Upgrade and profile-storage changes |
| P0 release gate | Real-kernel and real-terminal checks that must pass before every release |
| Guide | Covers |
|---|---|
| Contributing | Development workflow and contribution entry points |
| CI parity | The exact checks to run before pushing |
| Architecture migration | Control-plane boundaries and migration direction |
| Privileged-helper threat model | Authority, ownership, replay, and recovery invariants |
| Project board | Active and planned work |
Contributions and real-world testing are welcome:
- Start with a good first issue.
- Run a scenario from the P0 release gate.
- Share Linux results in the Linux tester discussion.
- Use Discussions for questions and ideas.
Development starts with cargo build, cargo test, and the full CI parity suite before pushing. Nix users can run nix develop for the project shell.
awesome-rust · awesome-ratatui · awesome-tuis · Arch Linux extra · Terminal Trove · LinuxLinks · Orhun Parmaksız's spotlight · RustNation UK talk deck · JustTUI
mercury — keyboard-first API client for the terminal. 5 MB, 50 ms startup. · afk — menu bar break reminder, 2.8 MB.
