Why WireGuard with Home Assistant?

WireGuard offers several advantages for Home Assistant users:

• Speed and efficiency: WireGuard uses lean cryptography and minimal CPU overhead.
• Simplicity: A clean configuration model with concise keys and peers.
• Strong security: Modern protocol, uses state-of-the-art cryptography.
• Flexible deployment: Run on the same machine as Home Assistant, in a container, or on a dedicated device.

For Home Assistant environments, you typically want one of these deployment options:

• WireGuard on the same machine as Home Assistant (if you’re comfortable with port exposure and potential resource impact).
• WireGuard in a separate Docker container (clean separation, easier updates).
• WireGuard on a dedicated Raspberry Pi or small server accessible in your network.

Choosing a deployment option

On the same machine as Home Assistant (supervised or core)

Pros:

• Simple to connect to the local network.
• Fewer moving parts. Fewer containers to manage.

Cons:

• Potentially higher resource usage on your Home Assistant device.
• Network exposure considerations for the host.

In a container (recommended for many setups)

Pros: WireGuard on OpenWrt: a practical guide to secure VPNs on home routers

• Isolation from core Home Assistant.
• Easier updates and backup of VPN configs.
• Works well with Home Assistant OS, Supervised, and Core with Docker.

Cons:

• Slightly more complex networking (bridges/ports).

On a dedicated device (Pi, small server)

Pros:

• Best for performance and isolation.
• Can serve multiple clients or sites.

Cons:

• More hardware to manage.

Installation options

• WireGuard hardware or OS packages: If you’re running a Linux-based Home Assistant host, you can install wireguard-tools and wireguard-dkms (or wireguard for your distro). On Raspberry Pi OS or Debian-based systems, use apt-get.
• Containerized: Use a lightweight container image that ships with WireGuard and a simple management interface.
• Home Assistant add-on: There are third-party add-ons that wrap WireGuard configuration for easier control from the Home Assistant UI.

Important note: If you’re using Home Assistant OS, you’ll typically use a container or add-on approach rather than modifying the core system. Always back up before changes.

Basic concepts and architecture

• Server and peer model: The server is the WireGuard host, and each remote device is a peer.
• Keys: Each peer uses a private key and a public key. The server needs the peer’s public key and allowed IPs.
• AllowedIPs: Defines what traffic is routed through the VPN. For remote access, you typically route your entire client traffic through VPN or only access Home Assistant’s LAN.
• PersistentKeepalive: Helps with NAT and firewall maintainers. A small value like 25 seconds can keep the tunnel alive through NATs.

Step-by-step setup (containerized or host-based)

Note: Adapt paths and commands to your environment. WireGuard on QNAP

1. Install WireGuard
   • On Debian/Ubuntu:
   • sudo apt update
   • sudo apt install wireguard-tools wireguard-dkms
   • On Raspberry Pi OS or similar:
   • sudo apt update
   • sudo apt install wireguard-tools wireguard-dkms
   • If using Docker, pull a WireGuard-friendly image and follow its docs.
2. Generate keys
   • wg genkey | tee privatekey | wg pubkey > publickey
   • Save:
   • PrivateKey: contents of privatekey
   • PublicKey: contents of publickey
3. Create server config

Example server config (server.conf):

[Interface] Address = 10.0.0.1/24 ListenPort = 51820 PrivateKey = SERVER_PRIVATE_KEY SaveConfig = true

Keepalive

[Peer] PublicKey = CLIENT_PUBLIC_KEY AllowedIPs = 10.0.0.2/32

Notes:

• Use a unique internal address space (e.g., 10.0.0.0/24) for VPN.
• You can add multiple [Peer] sections for more clients.

4. Create client config

Example client.conf: WireGuard on Debian

[Interface] PrivateKey = CLIENT_PRIVATE_KEY Address = 10.0.0.2/24 DNS = 1.1.1.1

