Vortix: a terminal dashboard for WireGuard and OpenVPN tunnels

An orchestrator for the system tools, not a VPN implementation

Vortix is a terminal UI for WireGuard and OpenVPN with multi-tunnel control, real-time telemetry and leak guarding, and the sentence that defines its scope is this one: Vortix orchestrates the system wg, wg-quick and openvpn implementations, it does not implement either VPN protocol itself.

That is a real design decision rather than a limitation to apologise for. The cryptographic and routing work is done by the same binaries the operating system already ships or that the distribution packages, which means the thing you are trusting with your traffic is the well-known implementation rather than a new one. What Vortix adds is a control surface, a status model and a way to see what is actually happening on the wire.

The stated use case is narrow and real. 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. That is a gap between a one-line shell command and a commercial client, and a terminal UI is a reasonable place to sit in it.

The audience is operators on macOS and Linux who work locally or over SSH, and the project ships binaries through Homebrew, Debian and Fedora packages, Arch, Cargo, npm, Nix, a shell installer and a static musl build. The TUI framework is ratatui with crossterm, and the crate is written in Rust with a rust-version floor of 1.85.

The install has two halves, and the first one is not optional

The quick start asks for the protocol tools before anything else, and there is a table of commands per distribution:

# 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 openvpn

The readme is precise about the consequence. Only the .deb and .rpm packages pull these in, so with any other channel you install them first. Vortix drives wg-quick and openvpn as subprocesses, so without them a profile imports but cannot connect, and vortix up names the missing package and the install command for your distro. That last detail is good design, because the most common failure for a tool like this is a profile that imports cleanly and then silently fails to bring up a tunnel.

Vortix itself then installs through whichever channel you prefer, and the readme gives the full list: brew install vortix on macOS and Linux, which also installs the protocol tools, a .deb or .rpm from the releases page, pacman -S vortix on Arch, cargo binstall vortix for a prebuilt binary or cargo install vortix to build from source, npm install -g @harry-kp/vortix, nix profile install github:Harry-kp/vortix, a curl shell installer, and the static musl archive.

The Cargo route has a caveat worth reading: building from source needs about 4 GB of memory. That is a large build for a Rust binary, and it is the kind of constraint that makes the prebuilt channels the sensible default.

Importing a profile and driving it from the CLI

The first three commands are all you need to get moving:

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 work

The import command takes a .conf, an .ovpn, a URL or a directory, which covers the two common ways profiles arrive: a file on disk and a link from a provider.

The privilege model is the thing to understand before you start. Changing tunnels, routes, DNS or the firewall needs root, while list, show and status do not. So the read-only inspection of your tunnel state works as an ordinary user, and only the mutating commands need sudo. That split is what makes the tool usable in a script that runs as a monitoring agent, and it is also why the interactive dashboard is launched with sudo, since that is where the mutating actions live.

There is one install wrinkle the readme calls out. If sudo vortix is not found after a Cargo install or the shell installer, you link it once:

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

And the readme points to a usage guide for the full set of commands, keys and panels, since the visible quick start deliberately does not enumerate them.

Leak detection and the kill switch, which are the point of the tool

The security features are what separate Vortix from a nicer wg-quick wrapper, and they are described with unusual specificity for a project of this size.

The detection side is the security guard, and the readme frames the problem it solves directly: detect IPv4, IPv6 and DNS-policy exposure instead of assuming a successful handshake means traffic is protected. A green handshake indicator tells you the tunnel came up. It does not tell you that a route leaked around it, that a v6 path bypassed the tunnel, or that the resolver is still answering from the local network. The security guard panel shows IPv4 and IPv6 exposure, DNS state, encryption state and kill-switch state, and reduces them to one verdict.

The kill switch has three modes: off, block-on-drop and vpn-only, implemented with PF on macOS and nftables on Linux. The two platforms are named side by side in the highlights table, which is a useful signal, because a kill switch that silently does nothing on one of them is the classic failure in this category. The two implementations are not equivalent, and the readme does not pretend they are.

The leak detection demo is one of the four demos linked from the readme, alongside multi-connection, split tunnel and profile management. That combination of demos tells you the intended usage: not a single-tunnel status viewer, but a place where several tunnels coexist and the operator needs to reason about which one owns the default route.

Multi-tunnel, split tunnelling and the default route conflict

The multi-tunnel story is the part of the feature set with the most moving pieces, and the readme describes it in a way that reveals the underlying model.

