ESPHome

Last reviewed Aug 26, 2026 · 1,004 words

ESPHome is not a service you run; it is a compiler you host. The container on port 6052 is a build farm with a device list attached, and the product is a firmware binary that runs on a $5 ESP32 and talks to Home Assistant directly. Once a device is flashed, the ESPHome container can be switched off for months and every sensor keeps reporting. So size the machine for compile jobs, not for uptime: the catalogue's 512 MB minimum gets you through a build, an x86 mini-PC gets you through it in under a minute, and a Raspberry Pi 4 gets you through it eventually.

What the dashboard actually does all day

It stores one YAML file per device in /config, compiles it with PlatformIO into C++ firmware, flashes the result over USB or over the air, and tails the device's log over the network. The first compile downloads roughly 1 GB of toolchain and takes several minutes; later builds of the same board reuse it and take 30 to 90 seconds on a modern CPU. That toolchain cache is why you mount /config persistently and why a container restart with a fresh volume feels slow again.

services:
  esphome:
    image: ghcr.io/esphome/esphome:latest
    network_mode: host
    privileged: true
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped

Host networking is needed for mDNS, which is how the dashboard finds devices for OTA and log streaming; privileged is the blunt way to pass a USB serial port through for the first flash, and you can drop it once every board is on Wi-Fi. If you run Home Assistant OS, the same thing is an add-on and you never think about this file.

A device is 30 lines of YAML and one USB cable

esphome:
  name: hallway-sensor

esp32:
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

logger:

sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Hallway Temperature"
    humidity:
      name: "Hallway Humidity"
    update_interval: 60s

No code appears anywhere in that file, and the component library behind it covers hundreds of sensors, displays, relays, LED strips, climate controllers and radios. When you do need logic, a lambda: block accepts a few lines of C++ inline, which is how the corner cases get handled without leaving YAML. The !secret references pull from secrets.yaml in the same directory, so the device files can go into git.

The first flash is USB and every later one is over the air. Plug the board into the machine running the dashboard, or into your laptop and use the browser-based installer at web.esphome.io, and flash once. From then on the ota: block means every change is compiled and pushed over Wi-Fi in about a minute, and a failed update falls back to the previous firmware rather than bricking anything. Boards in the wall, in the garden or in a ceiling void never see a cable again. Batteries are the one caveat: a deep-sleeping sensor is only reachable for OTA during the seconds it is awake, and ESPHome has a documented pattern for holding it awake on demand.

Home Assistant sees it in seconds, with no MQTT in between

The api: block is ESPHome's native protocol, encrypted with the key you set, and Home Assistant discovers the device on the LAN and offers to add it. Every entity in the YAML appears with its name, unit and device class, and state updates are pushed rather than polled. The single most popular thing to build with this is a Bluetooth proxy: add esp32_ble_tracker: and bluetooth_proxy: to a bare board and Home Assistant gains a BLE receiver in that room for the price of a coffee. The other is replacing cloud-bound plugs and bulbs. Many Shelly relays, Athom's pre-flashed devices and Home Assistant's own Voice Preview Edition run ESPHome, so the ecosystem is not only DIY. If you are in your first weeks with the platform, Home Assistant's first month covers where devices like these fit.

Against Tasmota and Zigbee

Tasmota is precompiled firmware configured through a web page and speaks MQTT, which makes it the faster path for an off-the-shelf plug you just want to de-cloud, and it needs no build machine. ESPHome compiles a firmware per device, integrates more tightly with Home Assistant, supports far more components, and lets you do things Tasmota cannot express. For sensors that need to run on a battery for a year, neither is the answer: a Zigbee device through Zigbee2MQTT will outlast any Wi-Fi board. ESPHome is for the mains-powered, the custom and the unusual, and the rest of the home automation category fills in the gaps.

Keep the versions honest

Each firmware embeds the ESPHome version that compiled it, and updating the dashboard container means every device is one version behind until you press "Update all". That is harmless for months and then, once a year or so, a breaking change lands (the ota: platform syntax above is one such change from the past) and 15 devices want editing. Pin the image tag, read the release notes before bumping, and back up /config because it contains every device's identity, secrets and the build cache.

What I'd do

Run the container on an x86 box with /config in git and secrets.yaml excluded, flash the first ESP32 as a Bluetooth proxy to see the whole loop work in 20 minutes, then move on to a temperature sensor and a relay. Use Tasmota for the cheap plug you cannot be bothered to compile for, and Zigbee for anything on a battery. ESPHome is the tool that turns a drawer of $5 boards into named entities in Home Assistant with no cloud and no code, and the build machine is the only infrastructure it ever asks for.