Skip to content

VPN Quick Start

Connect your machine to your organization's WireGuard VPN in three commands. The CLI enrols the machine as a device; b'nerd issues the tunnel configuration for it. You never send a key to anyone and nobody hand-edits a server for you.

What you can reach

A device reaches exactly the services your organization exposed through its gateway (for example gitlab) and nothing else — everything not explicitly granted is dropped on the gateway. If a service does not answer, ask your organization admin whether your device is authorized for it; the tunnel itself can be up while the answer is "nothing is exposed to you yet".

Prerequisites

  • bnerd 0.3.0 or newer — check with bnerd vpn --help; if there is no up subcommand, upgrade (see Installation).
  • WireGuard tools (wg, wg-quick): sudo apt install wireguard / brew install wireguard-tools / sudo pacman -S wireguard-tools. Kernel WireGuard is used when available, userspace wireguard-go otherwise.
  • An org-wide access token with at least the vpn_devices:write scope. Scopes nest read < write < manage < *, so a vpn_devices:* or * token works too. A token pinned to one project does not — gateways and devices are organization-level. You do not need any vpn_gateways scope to connect.
  • Your organization must already have a ready WireGuard gateway. Creating one is an org-admin task: bnerd vpn gateways — --region picks which one when the organization has more than one (bnerd vpn regions lists them); most organizations have exactly one and never need the flag.

1. Configure the CLI

# ~/.bnerd.yaml
api-url: https://api.bnerd.cloud
token: your-org-wide-token      # scope vpn_devices:write (or wider)
org-id: your-organization-id

bnerd config set token … / bnerd config set org-id … write the same keys.

2. Connect

bnerd vpn up

On the first run the CLI generates a key pair on this machine, sends only the public key to b'nerd, receives the tunnel configuration, writes it to ~/.config/bnerd/wireguard/bnerd0.conf and brings the interface up (this last step asks for sudo). You will see:

✓ Generated a new key pair (private key kept in ~/.config/bnerd/wireguard/<device>.key, mode 0600)
✓ Enrolled device <device> (…) on gateway <gateway> as 100.64.2.194
Connecting to <gateway> (203.0.113.10:51820), routing 100.64.2.0/24...
✓ Connected to bnerd (bnerd0)

The device name defaults to your hostname; pass --device my-laptop to choose one.

If the gateway is still provisioning

Right after an admin created the gateway, the first bnerd vpn up may end with "the VPN gateway is still provisioning — try again in a few minutes". Your device is already enrolled; simply run the same command again. It is idempotent — it reuses the enrolment and never creates a second device.

Running bnerd vpn up again later reuses the existing enrolment and just brings the interface up. If you enrolled this machine through the dashboard instead (Account → VPN devices → download the .conf), put the downloaded private key into ~/.config/bnerd/wireguard/<device>.key (mode 0600) and run bnerd vpn up --device <device> — the CLI adopts the existing enrolment by its public key rather than creating a new device.

3. Check and disconnect

bnerd vpn status        # interface, handshake age, traffic counters
bnerd vpn down

A fresh handshake in status (or sudo wg show) means the tunnel is up. Reaching a service additionally needs the authorization described at the top.

Your devices

bnerd vpn devices list
bnerd vpn devices revoke <device-id>

Revoking cuts the device off at the gateway within about a minute; the machine can enrol again with bnerd vpn up. Lost laptop: revoke it here, no admin needed.

Troubleshooting

You see Meaning Do
Access token does not have permission for this action — this token lacks thevpn_devices:writescope … the token is project-pinned or missing the scope create an org-wide token with vpn_devices:write
the VPN gateway is still provisioning — try again in a few minutes the gateway has not reported its key/address yet wait, run bnerd vpn up again
this organization has several ready WireGuard VPN gateways — pass --gateway … more than one gateway add --gateway <id>
could not bring up bnerd tunnel wg-quick failed (usually missing sudo or WireGuard tools) run with sudo available; sudo wg-quick up ~/.config/bnerd/wireguard/bnerd0.conf shows the raw error
handshake OK, service unreachable your device is not authorized for that exposure (default-deny) ask your org admin to grant it
no handshake at all UDP to the gateway's <floating-ip>:51820 is blocked, or the device was revoked check outbound UDP/51820; bnerd vpn devices list

bnerd --debug vpn up prints every API call.

Command reference

bnerd vpn — flags, exit codes, and the deprecated bnerd up / bnerd down / bnerd status aliases of the commands above.