WireGuard VPN Toggle for Omarchy's Waybar

October 31, 2025 ยท View on GitHub

A clean, automated installer for adding a WireGuard VPN toggle to Omarchy's Waybar status bar. Provides a convenient visual indicator and quick toggle for your WireGuard VPN connections.

Based on the guide from Omarchy Discussion #1366.

Features

  • ๐Ÿ”’ One-click VPN toggle - Left-click to connect/disconnect
  • ๐ŸŽจ Visual status indicator - Integrates with Omarchy's icon theming
  • ๐Ÿ”„ Profile switching - Right-click menu to switch between VPN configs
  • โšก Passwordless operation - Optional sudoers configuration
  • ๐Ÿ›ก๏ธ The Omarchy way - All scripts follow Omarchy bash practices with proper error handling
  • ๐Ÿ“ฆ Automated installation - Simple installer handles everything for Omarchy setups

Prerequisites

โš ๏ธ This tool is designed specifically for Omarchy setups only.

  • Omarchy - This VPN toggle is designed to integrate with Omarchy's Waybar configuration
  • Bash 4.0+
  • WireGuard (wireguard-tools)
  • jq (JSON processor for safe config manipulation)
  • WireGuard configuration files in /etc/wireguard/

Install Dependencies

Since Omarchy is designed for Arch Linux:

sudo pacman -S wireguard-tools waybar jq

Installation

Quick Install (One-Liner)

Install directly from GitHub with a single command:

Using curl:

curl -fsSL https://raw.githubusercontent.com/JacobusXIII/omarchy-wireguard-vpn-toggle/main/install.sh | bash

Using wget:

wget -qO- https://raw.githubusercontent.com/JacobusXIII/omarchy-wireguard-vpn-toggle/main/install.sh | bash

This will:

  • Automatically detect one-liner mode
  • Download the repository to /tmp
  • Run the full installation with interactive prompts
  • Clean up temporary files when done
  • Ask for sudoers configuration (optional passwordless toggling)

Note: You'll need WireGuard configuration files before the VPN toggle will work (see step 2 below).

Manual Installation

1. Clone the Repository

git clone https://github.com/JacobusXIII/omarchy-wireguard-vpn-toggle.git
cd omarchy-wireguard-vpn-toggle

2. Set Up WireGuard Configuration

If you haven't already, you need WireGuard configuration files in /etc/wireguard/.

For ProtonVPN users:

  1. Visit the ProtonVPN downloads page
  2. Download WireGuard configuration files
  3. Copy them to /etc/wireguard/: 
    sudo cp your-config.conf /etc/wireguard/
  4. Set proper permissions (600 or stricter): 
    sudo chmod 600 /etc/wireguard/*.conf

See the ProtonVPN WireGuard guide for detailed instructions.

For other VPN providers:

Most VPN providers offer WireGuard configuration files. Download them and place in /etc/wireguard/, then ensure they have proper permissions (600 or stricter) with sudo chmod 600 /etc/wireguard/*.conf.

3. Run the Installer

./install.sh

The installer will:

  • โœ… Check for required dependencies
  • โœ… Verify WireGuard configurations exist
  • โœ… Install scripts to ~/.config/waybar/scripts/
  • โœ… Add custom/vpn module to Omarchy's Waybar config (after network module)
  • โœ… Add #custom-vpn to style.css alongside #custom-omarchy
  • โœ… Optionally configure sudoers for passwordless operation

4. Restart Waybar

killall waybar && waybar &

Or restart your compositor.

Usage

Toggle VPN Connection

Left-click on the VPN icon in Omarchy's Waybar to connect or disconnect.

Switch VPN Profile

Right-click on the VPN icon to open an interactive menu where you can select a different WireGuard configuration.

Manual Control

You can also use the scripts directly from the command line:

# Toggle VPN on/off
~/.config/waybar/scripts/vpn-toggle.sh

# Check current status
~/.config/waybar/scripts/vpn-status.sh

# Select VPN profile
~/.config/waybar/scripts/vpn-select.sh

Customization

Styling

The installer automatically adds #custom-vpn to your style.css alongside other icons:

#custom-omarchy,
#custom-vpn {
  /* Your existing Omarchy icon styles */
}

By default, the VPN icon inherits the same styling as your other custom modules (colors, spacing, etc.). You can customize this by:

  • Keeping it grouped with other icons to inherit their styles
  • Separating it to apply custom styles only to the VPN icon: 
    #custom-vpn {
  color: #your-color;
  /* Your custom styles */
}

Change Icons

The VPN icons can be changed by editing your Omarchy Waybar config's format-icons:

"format-icons": {
  "default": "",    // Default/fallback icon (blank)
  "none": "๓ฐปŒ",       // No config
  "connected": "๓ฐฆ",   // VPN connected
  "disconnected": "๓ฐฆž" // VPN disconnected
}

Replace the Nerd Font icons with your preferred icons or emoji.

Project Structure

