Skip to main content

​
Overview

WireGuird provides configurable settings to customize application behavior. Settings are stored in a JSON file (wireguird.settings) and persist across application restarts.

​
Accessing Settings

1

Open the menu

Click the Menu button (three-line hamburger icon) in the main window header.
2

Select Settings

Click Settings from the dropdown menu.
3

Settings window appears

The settings window displays with checkboxes for each configurable option.

​
Available Settings

WireGuird offers three main configuration options:

​
Multiple Active Tunnels

Setting ID: settings_multiple_active_tunnels Type: Checkbox Default: Disabled (off) Controls whether multiple WireGuard tunnels can be active simultaneously.
When Multiple Tunnels is disabled:
  • Only one tunnel can be active at a time
  • Activating a new tunnel automatically deactivates all other active tunnels
  • Simpler routing configuration
  • Recommended for most users
Example behavior:
1. Connect to "office-vpn" → Connected
2. Connect to "home-vpn" → office-vpn disconnects, home-vpn connects
3. Only home-vpn is now active
Technical Details: 
// Source: gui/tunnels.go:249-268
if Settings.MultipleTunnels {
    // Only disconnect the specific tunnel being toggled
    d, err := wgc.Device(name)
    if err != nil && !errors.Is(err, os.ErrNotExist) {
        return err
    }
    
    if !errors.Is(err, os.ErrNotExist) {
        if err := dc(d); err != nil {
            return err
        }
    }
} else {
    // Disconnect ALL tunnels before connecting to a new one
    for _, d := range list {
        if err := dc(d); err != nil {
            return err
        }
    }
}
Enabling multiple tunnels can create complex routing scenarios. Ensure your AllowedIPs configurations don’t overlap, or you may experience unexpected routing behavior and connection issues.

​
Start on Tray

Setting ID: settings_start_tray Type: Checkbox Default: Disabled (off) Controls whether WireGuird starts minimized to the system tray or shows the main window on launch.
When Start on Tray is disabled:
  • The main WireGuird window appears when you launch the application
  • Normal desktop application behavior
  • Easier to discover and interact with on startup
  • Recommended for manual VPN management
Technical Details: 
// Source: main.go:147-149
if !gui.Settings.StartOnTray {
    win.ShowAll()
}
The application always creates the system tray icon. This setting only controls whether the main window is initially visible. System Tray Icon:
  • Icon: wireguard_off when no tunnels are active
  • Icon: wg_connected when at least one tunnel is active
  • Right-click menu:
    • Show: Display the main WireGuird window
    • Quit: Exit the application and disconnect all tunnels
You can close the main window at any time (without quitting), and WireGuird continues running in the system tray. Active VPN connections remain connected.

​
Check for Updates

Setting ID: settings_check_updates Type: Checkbox Default: Enabled (on) Controls whether WireGuird automatically checks for new versions on GitHub.
When Check Updates is enabled:
  • First check occurs 60 seconds after application startup
  • Subsequent checks occur every 24 hours
  • If a new version is available, a dialog appears: “Wireguird: update available => [version-tag]”
  • Checks are performed in the background without disrupting usage
  • No automatic downloads or installations
Technical Details: 
// Source: gui/gui.go:81-100
if Settings.CheckUpdates {
    go func() {
        time.Sleep(60 * time.Second)
        if err := updateCheck(); err != nil {
            log.Error().Err(err).Msg("error on update check")
        }
        
        updateTicker = time.NewTicker(24 * time.Hour)
        defer updateTicker.Stop()
        
        for {
            select {
            case <-updateTicker.C:
                if err := updateCheck(); err != nil {
                    log.Error().Err(err).Msg("error on update check")
                }
            }
        }
    }()
}
Update Check Process:
  1. Queries GitHub API: https://api.github.com/repos/UnnoTed/wireguird/releases
  2. Compares latest release tag with current version (1.1.0)
  3. If different, shows notification dialog
  4. User must manually visit GitHub to download updates
WireGuird does not automatically download or install updates. The update check only notifies you that a new version is available. You must manually download and install updates from the GitHub releases page.

​
Saving Settings

After modifying any settings:
1

Click Save

Click the Save button (button_settings_save) in the settings window.
2

Settings are persisted

Your changes are written to wireguird.settings and take effect immediately.The settings window closes automatically.
Settings File: 
{
  "MultipleTunnels": false,
  "StartOnTray": false,
  "CheckUpdates": true,
  "Debug": false
}
File Location: ./wireguird.settings (in the current working directory when WireGuird is launched)

