How to install WireGuard VPN Addon in Home Assistant with custom domain name

In this guide, I’m going to show you how to setup, configure, and install Wireguard VPN in Home Assistant using a custom domain name. This will allow you to not only access Home Assistant remotely, but also all of your other internal sites and services. Things like security cameras, dashboards, or services like Sonarr and Radarr.

I’ve seen quite a few Wireguard how-to guides with instructions to use DuckDNS, but since I have an available domain sitting in Cloudflare – I’m going to use that instead.

Let’s get started!

---

Step 1: Find your home’s IP address

Go to Google and type “what’s my IP address” in the search box. It will then show you the external IP address of your router.

---

Step 2: Create a DNS A Record

Next, create a DNS A record in your domain registrar. Like I said, my domain name is on Cloudflare so the screenshot below reflects that. It should be pretty similar for other registrars, for example I use Namecheap for this site.

The resulting URL will be vpn.mydomain.com.

• Name: VPN
• Content: your home’s IP address
• Proxy status: DNS only

---

Step 3: Install Wireguard Addon in Home Assistant

Next, open up Home Assistant. Go to Supervisor > Add-on store, and search for WireGuard.

Click the WireGuard addon, and the click Install.

---

Step 4: Configure Wireguard Settings

After installing WireGuard, do not start it yet. We need to configure a few options first.

Click the Configuration tab at the very top.

There are two blocks of code here: server and peers. The server section is the WireGuard server info, and the peers section is where you’d add new devices that will connect to your VPN.

Note about addresses: If you’re internal network uses the 172.x.x.x subnet, then you’re going to want to change the default IP addresses WireGuard has already autofilled for you. This will prevent routing issues and/or IP address conflicts. On Windows, open CMD and type “ipconfig” and locate the IPv4 section if you aren’t sure.

Under the Peers section, set the IP address to the next available IP in your range. For example, I’m using 172.27.66.1 for the server, and 172.27.66.2 for the peer(client).

Server Configuration

• Host: add the subdomain you just created. (vpn.mydomain.com)
• Addresses: If your internal network is using the 192.168.x.x or 10.x.x.x range, you can leave the default IP addresses WireGuard has provided. (see note above)
• DNS: Set to your router’s internal IP address (Open CMD > ipconfig /all > Under DNS servers)
  • If you have Adguard or PiHole installed, you can use the IP address of those instead. This will allow you to block ads even when connected to the WireGuard VPN.

Peers Configuration

This is where you’ll create WireGuard configuration files for each of the devices you want to connect to WireGuard with. For this example, I’m using my phone and leaving allowed_ips and client_allowed_ips as is. If you adding multiple devices, then you’ll need to copy the entire block of code starting at – name, give it a different name, and add the next available IP address (172.27.66.3)

Click Save once finished.

Then, go back to the Info tab and click Start.

---

Step 5: Port Forward

The next step is to forward port 51820 from your Home Assistant server through your router. Unfortunately, there are so many different types of routers, each with different steps to port forward so I can’t show you exactly how to complete this step. I’m using a TP Link Deco M5 router.

However, I can give you a screenshot of my port forwarding rules. The important thing to note is that you’ll be port forwarding 51820(wireguard port) from the internal IP of your Home Assistant instance (mine is 192.168.68.24) and choosing the UDP protocol only.

---

Step 6: Download Wireguard app

Download the WireGuard app from the Apple App Store or Google Play Store. You will need it for the next step.

---

Step 7: Locate Generated QR Code

Next, we need to scan the QR code generated from within WireGuard that was created whenever you created a new “peer”. QR Codes are located in the /ssl/wireguard directory.

There are two ways to access that directory: from File Editor or from Visual Studio Code. I’ll show you both methods below.

Find QR Code in VSCode Addon

If you using the VSCode addon, you can add a new sidebar item to quickly access the QR codes in the future. Open Visual Studio Code from the sidebar and right click in the empty sidebar > Add folder to Workspace.

Search for SSL, and then click the wireguard folder.

Then, click OK. The wireguard directory will now be available in your Visual Studio Code column.

Locate the qrcode.png file and open it. If the QR code doesn’t display in VSCode, you can right-click and download it.

Find QR Code in File Editor

If you use File Editor instead of VSCode, you’ll first need to change a setting in the File Editor addon in order to access the /ssl directory that contains the QR code.

Go to Supervisor > File Editor > Configuration tab > change enforce_basepath: to false. Then save the options and restart the File Editor addon.

When you go back to File Editor from your sidebar, you can now go up one more level by clicking the folder at the top > back arrow > scroll down until you locate the /ssl directory.

Now, you’ll see the qrcode.png file in File Editor:

---

Step 8: Scan QR Code

The next step is easy: Just scan the QR code from the mobile app!

In the app, click the + button.

Click Scan From QR Code.

Then give the tunnel a name (any name is fine here. It’s just for your reference.)

Then, disable wifi on your phone and toggle the WireGuard connection to on from within the app.

---

Step 9: Testing it Out

If all goes well, you can click into the new tunnel connection from within the app. If you see data flowing under the Transfer section, that means you are good to go!

You can now try accessing some of your internal sites and services. For my test, I opened my Homer dashboard, Uptime Kuma server monitoring webgui, and Overseerr and all launched just as expected. I also tested using Remote Desktop app from my phone to my pc, and that works as well! Just make sure to use your computer’s IP address instead of the computer name.

---

MAC Users:

A Redditor commented this for use with MAC. I’m just going to copy and paste his comment as I don’t have one to test/confirm with:

“Okay, so I went back and removed Wireguard and started over following the guide from above. I got it to work through VSC but I could not use the full /ssl command. I then had to command click on the code(I am a Mac user) to get it to pull up in the side bar, from there I could download the QR code.

I’m sure you probably don’t even need to hit enter on it, I did /ssl/WireGuard/ and from there you can command click on it. (Command key+click) and it would pull the file up like you added it to the workspace. Right click on the QR file on the left and download.”

---

(Optional) Step 10: Security Improvements

Once you have everything setup and working correctly, you should read through the WireGuard Addon docs to setup up allowed_ips and client_allowed_ips to further secure your VPN instance. There’s also some other helpful options you can configure such as log level, but these are all optional.

---

Wrapping Up

Hopefully this guide helps you setup WireGuard VPN correctly with a domain name you own! I still subscribe to Nabu Casa to support the devs, but I’ve been looking for a way to access the web interfaces of all my sites and services for a while. I’ve attempted the Wireguard Docker container a few times unsuccessfully, so I was extremely happy to see this was such a straightforward process from directly within Home Assistant.

Let me know in the comments below if you were able to set it up by following my guide or if you need any help!