Secure Remote Access to Home Assistant with WireGuard

Why Secure Remote Access Matters

Accessing your Home Assistant instance when you're away from home is often necessary for monitoring, control, and automation management. While solutions like Home Assistant Cloud (Nabu Casa) offer a convenient, managed service, and simple port forwarding might seem appealing, both have potential drawbacks. Port forwarding opens a door directly from the internet to your Home Assistant, significantly increasing your attack surface and exposing it to potential vulnerabilities. Home Assistant Cloud is a subscription service.

A highly recommended alternative for secure and private remote access is setting up a Virtual Private Network (VPN). WireGuard is a modern, fast, and secure VPN protocol that's relatively simple to configure and widely supported. Running a WireGuard server within your home network allows you to securely connect your devices as if they were local, without exposing Home Assistant directly to the public internet.

What is WireGuard?

WireGuard is a simple, fast, and secure VPN protocol that utilizes state-of-the-art cryptography. Compared to older protocols like OpenVPN or IPsec, it has a significantly smaller codebase, making it easier to audit and less prone to security flaws. Its performance is generally superior due to its streamlined design and reliance on modern kernel-space implementations.

In the context of Home Assistant, you can run a WireGuard server either directly on the Home Assistant machine (via an add-on or Docker) or on another device within your network (like a router or a dedicated VPN server). Your mobile phone, laptop, or other remote devices act as clients, connecting to this server to establish a secure tunnel back into your home network.

Setting Up WireGuard as a Home Assistant Add-on

The easiest way to run a WireGuard server if you're using Home Assistant OS or Supervised is via the official add-on available in the add-on store.

Installation Steps:

1. Navigate to Settings -> Add-ons in your Home Assistant sidebar.
2. Click on the Add-on Store button (bottom right).
3. Search for WireGuard.
4. Click on the WireGuard add-on and then click Install.

Configuration:

Once installed, do not start the add-on immediately. First, you need to configure it.

1. Go to the Configuration tab of the WireGuard add-on.
2. Interface Configuration:
   • host: Your home's public IP address or a domain name pointing to it (dynamic DNS is recommended if your IP changes). This is what clients will connect to.
   • addresses: The IP address range that will be assigned to the WireGuard interface on the server and clients. Choose a private range that doesn't conflict with your existing home network (e.g., 192.168.200.1/24). The /24 creates a subnet for your VPN clients. The server will typically take the first IP in the range (e.g., 192.168.200.1).
   • dns: DNS server(s) that clients will use when connected to the VPN. Using your router's IP or a public DNS like 1.1.1.1 or 8.8.8.8 is common. If you use your router's IP and it also handles local DNS (like for .local domains), clients might resolve local hostnames.
   • listen_port: The UDP port WireGuard will listen on. The default is 51820, but you can change it. Make sure this port is forwarded from your router's public IP to the Home Assistant instance's local IP.
   • private_key: Leave blank initially. The add-on will generate one on first start.
   • public_key: Leave blank initially. The add-on will generate one on first start from the private key.
3. Peer Configuration: This is where you define each client device that will connect.
   • Click Add Peer for each device (phone, laptop, etc.).
   • name: A descriptive name for the client (e.g., my_phone, my_laptop).
   • allowed_ips: The IP address from the VPN subnet that will be assigned to this specific client (e.g., 192.168.200.2/32 for the first client, 192.168.200.3/32 for the second, etc. The /32 indicates a single IP address). You can also add your home network's subnet here (e.g., 192.168.1.0/24) if you want the client to be able to reach all devices on your home network, not just Home Assistant. This is usually desired.
   • public_key: Leave blank initially. The add-on will generate a key pair for this peer on first start. You will get the client's private key and the server's public key needed for the client configuration.

Example Configuration Snippet (YAML format):

server:
  host: your_public_ip_or_domain.duckdns.org
  addresses:
    - 192.168.200.1/24
  dns:
    - 8.8.8.8
  listen_port: 51820
peers:
  - name: my_phone
    allowed_ips:
      - 192.168.200.2/32
      - 192.168.1.0/24 # Example: allows access to your main network
  - name: my_laptop
    allowed_ips:
      - 192.168.200.3/32
      - 192.168.1.0/24