omarchy-wireguard-vpn-toggle/
โ”œโ”€โ”€ scripts/              # VPN toggle scripts
โ”‚   โ”œโ”€โ”€ vpn-status.sh    # Checks VPN connection status
โ”‚   โ”œโ”€โ”€ vpn-toggle.sh    # Toggles VPN on/off
โ”‚   โ””โ”€โ”€ vpn-select.sh    # Interactive VPN profile selector
โ”œโ”€โ”€ install.sh           # Main installer script
โ”œโ”€โ”€ LICENSE              # MIT License
โ”œโ”€โ”€ README.md            # This file
โ””โ”€โ”€ .gitignore

Installed Files

The installer creates/modifies these files:

In ~/.config/waybar/scripts/:

  • vpn-status.sh - Checks VPN connection status (returns JSON with icon state)
  • vpn-toggle.sh - Toggles VPN on/off
  • vpn-select.sh - Interactive VPN profile selector
  • vpn.conf - Stores currently selected VPN configuration

In ~/.config/waybar/:

  • config.jsonc or config - Waybar config (adds custom/vpn module with format-icons)
  • style.css - Waybar styles (adds #custom-vpn alongside #custom-omarchy)
  • *.backup.YYYYMMDD-HHMMSS - Timestamped backups of modified files

Troubleshooting

Password Prompt When Toggling

If you're prompted for a password when toggling VPN:

  1. Run the installer again and choose to configure sudoers
  2. Or manually add this line using sudo visudo: 
    %wheel ALL=(ALL) NOPASSWD: /usr/bin/wg-quick

VPN Icon Not Appearing

  1. Check Waybar config is valid JSON:

    cat ~/.config/waybar/config.jsonc | jq

  2. Ensure scripts are executable:

    chmod +x ~/.config/waybar/scripts/vpn-*.sh

  3. Check Waybar logs:

    journalctl --user -u waybar -f

  4. Verify scripts exist:

    ls -lh ~/.config/waybar/scripts/vpn-*.sh

"No WireGuard configurations found"

Ensure you have .conf files in /etc/wireguard/:

ls -lh /etc/wireguard/

If empty, download configuration files from your VPN provider.

Connection Fails

Test manually to identify the issue:

# Try connecting manually
sudo wg-quick up your-config-name

# Check status
sudo wg show

# Try disconnecting
sudo wg-quick down your-config-name

Check for errors in the output.

Script Syntax Errors

All scripts follow strict bash practices. If you modify them, validate syntax:

bash -n ~/.config/waybar/scripts/vpn-status.sh
bash -n ~/.config/waybar/scripts/vpn-toggle.sh
bash -n ~/.config/waybar/scripts/vpn-select.sh

Security Considerations

Sudoers Configuration

The sudoers configuration allows running wg-quick without a password. This is limited to:

  • Only the /usr/bin/wg-quick binary
  • Only for users in the wheel/sudo group

This is generally safe, but be aware that anyone with access to your user account can control VPN connections without additional authentication.

If this is a concern in your environment, you can skip the sudoers setup and enter your password each time you toggle the VPN.

Configuration File Permissions

WireGuard configuration files in /etc/wireguard/ typically contain private keys. Ensure they have proper permissions:

sudo chmod 600 /etc/wireguard/*.conf
sudo chown root:root /etc/wireguard/*.conf

Uninstallation

To remove the VPN toggle:

  1. Remove the scripts:

    rm -rf ~/.config/waybar/scripts

  2. Remove from Waybar config:

    • Delete "custom/vpn" from modules-right array
    • Delete the "custom/vpn" configuration block
    • (Or restore from timestamped backup: ~/.config/waybar/config.jsonc.backup.YYYYMMDD-HHMMSS)

  3. Remove from ~/.config/waybar/style.css:

    • Remove #custom-vpn, from the line with #custom-omarchy
    • (Or restore from timestamped backup: ~/.config/waybar/style.css.backup.YYYYMMDD-HHMMSS)

  4. Remove sudoers rule:

    sudo rm /etc/sudoers.d/wireguard-vpn-toggle

  5. Restart Waybar:

    killall waybar && waybar &

Development

Code Style

All bash scripts follow the Omarchy way - bash practices observed in the Omarchy repository:

  • Shebang and strict mode: #!/bin/bash with set -eEo pipefail
  • Error handling: trap catch_errors ERR INT TERM; trap exit_handler EXIT
  • Function definitions: name() { ... } (no function keyword)
  • Use local for function-scoped variables
  • [[ ... ]] for conditions
  • Quoted variable expansions: "${VAR}"
  • Command availability: command -v tool &>/dev/null
  • 2-space indentation
  • UPPER_SNAKE_CASE for globals, lower_snake_case for locals

Testing

Validate syntax of all scripts:

bash -n install.sh
for script in scripts/*.sh; do bash -n "$script"; done

Credits

Based on the manual setup guide by @rulonder in Omarchy Discussion #1366.

This project was built with a little help from Cursor AI - a great way to enforce Omarchy bash practices, maintain code consistency, and write comprehensive documentation. ๐Ÿค–

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to:

  • Report bugs by opening an issue
  • Suggest features or improvements
  • Submit pull requests

When contributing code, please follow the existing bash style guide.

  • Omarchy - Configuration framework this is designed for
  • Waybar - Highly customizable Wayland bar
  • WireGuard - Fast, modern VPN protocol
  • ProtonVPN - Privacy-focused VPN service

Enjoy your new VPN toggle! ๐Ÿ”’โœจ