​
Canceling Changes

If you want to discard your modifications:
1

Click Cancel

Click the Cancel button (button_settings_cancel) in the settings window.
2

Settings are reverted

All checkbox states are reset to their saved values (before you opened the settings window).The settings window closes without saving changes.
// Source: gui/tunnels.go:816-827
btnSettingsCancel.Connect("clicked", func() {
    err := func() error {
        Settings.Init()  // Reload settings from file
        settingsWindow.Close()
        return nil
    }()
    
    if err != nil {
        ShowError(window, err, "settings cancel error")
    }
})

​
Settings Implementation

WireGuird uses a simple settings system:

​
Settings Structure

// Source: settings/settings.go:14-19
type Settings struct {
    MultipleTunnels bool
    StartOnTray     bool
    CheckUpdates    bool
    Debug           bool
}

​
Loading Settings

Settings are loaded automatically when WireGuird starts: 
// Source: settings/settings.go:59-80
func (s *Settings) Load() error {
    if !dry.FileExists(FilePath) {
        return nil  // Use defaults if file doesn't exist
    }
    
    data, err := ioutil.ReadFile(FilePath)
    if err != nil {
        return err
    }
    
    settings := &Settings{}
    if err := json.Unmarshal(data, &settings); err != nil {
        return err
    }
    
    *s = *settings
    return nil
}
If wireguird.settings doesn’t exist, WireGuird uses default values (MultipleTunnels: false, StartOnTray: false, CheckUpdates: true).

​
Saving Settings

// Source: settings/settings.go:44-57
func (s *Settings) Save() error {
    data, err := json.Marshal(s)
    if err != nil {
        return err
    }
    
    if err := ioutil.WriteFile(FilePath, data, 0660); err != nil {
        return err
    }
    
    return nil
}
Settings are saved with file permissions 0660 (read/write for owner and group, no access for others).

​
Debug Mode

There’s an additional hidden setting in the settings structure: Debug: Enables debug-level logging This setting is not exposed in the GUI but can be manually added to wireguird.settings: 
{
  "MultipleTunnels": false,
  "StartOnTray": false,
  "CheckUpdates": true,
  "Debug": true
}
When enabled, WireGuird logs detailed debug information to the console, including:
  • Settings initialization
  • Device list queries
  • UI event handling
  • Configuration file parsing
Debug mode affects console output only. The WireGuard logs panel in the GUI shows INFO and ERROR messages regardless of the debug setting.

​
Checking Current Version

To see which version of WireGuird you’re running:
  1. Click the Menu button in the main window
  2. The menu shows: “VERSION: v[version]” (e.g., “VERSION: v1.1.0”)
  3. Clicking this menu item opens the GitHub repository in your browser
// Source: gui/gui.go:17-19
const (
    Version     = "1.1.0"
    Repo        = "https://github.com/UnnoTed/wireguird"
)

​
Advanced Configuration

Advanced users can manually edit wireguird.settings while the application is closed: 
# View current settings
cat wireguird.settings

# Edit with your preferred editor
nano wireguird.settings

# Example content:
{
  "MultipleTunnels": true,
  "StartOnTray": true,
  "CheckUpdates": false,
  "Debug": true
}
Settings take effect the next time you launch WireGuird.
Manually editing the settings file can cause WireGuird to fail to start if the JSON is malformed. Always validate JSON syntax before saving.

​
Troubleshooting Settings

​
Settings Don’t Persist

If your settings reset after closing WireGuird:
  • Check that wireguird.settings exists in the working directory
  • Verify file permissions: ls -l wireguird.settings
  • Ensure you clicked Save, not Cancel
  • Check the console for error messages about file writing

​
Settings File Location

The settings file is created in the current working directory where WireGuird was launched: 
# Check where WireGuird is running from
pwd

# Look for the settings file
ls -la wireguird.settings
If you launch WireGuird from different directories, it may create separate settings files.

​
Reset to Defaults

To reset all settings to defaults: 
# Delete the settings file
rm wireguird.settings

# Restart WireGuird - it will use default settings
Alternatively, manually edit the file with default values: 
{
  "MultipleTunnels": false,
  "StartOnTray": false,
  "CheckUpdates": true,
  "Debug": false
}

Build docs developers (and LLMs) love

Get started for freeTalk to us