⬸ more blog posts

WireGuard cheatsheet

Learn how to set up a WireGuard client on a Mac. Installation instructions using the command line.

WireGuard is a VPN that works well for mobile users. It automatically takes care of roaming and makes sure that the connection between peers stays secure even as IP addresses change.

This walkthrough assumes you are adding a new Mac to an existing WireGuard network. Because of this, there are a few steps that require you to ask and send information to the person who setup the initial network. I'll refer to this person the sysadmin.

Hopefully this will extend the official documentation, so that you won't hit the same issues I did when getting set up on a Mac. This article from Stavros was also helpful with setup / troubleshooting.

Step 1: Install WireGuard tools

From the Terminal app, install tools using homebrew.

brew install wireguard-tools

This installs both "wg" (main WireGuard utility) and "wq-quick" (used in this tutorial to start/stop WireGuard).

Step 2. Configure your device

Create a directory for wireguard configuration files

cd ~/.config/
mkdir wireguard
cd wireguard/

Using the wg utility, create your public and private keys

wg genkey | tee privatekey | wg pubkey > publickey

Secure the keys

sudo chmod -R og-rwx ~/.config/wireguard/*

Copy your public key to your clipboard (you will send this in the next step). Be careful, do not share your private key!!!

cat publickey | pbcopy

Step 3: Communicate with your WireGuard administrator

Next, send your public key to your WireGuard sysadmin and ask for your connection info and peers. WireGuard assumes that you have a secure channel to exchange these keys on. Make sure to exchange these values in person or using an end-to-end encrypted channel. (Matrix, Signal, etc)


  • Your public key (from your clipboard)

Ask For

  • an internal IP address and port

  • the public key, allowed IPs, and endpoint for all the other peers that you want to connect to

Once you exchange that information and the sysadmin has added you as a peer for the other clients, it is time for the next step.

Step 4. Setup your configuration file

Copy your private key into your clipboard. Do not share this private key with anyone else.

cd ~/.config/wireguard/
cat privatekey | pbcopy

Create and open your configuration file. We will use nano in this example, but feel free to use whatever text editor you prefer

nano wg0.conf

Add configuration info to you config file

Address = [the IP address assigned by the sysadmin]
PrivateKey = [paste from your clipboard]
ListenPort = [the port assigned by the sysadmin]

PublicKey = [peer 1 public key]
AllowedIPs = [peer 1 IP(s)]
Endpoint = [peer 1 Endpoint]
# This is for if you're behind a NAT
# and want the connection to be kept alive.
PersistentKeepalive = 25

PublicKey = [peer 2 public key]
AllowedIPs = [peer 2 IP(s)]
Endpoint = [peer 2 Endpoint]


You can add as many peers as you need, just keep adding them to the bottom.

Also, you only need the "PersistentKeepalive" line once. This will intermittently ping that peer, so that you don't time out when you are behind a NAT (e.g. a firewall that is clearing out IPs when they aren't actively connected). Without this, you might not receive incoming peer requests.

If you aren't familiar with nano, type ctrl-x then y to save and exit (or n to exit without saving).

Step 5. Start WireGuard

You should now be configured and ready to start up WireGuard.

wg-quick up ~/.config/wireguard/wg0.conf

Test that you are connected by pinging a peer by their IP address that you got from the sysadmin.

ping [peer IP]

If you see pings, you are all done, woohoo! Welcome to your new WireGuard connection.

To turn WireGuard off

wg-quick down ~/.config/wireguard/wg0.conf

published oct 4, 2018

want updates from hq.network?

We respect your privacy.

experience a better internet now

see plans and pricing