home-assistant-addon

What this repository is

This repository is the Home Assistant add-on repository for ESPHome. The README opens by stating exactly that, and then tells readers that the ESPHome source code lives elsewhere, at the esphome repository. That single sentence defines the scope of this project: it is the packaging and distribution piece that runs ESPHome inside Home Assistant, not the application that does the device configuration and firmware building. The README keeps the description short on purpose, because the substance of ESPHome is documented in the main project.

The split between an add-on repository and a source repository is a common pattern in the Home Assistant ecosystem. An add-on repository holds the files needed to install and run a service as a managed container inside Home Assistant, while the source repository holds the program itself. By pointing away from itself for source, this README makes clear that changes to ESPHome behavior belong upstream. A reader who lands here looking to build or modify ESPHome is redirected to the correct place immediately, which avoids confusion about where contributions should go. For someone setting up ESPHome through the Home Assistant supervisor, this is the entry point they install, while the esphome repository remains the codebase they are ultimately running. The brevity of the README is therefore a signpost rather than a manual.

Documentation and where to get help

The README points to the official ESPHome documentation at esphome.io as the place to learn how the tool works. Because this repository is the add-on wrapper, it does not repeat setup guides, command references, or device support lists; instead it sends users to the dedicated documentation site. That keeps a single source of truth for how ESPHome is used, which matters when the main project releases frequently and docs must stay in step with the code.

For problems and ideas, the README routes users to two distinct places. Bugs and operational issues should go to the issue tracker in the esphome repository, not here. Feature requests are handled separately through the esphome organization's discussions, which the README links explicitly. This separation of issues from feature requests is a deliberate support policy: crashes and misbehavior are tracked as issues, while proposals for new behavior are discussed before any code is written. By listing both links up front, the README steers each kind of feedback to the right channel and spares maintainers from triaging mixed reports. The net effect is that this short README acts as a dispatcher, telling each visitor whether they need docs, a bug report, or a feature discussion, and giving the exact URL for each.

How the add-on fits into Home Assistant

As a Home Assistant add-on, this repository exists to make ESPHome available as a managed service inside a Home Assistant installation. Home Assistant add-ons are installed and updated through the supervisor, which handles the container, networking, and lifetime of the service, so the value of an add-on repo is that it packages a tool the user would otherwise have to run and maintain by hand. The README does not enumerate the add-on's configuration options or ingress settings, because those live in the add-on's own definition files and in the upstream documentation.

What the README does tell us is the boundary of responsibility. ESPHome the project is developed at the esphome repository, documented at esphome.io, and supported through its issue tracker and discussions. This repository is the delivery mechanism for the Home Assistant case. A practical takeaway for a reader is that they should install this add-on to run ESPHome from Home Assistant, then rely on the main project for everything else: learning the syntax, reporting faults, and requesting capabilities. In short, treat this repo as the front door to ESPHome on Home Assistant, with the real work happening in the linked repositories. The README's job is finished once that routing is clear, which is why it stays so brief.

Editorial conclusion

This repository is the Home Assistant add-on for ESPHome and is published at github.com/esphome/home-assistant-addon.