After configuring, save the settings.

Starting the Add-on and Obtaining Client Configurations

1. Go back to the Info tab of the WireGuard add-on.
2. Start the add-on.
3. Check the Logs tab to ensure it started without errors. It should generate the server's public key and the key pairs for each defined peer.
4. Go back to the Configuration tab. The public keys for the server and peers should now be filled in.
5. For each peer, the add-on provides a configuration that you need to get to your client device. This is often presented as a QR code or a downloadable configuration file. Look for instructions on how to retrieve this in the add-on documentation or logs. Typically, you'll find an option in the add-on's Web UI (if available) or logs to view or download the client configs.

Client Setup

Install the WireGuard application on your client device (available for Windows, macOS, Linux, Android, iOS).

In the WireGuard client app:

1. Add a new tunnel/connection.
2. Choose to import from file or scan a QR code, using the configuration generated by the Home Assistant add-on for that specific peer.
3. The client configuration will contain:
• PrivateKey: The client's private key (generated by the add-on).
• Address: The VPN IP assigned to this client (e.g., 192.168.200.2/32).
• DNS: The DNS server(s) you specified in the add-on config.
• PublicKey: The server's public key.
• Endpoint: Your home's public IP/domain and the WireGuard port (e.g., your_public_ip:51820).
• AllowedIPs: This should list the subnets you want the client to route through the VPN. This must include the VPN subnet itself (e.g., 192.168.200.0/24) and usually your home network subnet (e.g., 192.168.1.0/24). Setting this to 0.0.0.0/0 will route all traffic through the VPN, effectively masking your remote IP (useful for privacy, but might consume more home bandwidth).
4. Save the tunnel configuration.
5. Activate the tunnel when you want to connect remotely.

Accessing Home Assistant Over the VPN

Once your client device is connected to the WireGuard VPN, it is effectively part of your home network from a routing perspective (for the IP ranges defined in AllowedIPs). You can now access your Home Assistant instance using its local IP address or local hostname (if your DNS is configured correctly) in your browser or companion app, just as if you were home.

For example, instead of using https://your_public_ip:8123 or https://your_domain.duckdns.org:8123, you would use http://192.168.1.100:8123 (replacing 192.168.1.100 with your Home Assistant's local IP).

Best Practices for Reliability and Security

• Use a Strong Public IP/Domain: Ensure your host setting is correct and reliable (e.g., a stable public IP or a properly configured dynamic DNS).
• Port Forwarding: Only forward the specific UDP port you configured for WireGuard (default 51820) from your router to your Home Assistant's local IP. Avoid forwarding port 8123 or any other Home Assistant ports directly.
• Limit AllowedIPs: In the client configuration, set AllowedIPs to only the subnets you need to access (the VPN subnet and your home network subnet). Avoid 0.0.0.0/0 unless you intend to route all traffic through your home.
• Unique Keys Per Peer: The add-on handles this automatically, but ensure each client has its own unique key pair.
• Keep Add-on Updated: Regularly update the WireGuard add-on to benefit from bug fixes and security patches.
• Restart After Network Changes: If you change your home network subnet or Home Assistant's IP, you might need to update the WireGuard configuration and restart the add-on/clients.
• Firewall Rules: If you have a firewall on your Home Assistant machine or network, ensure it allows UDP traffic on the WireGuard port.

Troubleshooting

• Cannot Connect: Double-check your router's port forwarding rule. Verify the public IP/domain name in the client config is correct and reachable. Check the WireGuard add-on logs for errors. Ensure the client's AllowedIPs is configured correctly.
• Connected but Cannot Reach HA: Ensure the client's AllowedIPs includes your Home Assistant's local subnet (e.g., 192.168.1.0/24). Verify Home Assistant's local IP address. Check firewall rules.
• Slow Connection: Could be related to internet speed (upload speed at home, download speed remotely) or configuration issues.

Conclusion

Using WireGuard for remote access provides a secure, private, and high-performance way to connect to your Home Assistant instance without exposing it directly to the internet. While it requires a bit more initial setup than some alternatives, the enhanced security and flexibility make it a worthwhile solution for any Home Assistant user concerned about protecting their smart home ecosystem.