Skip to content

VPN Quick Start

This guide walks you through setting up and connecting to the bnerd VPN using WireGuard.

Prerequisites

  • bnerd CLI installed (see Installation)
  • WireGuard tools installed on your system
  • Access to the bnerd CloudAPI (token and org-id configured)

Install WireGuard

The client supports both kernel and userspace WireGuard and will automatically detect which is available.

Kernel-based (recommended): 

sudo apt update
sudo apt install wireguard

Userspace fallback: 

sudo apt update
sudo apt install wireguard-go wireguard-tools


brew install wireguard-tools

For userspace mode: 

brew install wireguard-go wireguard-tools


sudo pacman -S wireguard-tools

Client Setup

Step 1: Configure VPN Settings

Add the VPN server information to your ~/.bnerd.yaml:

api-url: https://api.bnerd.net
token: your-api-token
org-id: your-org-id

vpn:
  server-endpoint: vpn.bnerd.net:51820
  server-public-key: SERVER_PUBLIC_KEY

Tip

Get the server endpoint and public key from your bnerd administrator.

Step 2: First Connection

On first run, bnerd up automatically generates WireGuard keys for you:

sudo bnerd up

You'll see output like:

No client keys found. Generating new WireGuard key pair...
Generated keys (saved to ~/.config/bnerd/wireguard/bnerd0.key)
  Public Key: sO4RpKlRDdxCOPIbs5r0w7N/kGuxgEKZewCKnt9r3hc=

Important: Send this public key to your bnerd contact person.
They will add it to the VPN server to authorize your connection.

Step 3: Register Your Key

Send the displayed public key to your VPN administrator. They need to add your peer to the server:

[Peer]
PublicKey = <your-public-key>
AllowedIPs = 10.8.0.2/32

Once they confirm, reconnect:

sudo bnerd up

You should see:

Using existing client keys
Connecting to bnerd gateway (de-muc1)...
WireGuard interface bnerd0 is up

VPN connection established!
  Interface: bnerd0
  Address:   10.8.0.2/24

Usage

Connect

sudo bnerd up

Check Status

bnerd status

Or with continuous monitoring:

bnerd status -w

Disconnect

sudo bnerd down

Show Peer Info

When setting up on a new server or providing your info to an administrator:

bnerd up --show-peer-info

Regenerate Keys

If you need a fresh key pair:

bnerd up --regenerate-keys

Warning

After regenerating keys, you must send the new public key to your VPN administrator to re-authorize your connection.

Troubleshooting

Permission Denied

VPN operations require root privileges:

sudo bnerd up

WireGuard Not Found

Install WireGuard tools for your platform (see Prerequisites above). The client auto-detects kernel vs. userspace mode.

Connection Timeout

  1. Verify the server endpoint is correct in your config
  2. Check that UDP port 51820 is not blocked by your firewall
  3. Confirm your public key has been added to the server
  4. Use --debug for detailed diagnostics: sudo bnerd --debug up

Switching to a Different Server

  1. Update ~/.bnerd.yaml with the new server endpoint and public key
  2. Show your peer info: bnerd up --show-peer-info
  3. Send it to the new server's administrator
  4. Disconnect and reconnect: 
    sudo bnerd down
sudo bnerd up

Your private key stays the same — only the server details change.

Configuration Reference

See VPN Configuration Reference for all available settings.

Next Steps