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 #
- Configure port forwarding on your router to map the HA host to the public internet.
- Use DuckDNS to create a dynamic domain name to handle changing public IPs.
- Enable WireGuard on Home Assistant to create a VPN network, exposing the host to the public network.
- The remote Dongle-M connects to the HA host via the public IP or dynamic domain, putting both devices on the same LAN.
- 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.
- Visit duckdns.org and log in.
- 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:
https://github.com/hassio-addons/addon-wireguard
For detailed configuration steps, please chlick:
https://github.com/hassio-addons/addon-wireguard/blob/main/wireguard/DOCS.md
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.

