Quick Start

Overview

This quick start guide will have you managing WireGuard VPN tunnels with WireGuird in just a few minutes. We’ll cover launching the application, adding a tunnel, and establishing your first connection.

Before starting, ensure you have installed WireGuird and have at least one WireGuard configuration file (.conf) ready.

Launch WireGuird

Start the Application

Launch WireGuird with root privileges (required for managing WireGuard tunnels):

sudo wireguird

Or use the application launcher with graphical authentication:

pkexec wireguird

WireGuird requires root access because it executes wg-quick commands that modify network interfaces (gui/tunnels.go:232, 286).

First Launch Appearance:

Main window with an empty tunnel list
System tray icon (black = disconnected)
Header showing “Not connected!”

Verify System Tray Icon

Look for the WireGuird icon in your system tray:

Black icon: No active tunnels
Red icon: One or more tunnels active

Right-click the icon for quick access:

Show: Display the main window
Quit: Exit the application

The system tray integration uses Ayatana AppIndicator (main.go:60) for broad compatibility across desktop environments.

Add Your First Tunnel

WireGuird manages tunnels stored in /etc/wireguard/. You can add tunnels in several ways:

Import Configuration File
Copy Configuration Manually
Create New Configuration

Import from File Browser

Click Add Tunnel Button

In the main window, click the “Add Tunnel” button (+ icon) in the toolbar.This opens a file chooser dialog (gui/tunnels.go:349).

Select Configuration File(s)

Navigate to your WireGuard configuration file(s):

Single file: Select one .conf file
Multiple files: Hold Ctrl and select multiple .conf files
ZIP archive: Select a .zip containing multiple .conf files

WireGuird supports importing multiple tunnel configurations at once. ZIP archives are automatically extracted, and all .conf files are imported (gui/tunnels.go:375-396).

Confirm Import

Click “OK” in the file dialog.The configuration files are copied to /etc/wireguard/ with proper permissions (gui/tunnels.go:388).Your tunnel(s) now appear in the tunnel list on the left side of the main window.

What Happens During Import:

File is read from your selected location
Content is validated as a proper WireGuard configuration
File is copied to /etc/wireguard/<filename>.conf
Permissions are set to 666 (readable/writable)
Tunnel list is refreshed automatically

Manual File Copy

If you prefer command-line management:

Copy Configuration to /etc/wireguard/

sudo cp ~/path/to/your/tunnel.conf /etc/wireguard/

Or create a new configuration file:

sudo nano /etc/wireguard/myvpn.conf

Set Proper Permissions

Ensure the configuration file has appropriate permissions:

sudo chmod 600 /etc/wireguard/myvpn.conf

Configuration files contain private keys. Always restrict permissions to prevent unauthorized access.

Refresh Tunnel List

In WireGuird, press F5 to refresh the tunnel list (gui/tunnels.go:88-93).Or restart the application to detect new configurations.

Create Configuration with WireGuird Editor

Create Empty Configuration

First, create an empty configuration file:

sudo touch /etc/wireguard/newtunnel.conf
sudo chmod 600 /etc/wireguard/newtunnel.conf

Open in WireGuird

Press F5 in WireGuird to refresh the tunnel list
Select “newtunnel” from the list
Click the “Edit” button (pencil icon)

Enter Configuration

The editor window opens with syntax highlighting (gui/tunnels.go:615-659).Enter your WireGuard configuration:

[Interface]
PrivateKey = <your-private-key>
Address = 10.0.0.2/24
DNS = 1.1.1.1

[Peer]
PublicKey = <peer-public-key>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

The editor provides syntax highlighting for WireGuard properties and sections, making it easier to spot errors.

Save Configuration

Review your configuration
Click “Save” button
The tunnel is now ready to activate

If you want to rename the tunnel, edit the name field at the top of the editor before saving (gui/tunnels.go:729-749).

Connect to a Tunnel

Select a Tunnel

In the main window, click on a tunnel name in the left sidebar.The right panel displays tunnel details:Interface Information:

Status: Inactive
Addresses: IP addresses from config
DNS Servers: DNS configuration

Peer Information:

Public Key: Remote peer’s public key
Endpoint: Server address and port
Allowed IPs: Routed IP ranges

Activate the Tunnel

Click the “Activate” button in the interface section.What Happens:

WireGuird executes sudo wg-quick up <tunnel-name> (gui/tunnels.go:286)
WireGuard creates a network interface
Routes are configured based on AllowedIPs
DNS settings are applied (if configured)

