Skip to content

Latest commit

 

History

30 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

omarchy-vpn

Tests xray compatibility Quality Gate Release License: MIT

Omarchy 4 Arch Linux Hyprland Python 3.14 QML / Quickshell Bash nftables

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).

Features

  • 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.

Install

omarchy plugin add https://github.com/moonmouse11/omarchy-vpn --enable

omarchy 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.

What setup changes

  • Installs only the packages your picks need (wireguard-tools, openvpn, a resolvconf).
  • 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 to omarchy-vpn-helper, happ-killswitch and the IPv6 guard's fixed sysctl calls. 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-vpn and 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.conf is left alone, unless you agree to switch it back to systemd-resolved when the installer asks.

Endpoint bootstrap compatibility

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 Shadowsocks compatibility

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.

Usage

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

Settings

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.

Kill switch

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 off

The rules don't survive a reboot.

Happ setup

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.

Windscribe setup

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).

Cloudflare WARP setup

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.

INCY setup

  1. Install INCY Desktop yourself: AUR incy-bin, or the official Arch .pkg.tar.zst from 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.
  2. Open INCY and add your subscription URLs/QR codes there. The plugin reads its ~/.local/share/incy/incy.db and keeps separate subscription caches; it does not import subscriptions into the app or replace its database.
  3. 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.

Native test pinning

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/incy

All 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.

Privacy

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.

Troubleshooting

  • 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/--servers fall 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 with systemctl --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).

Uninstall

~/.config/omarchy/plugins/omarchy-vpn/uninstall.sh
omarchy plugin remove omarchy-vpn

Run 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.

Graphical regression gate

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.qcow2

Requires 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.

Contributing

See CONTRIBUTING.md. Pull requests go to dev.

License

MIT — see LICENSE. src/dnsleak.py reimplements the protocol of macvk/dnsleaktest (MIT).

Releases

Packages

Contributors

Languages