Cannot connect to ESPHome device over WireGuard VPN – “Unable to connect to the ESPHome device” error

Third party integrations
1

I’m trying to add my ESP32 device to Home Assistant using its VPN IP address from WireGuard.
However, when I enter the VPN IP as the host address, I get the following error message:

Unable to connect to the ESPHome device. Make sure the device’s YAML configuration includes an `api` section.

image
image615×470 17.3 KB

Here’s what I’ve set up so far:

  • Installed the WireGuard Add-on from the official Home Assistant add-on store
  • The ESP32 is running ESPHome with the built-in WireGuard client enabled
  • I can’t ping to the IP address: 172.27.66.5 from HA server

ESPHome configuration:

esphome:
  name: esp32-new
  friendly_name: esp32_new

esp32:
  board: esp32-c6-devkitc-1
  framework:
    type: esp-idf

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "O11cEw1wr34Y3PjpTOEguGAuaYN2T/PlXsPAxQPlJao="
  # Optimize for local network performance
  reboot_timeout: 15min
  port: 6053

ota:
  - platform: esphome
    password: "c2b598fe7ea9cc3015fe4abddbb55201"

wifi:
  networks:
    - ssid: !secret wifi_ssid
      password: !secret wifi_password
  # Static IP for Phat's home network (192.168.50.x)
  manual_ip:
    static_ip: 192.168.50.36
    gateway: 192.168.50.1
    subnet: 255.255.255.0
    dns1: 192.168.50.1  # Use local router as primary DNS
    dns2: 8.8.8.8       # Fallback to public DNS

  ap:
    ssid: "Esp32-New Fallback Hotspot"
    password: "UC6Dcqcq6gVU"
  
  # For OTA/dashboard to prefer the WireGuard/VPN address when reachable
  use_address: 172.27.66.5
  

captive_portal:

web_server:

time:
  - platform: sntp
    id: sntp_time
    timezone: Asia/Ho_Chi_Minh  # Adjust to your timezone
    servers:
      - 1.vn.pool.ntp.org
      - 2.vn.pool.ntp.org
      - 0.vn.pool.ntp.org
    update_interval: 60s

wireguard:
  address: 172.27.66.5
  private_key: xxx
  peer_endpoint: xxx.duckdns.org
  peer_port: 51820
  peer_public_key: xxx
  peer_allowed_ips:
    - 172.27.66.0/24  # Only route VPN subnet, not all traffic
    - 172.27.66.5/32
    # - 0.0.0.0/0  # Comment out to avoid routing all traffic through VPN
  peer_persistent_keepalive: 5s  # Reduced from 25s for better responsiveness
  netmask: 0.0.0.0
    
switch:
  - platform: gpio
    name: "ESP32 LED"
    pin: GPIO1
    id: led_pin

  - platform: gpio
    name: "ESP32 GPIO8"
    pin: GPIO8
    id: ext_led_pin

WireGuard Add-on Configuration (Home Assistant):

server:
  host: xxx.duckdns.org
  addresses:
    - 172.27.66.1
  dns: []
peers:
  - name: hassio
    addresses:
      - 172.27.66.2
    allowed_ips: []
    client_allowed_ips:
      - 172.27.66.0/24
  - name: remotepc
    public_key: xxx
    addresses:
      - 172.27.66.3
    allowed_ips: []
    client_allowed_ips:
      - 172.27.66.0/24
  - name: remotepc2
    public_key: xxx
    addresses:
      - 172.27.66.4
    allowed_ips: []
    client_allowed_ips:
      - 172.27.66.0/24
  - name: esp32
    addresses:
      - 172.27.66.5
    allowed_ips: []
    client_allowed_ips:
      - 172.27.66.0/24

WireGuard log:

[21:34:32] INFO: Requesting current status from WireGuard...
interface: wg0
  public key: T3AYTGXseMet6ueGOmg7fhMapHItnOgE1G792cSG9Bs=
  private key: (hidden)
  listening port: 51820
peer: e0f6Alw6+Agp/Maf5uE20vQ9q+JN3CyCcnHYoieY7n4=
  endpoint: 192.168.1.1:53207
  allowed ips: 172.27.66.5/32
  latest handshake: 1 minute, 59 seconds ago
  transfer: 19.64 KiB received, 3.94 KiB sent
  persistent keepalive: every 25 seconds
peer: clLKVbwc/M2+fTzFrX+D9TANm5TGaNhV34B54g8N0n4=
  allowed ips: 172.27.66.3/32
  persistent keepalive: every 25 seconds
peer: rroOSh8y7BnwzO6AAYTEbfw3HVqsYspipWQtwEHeDQI=
  allowed ips: 172.27.66.2/32
  persistent keepalive: every 25 seconds
peer: siGErQWl4jnwTRFCfRXrPqDhzhCeFh2pGae1rw0Xu0c=
  allowed ips: 172.27.66.4/32
  persistent keepalive: every 25 seconds

Has anyone successfully connected an ESPHome device through a VPN like this?
Any suggestions on what configuration might be missing or blocking the connection would be greatly appreciated :pray:

1 Like
2

I spent two days on this and finally fixed it, I hope I can help. The root cause is that Home Assistant runs in one container and WireGuard in another, so traffic entering the WireGuard tunnel ( wg0 ) doesn’t automatically reach HA’s container network or your LAN. You must enable IP forwarding and add proper iptables rules on the WireGuard server to allow forwarding and NAT, so packets from VPN clients can reach the HA container (and the LAN) and get replies.

In the WireGuard server config, under “Server” add the following in PostUp:

iptables -t nat -A POSTROUTING -o wg0 -j MASQUERADE; iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT

and in PostDown:

iptables -t nat -D POSTROUTING -o wg0 -j MASQUERADE; iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT

AI suggested me some version of this fix, so try with this o use AI to suggest similar configuration that could be good for your general settings and please update me if this worked for you.