WireGuard

Overview #



WireGuard allows you to establish a VPN tunnel, connecting a remote Dongle-M and a Home Assistant (HA) host into a single local network. This enables you to add a remote Dongle-M in HA and manage Zigbee devices remotely via ZHA or Z2M.


Prerequisites #


  • HA host must have a public IP.
  • Using Home Assistant platform.
  • WireGuard Add-on
  • DuckDNS Add-on
  • Advanced SSH & Web Terminal Add-on


Overall Workflow #


  1. Configure port forwarding on your router to map the HA host to the public internet.
  2. Use DuckDNS to create a dynamic domain name to handle changing public IPs.
  3. Enable WireGuard on Home Assistant to create a VPN network, exposing the host to the public network.
  4. The remote Dongle-M connects to the HA host via the public IP or dynamic domain, putting both devices on the same LAN.
  5. Add Dongle-M in ZHA/Z2M to add and control remote Zigbee devices.


Detailed Steps #



1. Configure Port Forwarding on the Router #


Purpose: Map the HA host to the public network so the remote Dongle can access it.


① Go to Network>>Firewall>>General Settings, set Forward options to accept;


② Go to Port Forwards, click Add, and forward UDP packets from port 51820 to the HA host’s port 51820.

Configuration Example:

  • Service Name: WireGuard
  • Device IP Address: IP address of Home Assistant
  • External Port: 51820
  • Internal Port: 51820
  • Protocol: UDP


2. Configure DuckDNS Dynamic Domain #


Purpose: Assign a dynamic domain pointing to your home network public IP. Even if the IP changes, the domain will always resolve correctly.


Note: Ensure your home network has a public IP; otherwise, this will not work.

  1. Create a domain and record your token. Example:
  • Domain: dongle-m.duckdns.org
  • Token: 25d53333-3f5a-45ec-8572-bbe59702016b


3. Install DuckDNS Add-on in Home Assistant. Configure the domain and token, then save and start the add-on.


4. Install and Configure WireGuard Add-on in Home Assistant #

Install WireGuard:


5. Configure Dongle-M WireGuard #


Copy the contents of the client.conf file from Home Assistant into the WireGuard configuration section of the Dongle-M.

What are your feelings

Updated on September 12, 2025