kvn

Keyboard-first TUI for managing VPN connections. It provides a fast, minimal interface for configuring profiles, connecting via sing-box and routing traffic.

---

Contents

• Features
• Supported Protocols
• Installation (Arch Linux)
  • AUR
  • Getting started
  • Polkit setup
  • Kill switch setup
  • Omarchy integration
  • Build from source
• Diagnostics
• Key Bindings
• Configuration
• Architecture
• Platform Support
• Contributing
• Author
• License

---

Features

• Vim-style navigation — j/k to move, gg/G to jump, ? for help
• Profiles & subscriptions — manage profiles and keep subscriptions automatically up to date
• Geo & service routing — choose country-based routing modes and ready-made overrides for selected services
• Kill switch — block outbound traffic if the VPN connection drops
• DNS presets — built-in Cloudflare and Quad9 DoH, Google DoT, and system resolver presets, custom presets with per-domain rules, and fake-IP
• Auto-connect & resume — restore the last connection on startup and after system resume
• Persistent daemon — keep the VPN and background services running after detaching the TUI
• Live insights — traffic rates, totals, active connections, and combined logs
• Diagnostics — check dependencies, configuration, daemon state, and integrations with kvn doctor
• Themes — choose from 22 bundled color palettes

---

Supported Protocols

kvn supports 12 sing-box outbound protocols. Profiles and subscriptions can be added from the clipboard using supported share links.

Protocol	Share-link scheme(s)	Key support
VLESS	vless://	REALITY, XTLS Vision, TLS with ECH; gRPC, WebSocket, HTTP, HTTPUpgrade, QUIC
Hysteria 2	hysteria2://, hy2://	QUIC, Salamander and Gecko obfuscation
Trojan	trojan://	TLS with ECH; gRPC, WebSocket, HTTP, HTTPUpgrade, QUIC
Shadowsocks	ss://	AEAD and AEAD-2022 ciphers; SIP002 and legacy Base64

More protocols

Protocol	Share-link scheme(s)	Key support
VMess	vmess://	Base64 JSON and URI formats; TLS with ECH and shared transports
TUIC	tuic://	TUIC v5, congestion control, and UDP relay modes
AnyTLS	anytls://	TLS-based multiplexing
NaiveProxy	naive+https://, naive+quic://, http2://	Chromium network stack over HTTP/2 or QUIC; no UDP
ShadowTLS	shadowtls://	Versions 1–3 with an inner Shadowsocks connection
SOCKS	socks://, socks5://, socks5h://, socks4://, socks4a://	SOCKS4, SOCKS4a, SOCKS5, and optional authentication
HTTP proxy	http://, https://	HTTP CONNECT with optional TLS and authentication
SSH	ssh://	Password and private-key authentication

---

Installation (Arch Linux)

Optional setup commands modify system or desktop configuration. See system integration details for installed files, permissions, and removal instructions.

AUR

yay -S kvn-bin \
  && systemctl --user enable --now kvn-tui.service

The package pulls in sing-box as a dependency and restores the TUN capabilities on /usr/bin/sing-box each time pacman upgrades it.

Getting started

Run kvn:

kvn

On first launch, kvn guides you through setup and your first VPN connection. You’ll need a VPN share link or subscription URL from your provider.

Polkit setup (optional)

Important

This setup and the kill switch setup below both add your user to the dedicated kvn-tui group; reboot once afterwards to activate it.

Polkit lets kvn auto-connect and reconnect without authentication prompts. Set it up:

sudo pacman -S --needed polkit \
  && sudo kvn setup --polkit

After setup and a reboot, toggle it with Shift+A. See Polkit setup for what it installs.

Kill switch setup (optional)

Warning

If the daemon crashes or cannot start while the kill switch is enabled, run this command to restore network access:

kvn disable --killswitch

The kill switch blocks internet traffic outside the VPN, including direct connections opened before it was enabled. See what kvn protects for its routing and local-network exceptions. Set it up:

sudo pacman -S --needed nftables \
  && sudo kvn setup --killswitch

After setup and a reboot, toggle it with Shift+K. See Kill switch setup for what it installs and how to remove it.

Omarchy integration (optional)

Omarchy is an Arch-based Linux distribution built around Hyprland. If you do not use it, skip this section. Omarchy 4 or newer is required.

Set up the standalone omakvn Quickshell bar plugin together with the kvn Apps menu entry, Hyprland shortcuts, and floating-window rules:

