If you are new to Wireguard, be sure to read our Wireguard introduction guide for beginners.
Wireguard VPN as a protocol is a bit different than a traditional VPN. I use the "server" and "client" terminology in these articles to simplify our understanding and make the transition to this idea a bit more comprehensible.
The truth is, that Wireguard as a protocol simply creates secure "tunnels" between peer devices. How we interact with these tunnels, and how those tunnels connect is what gives Wireguard its flexibility.
For details on setting up your own Wireguard server or modifying the server's config file, see our other articles on setting up a WireGuard server on Linux, Docker, and Windows.
Table of Contents
- Wireguard Mac OS Client Setup
- User Defined DNS servers
- Route All Traffic Through the Wireguard Server
- FAQs
- Why can't I connect to another device?
- Can I have more than one Wireguard tunnel active at a time?
- How do I add better security with a Preshared Key?
- Can I use Wireguard Mac client with IPv6?
- How do I export my config if I generated it myself?
- Why can't I connect to the Internet after starting my Wireguard client?
- What is On-Demand and how does it work? Can I set Wireguard to auto-connect?
- Final Thoughts on Wireguard Client Setup for Mac OS
Wireguard Mac OS Client Setup
You will sometimes hear about a "Road Warrior" setup with regards to Wireguard. This approach embraces the traditional server/client model - no matter where we go, our device is always able to connect to a static "home" server. This article will follow this approach and give a basic walk-through on connecting our Wireguard Mac "client" to a Wireguard "server".
According to the Wireguard documentation, there are two ways to install and utilize the protocol on Macs. One is with a GUI, which can be installed directly from the App Store, while the other is a CLI version and involves installing it via Homebrew. This guide will focus on the former.
Be the 1 in 200,000. Help us sustain what we do.You will gain benefits such as Deployarr access, discord roles, exclusive content, ad-free browsing, and more.🔥 Holiday Sale! 25% Off Platinum Membership$399.99$299.99 (ends December 31).Join the Geek Army (starting from just $1.67/month)
1. Install Wireguard
Following the directions listed on the Wireguard website, download and install the Wireguard program via the App Store. The same program is used no matter if you are setting up a "server" or "client":
Once installed, we will be greeted by an empty Wireguard window.
An icon for Wireguard can also be found in the top bar.
2. Create the Local Wireguard Adapter
Wireguard works by creating a virtual adapter to route your traffic through. There are 2 ways to setup Wireguard Mac OS client. Both require a set of configurations which can either be delivered to you as a single file, or created through the GUI. Let's look at both ways.
Option 1: Importing a Given Configuration File
If I am running the Wireguard server, I find it easiest to create the configuration files from my "server" and then share them as needed with each "client" device. Whether the complete config file came from your server or a commercial provider (eg. NordVPN), adding it to your client couldn't be easier. [Read: Commercial VPN providers that support Wireguard]
If this is your first tunnel, click the 'Import tunnels from file' button in the center of the screen. If you already have an existing tunnel, either use Command + O or click the plus sign '+' in the bottom-left corner and select 'Import Tunnel(s) from File...'.
We are greeted with a window in which we must choose the config file. Navigate to the location where it is stored, and open the file.
Note: You will likely be asked by the system whether or not to allow Wireguard to add a VPN Configuration. Click Allow.
We are then taken back to the main window with the newly added tunnel name listed to the left, and the details listed in the main pane to the right.
Edit the Tunnel (Optional)
At this point you can click the 'Activate' button to get started. But before we do, let's click the 'Edit' button in the bottom right to see the details of the adapter. Here we can edit any details including the name if you would like something more verbose than "wg0".
Option 2: Create a Configuration of Your Own
In this scenario, we will create the configuration ourselves, and only pass the client's "Public Key" to the server to add it as a new [Peer]. You will need, however, a few details from the Wireguard server you intend to connect to: the server's Public Key, Endpoint IP Address and Port, and Allowed IPs.
Create a new tunnel
At the bottom of the Wireguard client window, click the plus sign '+' and select 'Add empty tunnel...' Alternatively, use Command + N:
We are greeted with a new screen, with some information already filled in for us.
Add Known Information
Start by giving our new tunnel a name. I will be using "wireguard". Moving to the next section, we need to add a few pieces of information. Below is a template of what should be included at the bare minimum. Remember that Wireguard VPN protocol doesn't use the "server" and "client" naming scheme even though we can setup tunnels to work this way. So below, we will refer to our server under the [Peer] section.
I will be using the details I created in my example Wireguard Linux Server article. Refer to that article if you have questions on why or how the following is set.
[Interface] PrivateKey = Address = [Peer] PublicKey = AllowedIPs = Endpoint =
Everything under the [Interface] section refers to settings happening on this machine you are working on:
- PrivateKey is pre-generated and filled for us already.
- Address is the IP address we wish to assign on our local machine. To simplify and avoid overlapping IP mapping, I generally use the same range as the server and pick an unused address.
Everything following under the [Peer] section will refer to the details we need from the server:
- PublicKey is as the name suggests the Public Key from the Wireguard server.
- AllowedIPs sets which IP addresses we want routed through our Wireguard tunnel. To start, I will just be using the same set of addresses available to our Wireguard server.
- Endpoint is the IP address (or domain name) of our Wireguard server along with the port it is listening on.
The final file should look something like below (with your own keys and IP addresses)
Click 'Save' to close the window.
Add Client Details to your Wireguard Server
Now that the client is set, a few details need to be shared with the machine hosting the Wireguard VPN server. The client has to be added as a peer on the server. This has been described in our Linux Wireguard server guide.
At the very least, the server will need your client's Public Key and Address. Once added to the server, we can continue!
3. Activate the Tunnel!
Next step in the Wireguard Mac OS client setup process is to activate the tunner.
Click the 'Activate' button in the middle of the screen and after a second or so you should see the status change, the circle changes to green, and the app icon in the top bar change from gray to white.
4. Test Your Connection
It's always a good idea to test and make sure things are working as expected, which can be accomplished in a few ways.
Using the Terminal
You can test to make sure your connection is working by using the simple Terminal command ping.
Open a new terminal window by either going to your Finder --> Applications --> Utilities --> Terminal, or by pressing Command + Spacebar and typing the word "terminal" followed by the Return/Enter key.
In this case since our server is running on IP address 10.254.0.1, we can simply ping the address and look for a response:
ping -c 10 10.254.0.1
Access a service on the Wireguard server
I also setup a Nextcloud instance on my Wireguard server to test the tunnel. Opening a browser and inputting the IP address of the Wireguard server (10.254.0.1) followed by the port I set (8080) brings me directly to my personal cloud.
Success! Even though I don't have SSL/TLS setup (as seen by the crossed-out lock symbol in the top bar), it is still a secure connection through a Wireguard tunnel. If you'd prefer to access it via a domain name, consider setting up a local DNS resolver like Pi-Hole or AdGuard Home.
5. Access Additional Local Resources
The setup above allows you to connect directly to your Wireguard server and access anything running on it. If you have IP forwarding setup on the server, you can also access other peers who are connected to the same Wireguard server. In the example given, that would be any device connected to your server using the 10.254.0.1-10.254.0.254 range.
However, we might have other devices connected to the same local network as the Wireguard server, but not connected via Wireguard. In this scenario, we are still able to reach the other devices but must make a modification to our Mac Wireguard client. We need to modify our interface just slightly so that the Mac knows to pass requests to those IP addresses through the Wireguard tunnel (and not directly to the whatever network you are currently using). That might sound cryptic, but read on to see a working example.
The 'AllowedIPs' Section
Let's say I have an additional device on my home network that isn't attached directly to my Wireguard server; for example, a Raspberry Pi running my Jellyfin server. Let's say it is running on our home network with the IP address 192.168.100.191.
Currently, we are at Friend's house, and we type that address into our browser. Our computer would find that the site cannot be found.
This is because 192.168.100.191 isn't included in the AllowedIPs section of our Wireguard interface. Our browser looks for the device in Friend's network instead of through the Wireguard tunnel to our home network. Let's modify our client's "AllowedIPs" to make sure the request is passed through Wireguard.
Edit Our Wireguard Client Adapter Settings
Open your Wireguard Mac Client and click the 'Edit' button in the bottom right corner. We see a new window pop up. Let's add the IP 192.168.100.191/32 of our Raspberry Pi:
Click 'Save'. We see the adapter stopped and restarted with the new settings. Head to your browser and type in the address to see if Jellyfin can be correctly resolved.
Success!
Note: If you want to add more IPs for your local network, they are best added as a range. They can be entered as:
192.168.100.0/24
User Defined DNS servers
This section applies to anyone using Pi-Hole/AdGuard Home or who wishes to set custom DNS for their Mac with Wireguard. [Read: Complete Pi Hole setup guide: Ad-free better internet in 15 minutes]
If you decide not to route ALL of your traffic (see below) through your Wireguard server, you can still add DNS servers to your config. In this example we add a declaration using Cloudflare's DNS servers under the [Interface].
Open your Mac Wireguard client, and click the 'Edit' button in the bottom right corner. Add the following:
[Interface] ... DNS = 1.1.1.1, 1.0.0.1
Your finished Wireguard client configuration should look like below:
Click 'Save' and the adapter will be recreated.
I wasn't able to easily verify via command line that the new DNS servers were, in fact, the ones being used. You can see them listed using the Terminal command:
scutils --dns
But it wasn't clear since there were many listed. The closest verification I could get was by using a DNS leak testing site like https://dnsleaktest.com.
Note: If you have a Pi-Hole or AdGuard Home instance running, you would use the IP that they are bound to as your DNS server IP. This IP must also be included in the AllowedIPs section. For example, if you have Pi-Hole running on the same machine as your Wireguard server, you can use:
DNS = 10.254.0.1
Route All Traffic Through the Wireguard Server
Routing all traffic through our Wireguard server is generally quite easy to accomplish from the Mac Wireguard client. As above, we just need to open the Wireguard client window, and click the 'Edit' button in the bottom-right corner. Next we change AllowedIPs to 0.0.0.0/0.
Excluding Private IP Ranges
At the bottom of the window, you might notice there's an additional checkbox that did not exist before - Exclude private IPs. This setting allows you to pass all of your traffic through your Wireguard VPN EXCLUDING private address ranges like 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.
Be the 1 in 200,000. Help us sustain what we do.You will gain benefits such as Deployarr access, discord roles, exclusive content, ad-free browsing, and more.🔥 Holiday Sale! 25% Off Platinum Membership$399.99$299.99 (ends December 31).Join the Geek Army (starting from just $1.67/month)
FAQs
Why can't I connect to another device?
Ensure the device you are trying to connect to is within your "AllowedIPs" range. Remember that you can set individual IP's or a whole range of IP's. Most home routers use DHCP (dynamic host configuration protocol) which means that a device's IP can change occasionally (especially on router restarts).
In this case, you can give a range such as 192.168.1.0/24 to cover all devices in the 192.168.1.1 - 192.168.1.254 range. Also check firewall rules and DNS settings.
Can I have more than one Wireguard tunnel active at a time?
Yes, but unfortunately not through GUI. The GUI only allows running a single interface at a time. However, if you are willing to dive into the Terminal, we can have multiple interfaces active. Begin by following the installation instructions for Homebrew.
Once installed, we can grab the CLI version of Wireguard for Mac with the command:
brew install wireguard-tools
The next part is just a repeat of the Wireguard Linux Client commands, so I will direct you to that article for more in-depth instructions. The short version is to copy your config files to either /etc/wireguard or /usr/local/etc/wireguard/ and use:
sudo wg-quick up wg0
While not strictly necessary, the Preshared Key adds a layer of security to better protect our tunnel against attacks by advanced threats. Again, not strictly necessary but easy to add in my opinion. The generated key will need to be included in both the server's config file and in the client's config file.
If generated from the server, open your Wireguard for Mac client, click the 'Edit' button and add it into the client config under the [Peer] header.
To generate a Preshared Key from your Mac, you must use the CLI version of Wireguard. To use the CLI, you must install Wireguard for Mac via Homebrew (see above).
The process follows the Wireguard Linux Client so I will not go into depth. The short version is to use your terminal to generate a Preshared Key (PSK), copy it into both your client config, and into the server config.
sudo wg genpsk
Can I use Wireguard Mac client with IPv6?
Absolutely. Anywhere you see an IPv4 address, you can add a valid IPv6 address as well. Make sure your server can handle IPv6 requests or you might have trouble with the Wireguard tunnel.
How do I export my config if I generated it myself?
In your Mac Wireguard client window, click the gear icon at the bottom of the left-hand-side window. Select 'Export Tunnels to Zip...', find a location you prefer, and save the zip file. Unzip and you'll find all of your configs included.
Why can't I connect to the Internet after starting my Wireguard client?
As the joke goes... "It's Always DNS". If using 0.0.0.0/0, double check your server is able to resolve domain names. Check to see if your adapter settings were reset. Try setting a DNS server as stated earlier in this article. You might need to set the DNS for the Wi-Fi/Ethernet device. You can also set your DNS to the IP of the server itself depending if you have something like unbound running.
What is On-Demand and how does it work? Can I set Wireguard to auto-connect?
This is a neat setting that appears to be exclusive to the Mac Wireguard GUI client. When enabled, you can have Wireguard connect automatically when either Ethernet is enabled, or with specific rules regarding Wi-Fi.
You can specify for the Wireguard client to connect via Wi-Fi when on:
- Any SSID - Anytime Wi-Fi connects, similar to how Ethernet On-Demand works.
- Only these SSIDs - Only auto-connect when on a specified Wi-Fi network (work for example).
- Except these SSIDs - Always connect EXCEPT when connected to specified networks (don't activate when already on your home network for example).
Final Thoughts on Wireguard Client Setup for Mac OS
When compared to some of the other implementations of a Wireguard GUI, the Mac Wireguard app definitely leads the pack in terms of user-friendliness and ease of setup. That being said, it also comes with some limitations that will push some users towards the CLI version.
Either way, using Wireguard on Mac still follows the tenet of being fast, modern, secure, and easy. As privacy concerns mount, Wireguard proves that it is a leading contender for an added layer of security that anyone can access.
Considering how simple Wireguard Mac OS client setup is, I can no longer imagine surfing the Internet without a VPN!
