Skip to content
k-kostinPublic

About

VPN app for Omarchy: profiles, subscriptions and everyday connection controls in the bar.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

OmaVLESS

OmaVLESS is a VPN app for Omarchy that puts everyday connection controls directly in the bar.

Import your own compatible VLESS profile or HTTPS subscription, choose a mode, and connect from one compact, terminal-style panel. Open the terminal application when you want more room.

Free and open source. OmaVLESS is not a VPN provider: VPN servers and service subscriptions are not included.

OmaVLESS panel with country-and-city profile names, connection controls and Open app

Screenshots use example profiles and setup states to protect private data. No live VPN connection is shown.

Get started

OmaVLESS 0.9.8 is available for Omarchy on x86-64 and ARM64. Start from the plugin — no Rust build or manual package selection is needed.

omarchy plugin add https://github.com/k-kostin/omavless.git --enable

Turn off other VPN connections, open OmaVLESS from the bar and choose Install required components. The terminal installs the matching application, bundled Mihomo core and DNS helper for website-address lookup. Enter INSTALL, then DNS when asked; passwords go only into the system's password prompt. Setup does not connect a VPN. Follow onboarding to add your own profile or subscription, then press Connect beside the server you want.

Required components showing the missing application and VPN core with a guided install button

The user guide covers installation, partial setup, everyday use and optional tools. You do not need to install Mihomo separately. A guide for your assistant explains the same supported actions and privacy boundaries.

The command above follows upstream main. Marketplace verification covers a separate exact snapshot and may lag behind the GitHub release.

Update or reinstall

Update the plugin first:

omarchy plugin update kdk.omavless

Open OmaVLESS and follow the next step offered in the panel. Application and DNS-helper packages update separately from the plugin. Normal updates preserve profiles and settings; see the update instructions.

To start fresh, use Remove or the short terminal removal guide. Full removal deletes saved profiles/settings without a backup. Other VPN clients and a separately installed Mihomo stay. The helper normally needs one restart; the same command resumes removal afterward, even without the widget. Ordinary omarchy plugin remove removes only the widget, not the app or data.

For unfinished setup or old controls after an update, follow the user guide instead of reinstalling blindly.

Which mode should I choose?

Mode What it does
Full VPN Sends traffic through your connected VPN profile. Start here if you want a straightforward VPN connection.
Routing Uses a country policy and your domain/IP rules to decide which traffic goes directly and which uses the VPN.
Direct Bypasses the proxy while keeping the TUN interface running. This is not Disconnect.

Everyday controls

Expand a subscription to browse its profiles. Press ↻ beside its server count to download an updated server list — no need to re-import the URL.

The management bar below the list offers favorite, rename, edit, QR, export, details and delete for the selected profile. Subscription profiles keep their editing restrictions; search does not change the connection.

Settings contains language, subscriptions, routing, diagnostics and shutdown. English/Russian switching does not restart your VPN. Login autoconnect is Off by default.

View an expanded subscription · Connect and disconnect

Open the app for more room

Press Open app below the Profile actions bar to open OmaVLESS in a terminal. If it is already open, the button brings you back to that same window.

OmaVLESS terminal application showing example profiles and keyboard controls while disconnected

Use the wider workspace for traffic, active connections, routing, checks and diagnostics. It shares the same VPN connection with the plugin, not a second tunnel; both interfaces stay in sync.

Tab / Shift+Tab switch pages; ? shows help. Press q or close the terminal when done — closing the window does not stop your VPN. Disconnect stops the connection; Shut down OmaVLESS in the plugin's Settings stops the application and disables the plugin after confirmation.

0.9.8 includes encrypted Backup for profiles, subscriptions and supported bundled routing templates. It is not a whole-system backup; Restore is not included yet. See Backup usage and limits.

Supported inputs

Family Status
VLESS Primary supported family, including compatible TCP, WebSocket, HTTP, H2, gRPC and XHTTP configurations with TLS/REALITY
Trojan, Hysteria2, TUIC v5 Experimental; real-server coverage is incomplete
Subscriptions HTTPS raw/base64 lists of supported profile links

Advanced VLESS Encryption/REALITY PQ and XHTTP combinations retain their experimental limitations. WireGuard, AmneziaWG, vpn:// keys and arbitrary remote Clash/Mihomo YAML are not supported inputs.

See protocol support and limitations.

Privacy and help

Open Settings → Help, or Setup help during installation. Copy the ready request into Codex, Claude or another assistant on this computer and describe your problem at the end. The request points to the instructions installed with your plugin. You can also read the guide or report a problem directly; using an assistant is optional.

Profiles and subscription URLs stay in a private local store. For support, use Copy report or Save file in Settings → Support report. Do not post profile files, subscription URLs, private configuration, backup archives or unredacted screenshots.

Credits and license

Maintained by kdk. Community project; not affiliated with Omarchy, MetaCubeX or a VPN provider.

The interface builds on Omarchy VPN by Justin Köstinger. Routing data comes from RoscomVPN, MetaCubeX and Chocolate4U. See third-party notices.

MIT License · Contributing

About

VPN app for Omarchy: profiles, subscriptions and everyday connection controls in the bar.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages