Skip to content
ESPHome - Smart Home Made Simple 2026.5.0

Host Platform

The host platform allows ESPHome configurations to be compiled and run on a desktop computer. This is known to work on MacOS and Linux. On Windows WSL (Windows Subsystem for Linux) can be used to create a Linux environment that will run ESPHome.

The only configuration required is to optionally set a dummy MAC address that will be used to identify the configuration to Home Assistant (the native MAC address is not readily available.)

NOTE

HA will not automatically discover an ESPHome instance running on host using mDNS, and you will need to add it explicitly using the IP address of your host computer. If HA cannot establish a connection when adding the device manually, the firewall settings of the local host computer may be the cause. The ESPHome API port (6053 ) must be allowed through the firewall. See Api for details.

Many components, especially those interfacing to actual hardware, will not be available when using host. Do not configure wifi - network will automatically be available using the host computer.

# Example configuration entry
host:
  mac_address: "06:35:69:ab:f6:79"

Configuration variables

Section titled “Configuration variables”
  • mac_address (Optional, MAC address): A dummy MAC address to use when communicating with HA.

Build and run

Section titled “Build and run”

The esphome run yourfile.yaml command will compile and automatically run the build file on the host platform.

Over-the-Air Updates

Section titled “Over-the-Air Updates”

The host platform supports OTA updates via the esphome OTA platform on port 8082 (by default). When an OTA upload completes successfully, the new binary is validated (matching ELF on Linux or thin Mach-O on macOS, with the same architecture as the running executable), atomically renamed over the running binary’s path, and the process replaces itself with the new image via execv(). The PID is preserved across the swap, so any supervisor (systemd, a wrapper script, etc.) sees the same process continuing to run.

This is primarily intended for development, integration testing, and CI; the same code path that runs on real microcontrollers can be exercised end-to-end without flashing hardware.

CAUTION

The OTA endpoint can overwrite the running executable. Set an OTA password and either bind the host to a trusted interface only or restrict port 8082 with a firewall rule.

See Also

Section titled “See Also”