If “Multiple Tunnels” is disabled in Settings, activating a tunnel automatically disconnects any currently active tunnels (gui/tunnels.go:249-268).

Success Indicators:

Button label changes to “Deactivate”
Status changes to “Active”
System tray icon turns red
Green indicator appears next to tunnel name
Header shows “Connected to [tunnel-name]”

Monitor Connection

Once connected, real-time statistics update every second:Interface Stats:

Public Key: Your interface’s public key
Listen Port: UDP port for incoming connections

Peer Stats:

Latest Handshake: Time since last handshake (e.g., “2 minutes ago”)
Transfer: Received and sent bytes in human-readable format

Statistics only update when the WireGuird window has focus to conserve resources (gui/tunnels.go:837).

Test Your Connection

Verify your VPN connection is working:

# Check tunnel interface exists
ip addr show <tunnel-name>

# View WireGuard status
sudo wg show

# Test connectivity
ping 10.0.0.1  # Replace with your VPN gateway IP

# Check public IP (if tunneling all traffic)
curl ifconfig.me

Disconnect from a Tunnel

Select Active Tunnel

Click on the active tunnel in the left sidebar (marked with a green indicator).

Click Deactivate

Click the “Deactivate” button.What Happens:

WireGuird executes sudo wg-quick down <tunnel-name> (gui/tunnels.go:232)
Network interface is removed
Routes are cleaned up
DNS settings are restored

Success Indicators:

Button label changes back to “Activate”
Status changes to “Inactive”
System tray icon turns black
Gray indicator appears next to tunnel name
Header shows “Not connected!”

Essential Features

Keyboard Shortcuts

Shortcut	Action
F5	Refresh tunnel list (gui/tunnels.go:88)

Add Tunnel

Import .conf files or .zip archives containing tunnel configurations.

Edit Tunnel

Open the built-in editor to modify the selected tunnel’s configuration with syntax highlighting.

Delete Tunnel

Remove the selected tunnel configuration from /etc/wireguard/ (prompts for confirmation).

Export Tunnels

Export all tunnel configurations to a dated ZIP archive for backup (gui/tunnels.go:462-537).

Click the menu button (hamburger icon) in the header to access:

Settings: Configure application behavior
VERSION: v1.1.0: View version and open GitHub repository (gui/tunnels.go:125)

Configuration Settings

Access Settings from the application menu to customize WireGuird:

Multiple Active Tunnels

Disabled (Default)
Enabled

Single Tunnel ModeWhen disabled, activating a new tunnel automatically disconnects any active tunnels.Best for:

Users who only need one VPN connection at a time
Preventing routing conflicts
Simpler connection management

Start on Tray

When enabled, WireGuird launches minimized to the system tray instead of showing the main window (main.go:147). Useful for:

Automatic startup at login
Keeping the application running in background
Quick access from system tray

Check for Updates

When enabled, WireGuird automatically checks for new releases:

First check: 60 seconds after launch
Subsequent checks: Every 24 hours
Notification dialog when updates are available

Settings are saved to ./wireguird.settings in JSON format (settings/settings.go:12, 44-56).

Common Tasks

Import tunnels from another computer

Export on source computer

Click the Export button (zip icon) in WireGuird toolbar.Save the ZIP file (e.g., wg_tunnels_5_Mar_2026.zip).

Transfer to destination computer

Copy the ZIP file to your other computer via USB, network, or cloud storage.

Import on destination computer

In WireGuird, click Add Tunnel and select the ZIP file.All tunnel configurations are automatically extracted and imported.

Rename a tunnel

Open editor

Select the tunnel and click the Edit button.

Change name

Edit the name field at the top of the editor window (gui/tunnels.go:729).

Save

Click Save. The configuration file is renamed automatically (gui/tunnels.go:741-749).

Tunnel names must be 15 characters or less due to Linux interface naming limitations (gui/tunnels.go:217).

View connection logs

WireGuird displays connection logs at the bottom of the main window:

Timestamp: When the event occurred
Level: INFO or ERROR (errors in red)
Message: Description of the event

Log Events:

Tunnel activation/deactivation
Connection errors
wg-quick command output

Logs are stored in memory and cleared when the application restarts (gui/tunnels.go:1140-1165).

Check tunnel configuration is valid

Before activating, verify your configuration:

sudo wg-quick up <tunnel-name> --dry-run

Or use the WireGuard config validator:

sudo wg show <tunnel-name>

Common configuration issues:

Missing or invalid PrivateKey
Malformed Endpoint (must be host:port)
Invalid IP addresses in Address or AllowedIPs
Missing [Interface] or [Peer] sections

Troubleshooting

Can't activate tunnel - Permission denied

Cause: WireGuird wasn’t launched with root privileges.Solution:

sudo wireguird
# or
pkexec wireguird

WireGuard requires root to create network interfaces.

Tunnel activates but no internet connection

Cause: DNS or routing configuration issue.Check DNS:

cat /etc/resolv.conf

Check routes:

ip route show

Solution: Ensure your tunnel configuration includes DNS servers:

[Interface]
DNS = 1.1.1.1, 8.8.8.8

Tunnel name too long error

Cause: Tunnel filename exceeds 15 characters (gui/tunnels.go:217).Solution: Rename the configuration file:

sudo mv /etc/wireguard/very-long-tunnel-name.conf /etc/wireguard/shortvpn.conf

Press F5 in WireGuird to refresh.

System tray icon not visible

Cause: Desktop environment doesn’t support system tray.GNOME Solution:

sudo apt install gnome-shell-extension-appindicator
gnome-extensions enable [email protected]

KDE/XFCE: System tray support is built-in. Check panel settings.

wg-quick command output errors

WireGuird displays wg-quick errors in the logs panel (gui/tunnels.go:234-240, 288-294).Common errors:

“Name or service not known”: DNS can’t resolve Endpoint
- Check internet connection
- Verify Endpoint address
“Operation not permitted”: Permission issue
- Ensure running with sudo
“Cannot allocate memory”: System resource limit
- Check available memory: free -h
“File exists”: Interface already exists
- Disconnect first: sudo wg-quick down <name>

Next Steps

Now that you’re familiar with the basics, explore more advanced features:

Tunnel Editor

Learn about the built-in configuration editor with syntax highlighting and real-time validation.

Multiple Tunnels

Configure and manage multiple simultaneous VPN connections for advanced routing.

Backup & Restore

Export tunnel configurations for backup or migration to another system.

Keyboard Shortcuts

Master keyboard shortcuts for faster tunnel management.

Getting Help

If you encounter issues:

GitHub Issues: Report bugs or request features
WireGuard Docs: Official WireGuard documentation
System Logs: Check journalctl -xe for system-level WireGuard errors

WireGuird is open source! View the source code, contribute, or fork the project on GitHub.

Get Started

User Guide

Advanced

Development

Overview

Launch WireGuird

Add Your First Tunnel

Import from File Browser

Manual File Copy

Create Configuration with WireGuird Editor

Connect to a Tunnel

Disconnect from a Tunnel

Essential Features

Keyboard Shortcuts

Add Tunnel

Edit Tunnel

Delete Tunnel

Export Tunnels

Application Menu

Configuration Settings

Multiple Active Tunnels

Start on Tray

Check for Updates

Common Tasks

Troubleshooting

Next Steps

Tunnel Editor

Multiple Tunnels

Backup & Restore

Keyboard Shortcuts

Getting Help

Build docs developers (and LLMs) love

Get Started

User Guide

Advanced

Development

​Overview

​Launch WireGuird

​Add Your First Tunnel

​Import from File Browser

​Manual File Copy

​Create Configuration with WireGuird Editor

​Connect to a Tunnel

​Disconnect from a Tunnel

​Essential Features

​Keyboard Shortcuts

​Toolbar Buttons

Add Tunnel

Edit Tunnel

Delete Tunnel

Export Tunnels

​Application Menu

​Configuration Settings

​Multiple Active Tunnels

​Start on Tray

​Check for Updates

​Common Tasks

​Troubleshooting

​Next Steps

Tunnel Editor

Multiple Tunnels

Backup & Restore

Keyboard Shortcuts

​Getting Help

Build docs developers (and LLMs) love

Overview

Launch WireGuird

Add Your First Tunnel

Import from File Browser

Manual File Copy

Create Configuration with WireGuird Editor

Connect to a Tunnel

Disconnect from a Tunnel

Essential Features

Keyboard Shortcuts

Toolbar Buttons

Application Menu

Configuration Settings

Multiple Active Tunnels

Start on Tray

Check for Updates

Common Tasks

Troubleshooting

Next Steps

Getting Help