A VPN manager for the Omarchy 4 shell: a bar widget, a panel and an app window for WireGuard, AmneziaWG, OpenVPN, Windscribe, Cloudflare WARP, VLESS and Shadowsocks keys, Happ/INCY subscriptions and any VPN managed by NetworkManager.
Omarchy 3 (Waybar + Walker) is served by waybar-vpn-manager (archived at v0.3.0).
- Bar widget — a lock icon with the active connection; a left click opens the panel, a right click (or SUPER+Shift+V) the app window.
- Every server in one list — Happ/INCY grouped by subscription, WireGuard, AmneziaWG, OpenVPN,
Windscribe, Cloudflare WARP, imported keys and NetworkManager VPNs. Filter with
/(by name, protocol or country code), connect with a click or Enter, star favourites for quick connect. - Happ without the Happ window — servers come straight from your subscriptions and connect in the background; the Happ app keeps working alongside.
- Protection checks — the panel says Protected only once the exit country, DNS and IPv6 all check out; otherwise Unverified or At risk, with the reason.
- Kill switch — no tunnel, no internet (see Kill switch).
- IPv6 leak guard — IPv6 is off while a VPN is up (none of these tunnels carry it), also at boot for WireGuard, AmneziaWG and OpenVPN autostart.
- DNS through the tunnel for Happ and keys.
- Tools — DNS leak test, IP info, speed test, ping through each server, refresh subscriptions, clear caches.
- Import and manage profiles — a config file or a pasted
vless:///ss://key; toggle autostart or delete WireGuard/AmneziaWG/OpenVPN/NetworkManager profiles.
omarchy plugin add https://github.com/moonmouse11/omarchy-vpn --enableomarchy plugin add only downloads the plugin. The widget then shows Setup needed: open its
panel and press Finish setup. A terminal opens, asks which protocols and features you want,
then your sudo password once, and installs what's missing. You can review the script first:
~/.config/omarchy/plugins/omarchy-vpn/install.sh (or run it yourself).
After omarchy plugin update omarchy-vpn the panel shows Update setup — press it once more.
From a checkout instead: git clone https://github.com/moonmouse11/omarchy-vpn && cd omarchy-vpn && make install.
You install yourself, if you want them: Happ (AUR: happ-desktop-bin — also needed for
VLESS/Shadowsocks keys), INCY Desktop (see INCY setup), and AmneziaWG
(AUR: amneziawg-tools plus amneziawg-dkms and
linux-headers, or prebuilt amneziawg-linux for the stock kernel). The installer
reminds you when you pick them.
- Installs only the packages your picks need (
wireguard-tools,openvpn, aresolvconf). - Adds root-owned helpers to
/usr/local/bin(omarchy-vpn-helper,happ-killswitch,openvpn-dns-updown,omarchy-vpn-incy-network,omarchy-vpn-dns-bootstrap) and the isolated INCY/DNS root modules to/usr/local/lib/omarchy-vpn. The sudoers rule (/etc/sudoers.d/vpn-manager) grants access only toomarchy-vpn-helper,happ-killswitchand the IPv6 guard's fixedsysctlcalls. OpenVPN invokes its DNS helper; the main helper invokes the fixed INCY/DNS entries. Privileged helper sources are copied before the sudo prompt and re-hashed after installation. The main helper refuses VPN configs that would run commands as root. - Copies the app to
~/.local/share/omarchy-vpnand adds the SUPER+Shift+V binding to~/.config/hypr/bindings.lua. - Keeps managed systemd drop-ins for enabled VPN profiles: the IPv6 boot guard, and for OpenVPN, the same PID/DNS lifecycle as desktop connections. Uninstall removes these drop-ins.
/etc/resolv.confis left alone, unless you agree to switch it back to systemd-resolved when the installer asks.
The plugin resolves WireGuard, AmneziaWG and OpenVPN endpoint hostnames once, then passes the
same IPv4 answers to the firewall and a private runtime profile. It does not replace the
profile's DNS settings. On a plugin-managed disconnect, SaveConfig=true keeps native state
changes while restoring original hostnames and IPv6 AllowedIPs for matching WireGuard/AmneziaWG
peers, plus IPv6 interface addresses omitted while the guard was active.
External wg-quick/systemd operations retain their own native save behavior. If the source profile
changes before a pending save is recovered, recovery refuses to overwrite it and retains the private
runtime for manual reconciliation. Explicitly deleting an inactive profile discards its old runtime,
so reimporting the same name cannot restore old credentials.
OpenVPN option names must be plain (for example, remote, not "remote" or an escaped spelling).
Unsupported directive syntax is rejected before native startup; quoted hostname arguments and
ordinary trusted hooks/settings remain supported.
Bootstrap uses UDP/TCP port 53 to configured upstreams, not a public fallback. Server errors such as
SERVFAIL/REFUSED try the next configured upstream within the same deadline; NXDOMAIN stays terminal. IPv4 /etc/hosts
overrides are preserved without a DNS query. Strict DNS-over-TLS and unrecognized local DNS
proxies are refused rather than silently bypassed; no resolver settings are rewritten.
The connect-time allowance requires the dedicated socket mark and a configured upstream on
TCP/UDP :53: it does not open ordinary app/shared-resolved DNS, :853, another destination or a
general mark bypass. Guarded firewall loads never scrape unrelated TCP sessions or merge saved
IPs. Handled exits/cancellation close the DNS session and remove bootstrap permission; a failed
firewall reload is reported. SIGKILL cannot run Python cleanup: owned FDs close and the next guarded
load replaces the rules. This is not a sandbox against another process with the same UID, which
already has access to the privileged kill-switch helper.
make test-dns-docker checks actual nft packets, authenticated helper/client queries, TCP fallback,
cancellation and permission removal from an existing socket under a dead TUN. It builds a separate
Python 3.14 image and uses disposable namespaces, no host network/state mounts, a read-only
repository and explicit capabilities (including NET_ADMIN/SYS_ADMIN and /dev/net/tun). The Python
workflow runs it separately; this is not a live host VPN test.
INCY configurations containing Shadowsocks temporarily run with TUN sniffing disabled, including mixed/balancer configurations. This avoids a reproduced stall in our external-TUN-FD path with bundled Ferrum 26.10.13. Domain rules that need sniffed names may not match; IP-based rules and the kill switch are unchanged. VLESS-only configurations keep sniffing. This is a compatibility workaround, not a confirmed application-wide Ferrum bug.
| Where | How |
|---|---|
| Panel | left click on the widget |
| App window | SUPER+Shift+V, a right click on the widget, or m in the panel |
| Connect / disconnect | click a server, or move with j/k and press Enter |
| Filter | / (Esc leaves it) |
| Ping | the Ping button, ⟳ on a group, a click on a server's ping, or p |
| Favourite | ☆ on a row, or s |
| Import a profile | + Import on a protocol in the window, or i |
| Autostart / delete | right click on a server in the window, or a / x |
| DNS leak test | the DNS badge (when it isn't green), or d |
The window's Settings button opens every option in a small terminal: Space changes one,
s saves, q quits. Re-running the installer asks the setup questions again.
The bar label can be changed with omarchy bar set omarchy-vpn labelFormat '{server} · {ping}'
(or f in the panel cycles presets). Useful placeholders: {label}, {server}, {provider},
{ping}, {exit_country}, {exit_flag}, {rate}, {state}.
omarchy bar set omarchy-vpn showLabel false shows the icon only.
When on, nothing leaves the computer except through the VPN — local network devices stay reachable. Pick a mode in Settings:
- off — only the window's Kill switch button turns it on;
- happ — on automatically while Happ is connected;
- all — on automatically for every connection.
Lockdown (on by default) keeps blocking even when no VPN is up, so a dropped tunnel never falls back to your real connection. If you're ever locked out:
sudo /usr/local/bin/happ-killswitch offThe rules don't survive a reboot.
Usually nothing to do: subscriptions are fetched the way the Happ app fetches them, as the same device, so no extra device slot is used.
If a provider still refuses (device limit, unsupported client), the server list shows
<provider> · ⚠ <its message> — free a device slot with your provider. If a provider needs
other request headers, put them in ~/.config/happ-capture/headers.json as one JSON object
({"User-Agent": "…", "X-Hwid": "…"}) and chmod 600 it; they replace the default ones.
Subscription URLs must use HTTPS. Redirects back to HTTP are rejected before device or custom headers can be resent. Existing safe subscription IDs keep their cache filenames; unsafe IDs are stored under deterministic hashed names so punctuation cannot create filename collisions.
Free tier: 10 GB/month with a confirmed email. Install windscribe-cli-v2-bin from the
AUR (the install wizard hints at it), then click Set up in the Locations list — a
terminal runs windscribe-cli login for you. Both CLI 2.21.x and the official 2.25.x
status formats are supported. Best Location asks Windscribe to choose the exit;
location rows retain Windscribe's Pro, Disabled and 10 Gbps flags. Disabled locations
are refused locally, while connecting a Pro-only location reports Windscribe's own
account refusal.
The default connection mode remains Automatic (default, then Stealth, then WStunnel after
confirmed teardown). An explicit one-attempt protocol can be stored in config.json as
"windscribe": {"protocol": "udp", "port": "443"}; valid protocols are wireguard,
udp, tcp, stealth and wstunnel, and an empty port uses the CLI default. The QML
controls for these preferences are not part of this core update.
The kill switch is hidden while a Windscribe tunnel is up (vendor daemon, like NetworkManager); Windscribe's own firewall setting is untouched — but if it is ON, switching away warns that it may keep blocking traffic (never blocks the switch itself).
Free, no account, unlimited. Install cloudflare-warp-bin from the AUR (the install wizard
hints at it). The rest has a setup row right in the Locations list — click Set up
and a terminal starts the daemon and runs warp-cli registration new for you (one sudo
password). After that the Cloudflare WARP row connects/disconnects like any other.
Consumer WARP has no server picker (Cloudflare picks the nearest exit) and its daemon owns the tunnel outside the plugin's kill switch — while WARP is up the kill switch badge is hidden, the same as with NetworkManager connections.
- Install INCY Desktop yourself: AUR
incy-bin, or the official Arch.pkg.tar.zstfrom INCY's releases. The plugin installer does not download or install INCY. The tested package is Desktop 3.9.0, bundled Ferrum 26.10.13 (0da8c683); other versions are not guaranteed compatible. - Open INCY and add your subscription URLs/QR codes there. The plugin reads its
~/.local/share/incy/incy.dband keeps separate subscription caches; it does not import subscriptions into the app or replace its database. - Disconnect any tunnel in the INCY app before connecting from the plugin. Enable INCY in the plugin's Settings if hidden, then select a server in Locations. Refresh All updates subscription caches; Ping measures through a separate short-lived core.
The default installation is /opt/incy. Both lib/app/resources/bin/libincycore.so and
its sibling libxray_ffi.so are required; a standalone xray binary is not used.
Discovery also checks incy in PATH and the user desktop entry. For a custom installation,
set OMARCHY_VPN_INCY_ROOT to the directory containing lib/ and bin/ in the environment
inherited by the shell/plugin, not just in an unrelated terminal.
One owner at a time. The app's tunnel is tun_incy; the plugin's is incy-xray.
The plugin refuses connect/disconnect actions while the app owns a tunnel: disconnect in
INCY first. Closing its window is not a substitute for disconnecting.
Privilege boundary. make install installs the fixed root-owned network helper and
its isolated Python package. The helper accepts only a mode and random session token;
it creates the fixed TUN/routes and binds outgoing sockets to the uplink. It never loads
INCY libraries, subscription configuration or user code. The library worker runs as the
user with no root UID or capabilities. Connect and Ping both use this separation.
The kill switch accepts broker mark 0x6b74 only together with generated proxy priority
6; subscription-direct traffic does not gain a blanket bypass.
Upgrading from the old incy-run implementation: disconnect the old connection,
update the plugin and run Update setup (or make install from the checkout). Updating
only the user backend is not enough: the root helpers/package must match too. The old
root execution command is removed; there is no fallback to running the core as root.
Your INCY database/subscriptions are kept. If startup fails, the plugin checks basic config
structure before launching the broker; full protocol/config validation happens in the
unprivileged worker, with its error returned to the caller.
See INCY Shadowsocks compatibility for the temporary TUN sniffing limitation, including its effect on domain-based routing.
The optional native suite verifies both library hashes against tracked
tests/incy-artifacts.sha256 before network setup or loading native code:
make test-docker-build
make test-incy-docker INCY_TEST_ROOT=/path/to/extracted/opt/incyAll network changes stay inside the disposable container. An absent or different library
fails the test; these hashes are not an install/runtime allowlist for users.
To test a new release, authenticate its official package and record its provenance, update
both library hashes and package/version comments in the manifest, then run the native
suite and regular make test-docker. Retain the update only with successful compatibility
results; changing a hash alone is not evidence of compatibility. The standalone
tests/incy_ferrum_check.py uses the same pin before its no-TUN control checks.
Besides your VPN servers and subscriptions, the plugin talks to: ipwho.is and ip-api.com
(your exit IP and its country), bash.ws (DNS leak test), www.gstatic.com (ping),
Cloudflare/OVH/Hetzner speed test servers (only when you run one). AbuseIPDB and IPQualityScore
only if you add an API key. These lookups send only the IP address being checked, and go
through the VPN while one is up.
-
Subscription responses are limited to 16 MiB. A malformed or oversized response is rejected; the last cached server list is kept. This is a download-size limit, not a server-count limit.
-
Log:
~/.local/state/vpn-manager/vpn-manager.log -
Status and server-list reads come from a per-user service (
omarchy-vpn-backend.service). If it's stopped or unreachable,--status/--serversfall back to a direct read automatically — nothing to configure. IPC responses over 256 KiB also use direct reads: large server lists stay complete, but do not benefit from the backend fast path. Inspect or restart it withsystemctl --user status omarchy-vpn-backend,journalctl --user -u omarchy-vpn-backend,systemctl --user restart omarchy-vpn-backend. -
Errors (a config the installed xray rejects, a tunnel that died) show as notifications with the reason.
-
Settings:
~/.config/vpn-manager/; caches:~/.cache/vpn-manager/(the Clear caches tool empties them).
~/.config/omarchy/plugins/omarchy-vpn/uninstall.sh
omarchy plugin remove omarchy-vpnRun uninstall.sh first: it turns the kill switch off and removes the helpers, the sudoers rule,
the app and the key binding. Removing the plugin alone would leave them behind. Your settings,
keys and favourites in ~/.config/vpn-manager are kept. From a checkout: make uninstall.
Static QML checks do not prove focus or keyboard-action safety. With an existing sealed
Omarchy test image and its vm-boot launcher (temporary COW overlay required), run:
bash tests/run_qml_vm.sh /path/to/vm-boot /path/to/sealed-image.qcow2Requires QEMU/KVM and about 3 GiB guest memory; the image must include Quickshell/Hyprland,
wtype, grim and Python. Nothing is installed on the host. The guest refuses to run
without the explicit disposable-VM boot marker. A fake vendor refuses/logs actions;
the gate checks real filter text and matching rows in both UI surfaces (also when both
are visible), empty hidden-list models and the runtime journal. Evidence goes to .cache/qml-vm-audit.*. Missing VM
prerequisites block this gate; ordinary pytest/source checks are not a replacement.
See CONTRIBUTING.md. Pull requests go to dev.
MIT — see LICENSE. src/dnsleak.py reimplements the protocol of
macvk/dnsleaktest (MIT).