You can connect multiple profiles and distinguish the default-route tunnel from split-route tunnels, and the highlights table adds that there is one default-route owner, with a Switch or Cancel choice on conflicts. That last detail is the important one. Two tunnels both claiming the default route is not a configuration you can resolve by picking a winner in a settings file, because the conflict only shows up when the second tunnel comes up, and the operator has to decide at that moment whether to hand over the default route or abort. Offering Switch or Cancel at the moment of conflict is a real workflow decision rather than a checkbox.

Split tunnelling is the second half, and it is where the 1024-route limit in the profiles row becomes relevant, since a WireGuard or OpenVPN profile can carry up to 1024 routes and the tool has to be able to hold and display them.

The telemetry panel is the third piece, and the list is long enough to be worth reading in full: throughput, latency, jitter, packet loss, public IP, ISP and location, plus exit identity and DNS policy from the feature list. Jitter and packet loss in particular are the numbers that explain a call that drops frames while a throughput graph looks healthy.

The alternative here is not another terminal tool but the desktop clients Vortix positions itself against, or a bare wg-quick invocation with a hand-rolled status script. The difference is that Vortix holds the multi-tunnel state and the exposure checks in one process instead of leaving you to correlate two separate tools.

Automation surface: versioned JSON, NDJSON, exit codes and hooks

The automation row in the highlights table is the one that decides whether this is a toy or something you can build on, and it lists a versioned JSON envelope, NDJSON watch streams, stable exit codes, shell completions and hooks.

The distinction that matters is between a terminal UI you can also script and a terminal UI that is only a terminal UI. A versioned JSON envelope means the output format has a contract, so a script parsing it does not break silently on a minor release. Stable exit codes mean the same for automation: a script can branch on success and failure without parsing prose. NDJSON watch streams give a line-oriented event feed, which is the shape a monitoring agent wants, and it is a different shape from the pretty panels.

The diagnostic side is similarly thorough: event logs, OpenVPN daemon logs, session journals, a per-process socket audit, and a vortix report command. The socket audit is the interesting one, because the leak detection story is fundamentally about which process opened which socket, and having that as a first-class output means you can check it after the fact rather than only trusting the verdict at the moment it appears.

The diagnostics documentation lives under docs/usage.md, and the configuration documentation including the hooks section lives under docs/configuration.md, which is also where the appearance options are described: seven built-in themes, including one that follows your terminal's colors.

State of the project: version 0.5, a fresh push, and a pinned dependency

The release history is short and recent. The most recent tags are v0.5.4 and v0.5.3, both on 2026-10-03, and v0.5.2 on 2026-09-27. The repository is not archived, and the last push was on 2026-10-19, so this is active work on a 0.x line.

The licence is MIT, and the workspace Cargo.toml names Harry KP as the author.

One dependency detail is worth flagging, because it is the kind of thing that catches a user out six months later. The time crate is pinned with an upper bound, and the comment in the manifest explains why: the bound excludes time 0.3.48, published 2026-06-12, which ships a fresh trait conflict that breaks cargo install vortix for anyone without --locked, and the cap is to be dropped once upstream releases a clean 0.3.49 or later. Until then, the pin keeps the canonical install command working for people installing from crates.io.

That is a good example of a pre-1.0 project absorbing upstream breakage. The same manifest also shows a deliberate choice with ratatui, where the all-widgets and macros default features are turned off because the Calendar widget and the macros are unused, so the binary does not carry them. The workspace members are crates/vortix and crates/xtask, with the former as the default member, and the repository also carries a nix flake, a release-plz configuration for release automation, a deny.toml for dependency auditing, a cliff.toml for changelog generation, and a tapes/ directory, which reads like a recorded test fixture set rather than a typical fixture folder.

Editorial conclusion

Vortix fits a Linux or macOS operator who runs WireGuard or OpenVPN profiles day to day and wants tunnel status, exposure warnings and a kill switch in one keyboard-driven view, and it does not fit a Windows user, a managed VPN client user, or anyone unwilling to run a tool with root access that rewrites routing and DNS. Before adopting it, install the protocol tools first and confirm vortix up can find them, read the usage guide for the JSON envelope and exit codes you would script against, and check the kill switch mode you want against the platform table, because PF and nftables are not the same implementation.

Frequently asked questions

Official sources

1. Harry-kp/vortix on GitHub
2. License: MIT
3. Project website
4. README
5. Releases