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

Platform Support

Vortix is actively developed and used primarily on macOS.

Linux support is a current focus and is improving quickly, with CI coverage for Ubuntu and Fedora. Linux environments still vary a lot across distributions, firewall backends, DNS tooling, and privilege models, so distro-specific issues may still exist.

If you use Vortix on Linux and hit a problem, please open an issue and include vortix report output when possible. Ubuntu, Fedora, and Arch users are especially helpful when testing release candidates and validating fixes before release. If you want to help test Linux support, join the Linux tester discussion.

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 | | resolvconf / systemd-resolved | N/A (uses native DNS) | systemd-resolvconf or openresolv | WireGuard DNS management (optional, needed if DNS in config) | | 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.

DNS tools note: If your WireGuard profile includes a DNS = directive, Vortix will automatically detect and warn about missing DNS tools. Install accordingly:

• Arch/Fedora (systemd-based): sudo pacman -S systemd-resolvconf or sudo dnf install systemd-resolved
• Debian/Ubuntu: sudo apt install systemd-resolved (usually pre-installed)
• Alpine/Void (OpenRC): Vortix falls back to /etc/resolv.conf editing automatically

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 systemd-resolved

Fedora/RHEL:

sudo dnf install curl wireguard-tools openvpn iptables iproute systemd-resolved

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

sudo pacman -S curl wireguard-tools openvpn iptables iproute2 systemd-resolvconf

DNS management: Vortix uses resolvconf (via systemd-resolvconf or openresolv) to manage DNS when your WireGuard profile contains DNS =. On systemd distros (most modern Linux), this is automatic via systemd-resolved. Non-systemd distros (Alpine, Void, Gentoo OpenRC) will use /etc/resolv.conf editing as a fallback.

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

Linux support note

Most day-to-day development happens on macOS. Linux support is continuously tested in CI, but real-world distro coverage is still growing. If something behaves differently on your Linux setup, please treat that as useful signal and report it rather than assuming it is expected.

Usage

Vortix has two modes: an interactive TUI dashboard (default) and a headless CLI for scripting, automation, and AI agents.

sudo vortix              # Launch TUI dashboard (default)

CLI Commands

Every subcommand supports --json for machine-readable output and --quiet for silent operation (exit code only).

Connection:

sudo vortix up work-vpn         # Connect to a profile
sudo vortix down                # Disconnect (graceful)
sudo vortix down --force        # Force-disconnect (SIGKILL)
sudo vortix reconnect           # Reconnect to last used profile
vortix status                   # Show connection state + telemetry
vortix status --brief           # One-line: "● Connected to work-vpn"
vortix status --watch           # Live updates every 2s
vortix status --watch --json    # NDJSON stream for monitoring

Profile Management:

vortix list                     # List all imported profiles
vortix list --names-only        # Profile names for scripting
vortix list --sort last-used    # Most recently used first
vortix import ./work.conf       # Import a WireGuard profile
vortix import ./configs/        # Bulk import from directory
vortix show work-vpn            # Display profile configuration
vortix show work-vpn --raw      # Raw config file contents
vortix delete old-vpn --yes     # Delete without confirmation
vortix rename old-vpn new-vpn   # Rename a profile

Security:

sudo vortix killswitch auto     # Set kill switch to auto mode
sudo vortix killswitch always   # Always-on kill switch
vortix killswitch               # Show current mode
sudo vortix release-killswitch  # Emergency firewall release

System:

vortix info                     # Config paths, versions, profile count
vortix update                   # Self-update from crates.io
vortix report                   # Generate bug report
vortix completions ba