Vortix

Terminal UI for WireGuard and OpenVPN with real-time telemetry and leak guarding.

Why Vortix?

I wanted a single interface to:

• See connection status, throughput, and latency at a glance
• Detect IPv6/DNS leaks without running separate tools
• Switch between VPN profiles without remembering CLI flags

Existing options (wg show, NetworkManager, Tunnelblick) either lack real-time telemetry or require a GUI.

Feature	Vortix	GUI Clients	CLI-only
Memory usage	~15MB	200-500MB	~5MB
Startup time	<100ms	2-5s	Instant
Real-time telemetry	✅	✅	❌
Leak detection	✅	Some	❌
Kill switch	✅	✅	Manual
Keyboard-driven	✅	❌	✅
Works over SSH	✅	❌	✅

Features

• WireGuard & OpenVPN — Auto-detects .conf and .ovpn files
• Advanced Telemetry — Real-time throughput, latency, jitter, and packet loss
• Geo-Location — Instant detection of your exit IP's city and country
• Leak detection — Monitors for IPv6 leaks and DNS leaks in real-time
• Kill Switch — Built-in firewall management for maximum security
• Interactive Import — Easily add new profiles directly within the TUI
• Config Viewer — Inspect profile configurations directly within the TUI
• Keyboard-driven — No mouse required

Requirements

Runtime dependencies

Dependency	macOS	Linux	Purpose
curl	Pre-installed	apt install curl	Telemetry and IP detection
openvpn	brew install openvpn	apt install openvpn	OpenVPN sessions
wireguard-tools	brew install wireguard-tools	apt install wireguard-tools	WireGuard sessions
iptables or nftables	N/A (uses pfctl)	Pre-installed	Kill switch
iproute2	N/A (uses ifconfig)	Pre-installed	Interface detection

Vortix checks for missing tools at startup and shows a warning toast with install instructions.

Build dependencies (source installs only)

• Rust 1.75+
• macOS 12+ or Linux kernel 3.10+ (5.6+ recommended for native WireGuard)

Quick install commands

Ubuntu/Debian:

sudo apt install curl wireguard-tools openvpn iptables iproute2

Fedora/RHEL:

sudo dnf install curl wireguard-tools openvpn iptables iproute

Arch Linux (only needed for source builds — pacman -S vortix handles deps automatically):

sudo pacman -S curl wireguard-tools openvpn iptables iproute2

DNS detection uses resolvectl (systemd-resolved) as the primary method, with nmcli (NetworkManager) and /etc/resolv.conf as fallbacks. Non-systemd distros (Alpine, Void, Gentoo OpenRC) will use the /etc/resolv.conf fallback automatically.

Installation

Homebrew (macOS/Linux):

brew install Harry-kp/tap/vortix

npm/npx:

npm install -g @harry-kp/vortix
# or run directly without installing:
npx @harry-kp/vortix

From crates.io:

cargo install vortix

Arch Linux (extra repo):

pacman -S vortix

Quick install (Binary):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Harry-kp/vortix/releases/latest/download/vortix-installer.sh | sh

Static binary (Linux):

Download the x86_64-unknown-linux-musl release from the releases page. This is a statically linked binary (no glibc needed), but you still need the runtime dependencies above (curl, openvpn/wireguard-tools, etc.).

Nix (flakes):

nix run github:Harry-kp/vortix        # Run without installing
nix profile install github:Harry-kp/vortix  # Install to profile

From source:

git clone https://github.com/Harry-kp/vortix.git
cd vortix
cargo install --path .

Linux: setting up sudo access

Vortix needs root to manage VPN connections and firewall rules. On Linux, sudo uses a restricted PATH (secure_path in /etc/sudoers) that does not include ~/.cargo/bin/ — so sudo vortix will fail with command not found.

Fix (one-time):

sudo ln -s ~/.cargo/bin/vortix /usr/local/bin/vortix

After this, sudo vortix works as expected.

Who is affected:

• cargo install vortix — yes
• Shell installer (curl | sh) — yes
• From source (cargo install --path .) — yes
• pacman -S vortix (Arch) — no, installs to /usr/bin/
• brew install (Homebrew) — no, installs to Homebrew prefix
• npm install -g (npm) — no, installs to npm global bin
• Nix (nix profile install) — no, installs to Nix profile bin
• macOS — no, sudo preserves user PATH

Usage

sudo vortix              # Launch TUI (requires root for VPN operations)
vortix import <file>     # Import a .conf or .ovpn profile
vortix info              # Show config directory and version
vortix update            # Self-update to latest release
vortix report            # Generate a bug report with system diagnostics

Keybindings

Key	Action
Tab	Cycle Focus (All Panels)
1-9	Connect to Quick-Slot 1-9
Enter	Connect / Toggle Profile
d	Disconnect Active Session
r	Reconnect Active Session
i	Import Profile (Direct)
v	View Profile Configuration
y	Copy Public IP to Clipboard
K	Toggle Kill Switch (Shift+K)
z	Toggle Zoom View (Panel)
x	Open Action Menu (Contextual)
b	Open Bulk Menu
Del	Delete Profile (Sidebar)
q	Quit Application

Configuration

Config directory

By default, vortix stores profiles, auth credentials, and logs in ~/.config/vortix/.

Override via CLI flag or environment variable:

sudo vortix --config-dir /path/to/custom/dir
# or
export VORTIX_CONFIG_DIR=/path/to/custom/dir
sudo vortix

Precedence: --config-dir flag > VORTIX_CONFIG_DIR env var > default path.

When running with sudo, vortix automatically resolves the invoking user's home directory (via SUDO_USER), so config files live in your home, not /root/.

Directory structure

~/.config/vortix/
├── profiles/                 VPN configuration files
│   ├── work.conf             WireGuard profile
│   └── office.ovpn           OpenVPN profile
├── auth/                     Saved OpenVPN credentials
│   └── office                Username + password for "office" profile
├── run/                      OpenVPN runtime files (temporary)
│   ├── office.pid            Daemon PID (source of truth for disconnect)
│   └── office.log            Raw daemon output (monitors connect/failure)
├── logs/                     Application logs (daily rotation)
│   └── 2026-02-09.log        Same content as the TUI Logs panel
├── config.toml               User settings (optional, see below)
├── metadata.json             Profile metadata (last used, sort order)
└── killswitch.state          Kill switch state for crash recovery

All files and directories are owned by your user account, even when vortix runs under sudo. You can read, modify, or delete anything here without elevated privileges.

Path	Mode	Description
profiles/	600	Your .conf and .ovpn files. Added via vortix import or the TUI.
auth/	600	Saved OpenVPN username/password pairs. One file per profile.
run/	644	OpenVPN only. PID and log files created during a VPN session. The .pid file identifies which daemon to kill; the .log is polled for success/failure. Cleaned up on disconnect. WireGuard doesn't use this.
logs/	644	Application session logs (daily rotation, configurable size/retention). Not the raw OpenVPN output in run/.
config.toml	644	Optional user settings. Only exists if you create it manually (see below).
metadata.json	644	Internal bookkeeping (last used, sort order). Auto-managed.
killswitch.state	644	Persists kill switch mode across crashes. Auto-managed.

Config file

Create ~/.config/vortix/config.toml to customize settings. All fields are optional -- missing fields use defaults:

# --- Timing ---
UI refresh rate in milliseconds (default: 1000)
tick_rate = 1000
Telemetry polling interval in seconds (default: 30)
telemetry_poll_rate = 30
HTTP API timeout in seconds (default: 5)
api_timeout = 5
Ping timeout in seconds (default: 2)
ping_timeout = 2
OpenVPN connection timeout in seconds (default: 20)
connect_timeout = 20
Max seconds to wait for a VPN disconnect before force-killing (default: 30)
disconnect_timeout = 30
--- Logging ---
Minimum log level shown in the TUI event log: "debug", "info", "warning", "error" (default: "info")
log_level = "info"
Maximum log entries kept in the TUI event log (default: 1000)
max_log_entries = 1000
Log file rotation size in bytes (default: 5242880 = 5 MB)
log_rotation_size = 5242880
Days to retain old log files (default: 7)
log_retention_days = 7
--- OpenVPN ---
OpenVPN daemon verbosity level, --verb flag, range 0-11 (default: "3")
openvpn_verbosity = "3"
--- Telemetry endpoints ---
Ping targets for latency measurement (tried in order)
ping_targets = ["1.1.1.1", "8.8.8.8", "9.9.9.9", "208.67.222.222"]
IPv6 leak detection endpoints
ipv6_check_apis = ["https://ipv6.icanhazip.com", "https://v6.ident.me", "https://api6.ipify.org"]
Primary IP/ISP API
ip_api_primary = "https://ipinfo.io/json"
Fallback IP APIs
ip_api_fallbacks = ["https://api.ipify.org", "https://icanhazip.com", "https://ifconfig.me/ip"]

How It Works

Telemetry: A background thread polls system network stats every second for throughput (macOS: netstat -ib, Linux: /proc/net/dev). Network quality (latency, jitter, loss) is calculated using multi-packet ICMP probes. Public IP, ISP, and Geo-location data are fetched via ipinfo.io/json.

Security (Kill Switch & Leak Detection):

• Kill Switch: Platform-native firewall integration. macOS uses PF (Packet Filter) via pfctl. Linux supports both iptables (with a dedicated VORTIX_KILLSWITCH chain) and nftables (with an atomic vortix_killswitch table) for clean teardown. Automatically blocks all non-VPN traffic when connection drops.
• IPv6 Leak: Active monitoring via api6.ipify.org. Any IPv6 traffic detected while VPN is active triggers a leak warning.
• DNS Leak: Monitors DNS configuration to ensure nameservers align with the secure tunnel (macOS: scutil --dns / networksetup, Linux: resolvectl / nmcli / /etc/resolv.conf).

WireGuard Integration: macOS resolves interface names via /var/run/wireguard/*.name. Linux uses kernel WireGuard interfaces directly (wg0, wg1, etc.). Both platforms parse wg show for handshake timing, transfer stats, and endpoint metadata.

OpenVPN Integration: Tracks session uptime and connection status via ps proc parsing. Interface detection uses ifconfig on macOS and ip addr on Linux.

Platform Notes

Feature	macOS	Linux
Kill switch	pfctl (PF)	iptables or nftables
Network stats	netstat -ib	/proc/net/dev
Interface detection	ifconfig + /var/run/wireguard/	ip addr + wg show
DNS detection	scutil --dns, networksetup	resolvectl, nmcli, /etc/resolv.conf
Default VPN iface	utun0	wg0
Tested distros	macOS 12+	Ubuntu, Fedora, Arch

Troubleshooting

Profiles missing after upgrade (Linux)

If you previously ran vortix with sudo and profiles were stored in /root/.config/vortix/, the app will offer a one-time migration prompt. Accept it to move your data to ~/.config/vortix/ under your real user account.

If you declined migration and want to keep using the old path:

sudo vortix --config-dir /root/.config/vortix

Permission denied errors

If config files are owned by root, fix ownership:

sudo chown -R $(whoami) ~/.config/vortix/

Roadmap

See the project board for what's being explored. Have an idea? Join the discussion.

Development

cargo build         # Build binary
cargo test          # Run unit/integration tests
cargo clippy        # Enforce code quality (Fail-fast via pre-commit)

Nix users can enter a development shell with all Rust tooling pre-configured:

nix develop

Featured In

• awesome-rust — A curated list of Rust code and resources
• awesome-ratatui — A curated list of Ratatui apps and tools
• awesome-tuis — A list of the best TUI programs
• Arch Linux [extra] — Official Arch Linux package repository
• Terminal Trove — The $HOME of all things in the terminal

Star History