kvn setup --omarchy

The plugin shows live VPN status and provides profile selection and common VPN controls directly from the bar.

The idempotent installer creates backups before editing user configuration. Remove them after verification with:

kvn clean --omarchy-backups

This removes only the backups and leaves the active integration unchanged. See Omarchy setup for every file it changes and how to remove the integration.

Build from source

Requires Rust 1.98+, sing-box 1.14+, base-devel, dbus, and a clipboard tool (wl-clipboard on Wayland or xclip / xsel on X11).

yay -S base-devel rust dbus sing-box wl-clipboard \
  && git clone https://github.com/yarikov/kvn.git \
  && cd kvn

For a packaged installation with the binary in /usr/bin and the systemd user service included:

cd pkg/arch \
  && makepkg -si

Alternatively, install only the binary from the repository root:

cargo build --release --locked \
  && sudo install -Dm755 target/release/kvn-tui /usr/local/bin/kvn \
  && sudo setcap cap_net_admin,cap_net_raw+ep "$(command -v sing-box)"

The capabilities allow sing-box to use TUN without running kvn as root. The manual installation uses the automatic detached daemon. If you create a custom systemd user service, set its ExecStart to /usr/local/bin/kvn --daemon.

Diagnostics

kvn doctor

Runs a read-only check of sing-box, configuration, pending package migrations, the daemon, clipboard, and optional integrations, with remediation hints for detected problems.

---

Key Bindings

Navigation

Key	Action
Ctrl+h / Ctrl+←	Focus left pane
Ctrl+l / Ctrl+→	Focus right pane
j / ↓	Move or scroll down
k / ↑	Move or scroll up
gg / G	Go to the first / last item

Profiles

Key	Action
Enter	Connect to selected profile
e	Open profiles.json in $VISUAL or $EDITOR
y	Yank selected profile or subscription
p / Ctrl+V	Paste profile or subscription from clipboard
d	Delete selected profile or subscription
u / U	Update selected subscription / geo
i / I	Cycle subscription / geo auto-update
t / T	Test selected / all profiles

Logs

Key	Action
y	Copy the focused log record, or every record in the visual selection
Shift+V	Start a record-wise visual selection
j / k	Extend the visual selection by one complete log record
gg / G	Extend the visual selection to the start / end of the complete log buffer
Esc	Cancel the visual selection

Connection

Key	Action
r	Reconnect
s	Disconnect
Shift+A	Toggle auto-connect
Shift+K	Toggle kill switch

Settings

Key	Action
Space	Open settings menu
Space c	Connection settings
Space d	DNS settings
Space i	Interface settings
Space r	Routing settings
Backspace	Return from a settings page to the menu, discarding its changes

Dialogs

Key	Action
h / l, ← / →	Change selected value
Enter	Confirm selection or changes
y / n	Confirm / cancel the action
q / Esc	Cancel dialog

General

Key	Action
q / Esc	Detach the TUI from the main screen; in a dialog, cancel it (Esc cancels an active log selection first)
Ctrl+C	Stop the daemon, disconnect the VPN, and exit completely
?	Open or close help

On terminals supporting the Kitty keyboard protocol, letter shortcuts follow their physical US key positions regardless of the active keyboard layout.

---

Configuration

Configuration is stored in ~/.config/kvn-tui/profiles.json. Press e to edit it in $VISUAL or $EDITOR. Errors can be corrected in the same editing session; concurrent changes are merged, with conflicts reopened in the editor.

See the configuration guide for the JSON structure, advanced DNS and routing, validation, migrations, and runtime file locations.

---

Architecture

kvn is built with Rust on top of sing-box, with a persistent daemon and a TEA-style core. See the architecture overview for how the daemon, its clients and sing-box fit together, the IPC protocol, privileges, and the source layout.

---

Platform Support

Arch Linux and Omarchy are the officially supported platforms. The project may compile and run on other Linux distributions, but their installation and system integration are not tested or maintained by the project.

Contributing

Contributions are welcome, including support for other distributions from users who can test and help maintain it. Before opening a pull request, read CONTRIBUTING.md for branch naming, Conventional Commit and pull request title requirements, testing, and coverage expectations. Pull request titles are used in generated release notes.

Author

Created and maintained by Dmitry Yarikov — dmitry@yarikov.com.

If kvn saves you time, you can buy me a coffee ☕

License

MIT