[Peer] PublicKey = SERVER_PUBLIC_KEY Endpoint = your.home.public.ip:51820 AllowedIPs = 0.0.0.0/0,::/0 PersistentKeepalive = 25

5. Enable routing and firewall
   • Enable IP forwarding:
   • sudo sysctl -w net.ipv4.ip_forward=1
   • echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
   • Add firewall rules to allow UDP 51820:
   • sudo ufw allow 51820/udp
   • If using NAT for remote clients:
   • sudo iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE
   • Save iptables rules as appropriate for your distro.
6. Start WireGuard
   • Server:
   • sudo wg-quick up server
   • sudo systemctl enable wg-quick@server
   • Client:
   • Bring up in the client device:
   • sudo wg-quick up client
   • Or use a GUI or mobile app that supports WireGuard and import the client config.
7. Verify connection
   • On the server, check:
   • sudo wg show
   • From a client, try pinging the server IP:
   • ping 10.0.0.1
   • Access Home Assistant via the VPN network:
   • http://10.0.0.1:8123 (or your configured port)
   • Ensure traffic to Home Assistant is routed through the VPN if desired.

Integrating WireGuard with Home Assistant (UI and automations)

• Home Assistant add-ons: Some users install WireGuard as an add-on for easy controls from the UI. These add-ons typically expose start/stop/reload and status within Home Assistant’s supervisor.
• Automations: Create automations to alert you if the VPN goes down, or to automatically start the VPN at certain times or network conditions.
• DNS considerations: If you run Home Assistant behind a domain with a dynamic IP, consider using a dynamic DNS service. WireGuard can keep a stable IP inside the VPN, while your domain points to your home’s external address.

Security considerations and best practices

• Use strong keys: Generate long, random keys and rotate periodically.
• Limit peer permissions: Only allow the traffic you need with AllowedIPs. If you only want remote access to Home Assistant, set AllowedIPs to your Home Assistant LAN range (e.g., 192.168.1.0/24) or even more restrictive.
• Disable unused services: Turn off any services you don’t need to reduce attack surface.
• Regular backups: Store your server and client configurations securely. If you use a container or add-on, keep a backup of the config files and keys.
• Update promptly: Keep WireGuard and the host OS updated to patch vulnerabilities.
• Use a strong endpoint: If you’re enabling remote access, ensure your home network’s router is hardened, and consider running VPN on a dedicated device for better isolation.

A quick comparison: WireGuard on Home Assistant vs. alternative remote access options

Troubleshooting common issues

• Problem: VPN connection fails to establish.
• Check that the server’s UDP port is open and reachable from the client network.
• Verify PublicKey and PrivateKey pairs in server and client configs.
• Ensure correct Endpoint in client config (public IP or domain and port).
• Problem: No traffic through VPN, can’t reach Home Assistant.
• Confirm AllowedIPs on the server include the client IP.
• Verify IP forwarding is enabled on the server.
• Check firewall rules to allow traffic from the VPN subnet to the LAN.
• Problem: DNS or domain resolution issues when remote.
• Review DNS settings on the client and server.
• Consider using a stable DNS or not routing DNS through VPN if not needed.

Maintenance tips

• Keep a rollback plan: Save the working server and client config before updates.
• Document changes: Maintain a quick reference of keys, endpoints, and IP ranges.
• Rotate keys periodically: A simple security hygiene step.
• Test with a mobile device: Regularly test from outside your home network to ensure reliability.

Final recommendation

If your goal is secure, fast, and straightforward remote access to Home Assistant, WireGuard is an excellent choice. Start with a containerized deployment for clean separation and easier maintenance, especially on Home Assistant OS or supervised environments. Create a single server instance with a couple of well-scoped clients, implement sensible AllowedIPs, and harden your firewall. As you grow, you can add more peers, or even run WireGuard on a dedicated device to handle multiple sites or a broader network.

With careful planning, a WireGuard setup will give you reliable, private access to Home Assistant from anywhere, while keeping your smart home ecosystem secure and responsive.