ESPHome Device Builder Dashboard

project board

first, and join the Discord channel

for live discussion.

A new dashboard for ESPHome — a guided interface for composing device configs, exploring components and boards, managing automations, and pushing firmware updates.

Try it

Running it behind a reverse proxy?

Skip ahead to Behind a reverse proxy

for the nginx / --trusted-domains setup.

The dashboard runs by default in the official Home Assistant add-on (as of ESPHome 2026.6.0) and ships as an opt-in backend in ESPHome Desktop. Pick the path that matches how you run ESPHome today:

Home Assistant add-on

As of ESPHome 2026.6.0, the ESPHome add-on (Stable, Beta, or Dev) runs the Device Builder by default; install or update the add-on and open it from the Home Assistant sidebar. The Device Builder ships inside the add-on and serves the dashboard over Home Assistant Ingress, so there's no toggle to set.

The add-on's data layout stays the same (/config/esphome/ for YAMLs, /data/ for build artefacts) so updating doesn't move or duplicate any state.

ESPHome Desktop (macOS / Windows / Linux)

Install ESPHome Desktop v0.7.0 or later, then click the system-tray icon and pick **Backend → ESPHome Builder (stable) or ESPHome Builder (beta)**. The daemon restarts under the chosen backend and the tray badge updates to reflect which one is running. Switch back to Classic ESPHome Dashboard the same way.

Windows build location. On native Windows the dashboard puts its

build tree and PlatformIO toolchain under a short, space-free root,

C:\esphb\\ (where is the first 8 characters of the

dashboard id; per-dashboard roots nest under one C:\esphb folder),

rather than under your config / profile dir, so deep ESP-IDF build paths

stay under the 260-char MAX_PATH limit and clear of spaces in your

profile name (C:\Users\First Last\…). The native ESP-IDF toolchain

lives at C:\esphb\idf, shared by all dashboards on the machine: its

compiler probes paths reaching ~245 characters below that folder, so the

prefix must stay very short to clear MAX_PATH. Nothing here is removed

on uninstall, so a reinstall keeps the warm toolchain; delete C:\esphb

by hand to reclaim the disk space. This applies only to native Windows;

running in a Linux Docker container (or the HA add-on) uses the normal

data dir.

Standalone (PyPI)

For developers, headless servers, or anyone running outside the add-on / Desktop / Docker shapes:

python -m venv .venv && source .venv/bin/activate
pip install 'esphome-device-builder[esphome]'
esphome-device-builder ~/esphome-configs

The [esphome] extra pulls in the upstream esphome package the dashboard needs to compile, flash, and discover devices. The HA add-on / Desktop builds ship esphome separately, so the bare pip install esphome-device-builder (no extra) is for those contexts only.

For the beta channel, pass --pre to opt the resolver into prereleases — e.g. pip install --pre 'esphome-device-builder[esphome]' for a fresh install, or pip install --upgrade --pre 'esphome-device-builder[esphome]' to pull the newest beta on top of an existing install. --pre only opts the current command into prereleases; rerun the upgrade command to refresh.

The server starts on http://localhost:6052. Run with --help for the full flag set.

python -m venv .venv && source .venv/bin/activate
Replace <version> with a release tag (X.Y.Z stable, X.Y.ZbN beta).
`[esphome] @ <url> carries the optional extra through the

direct-URL install so the dashboard finds esphome at startup.
pip install "esphome-device-builder[esphome] @ https://github.com/esphome/device-builder/releases/download/<version>/esphome_device_builder-<version>-py3-none-any.whl"
esphome-device-builder ~/esphome-configs

git clone https://github.com/esphome/device-builder
cd device-builder
script/setup
source .venv/bin/activate
esphome-device-builder ./configs --log-level debug --dev

As of ESPHome 2026.6.0, the standard ghcr.io/esphome/esphome image bundles the Device Builder and runs it as the dashboard; there's no env var or extra setup. The image's default command (dashboard /config) launches esphome-device-builder against your config dir:

docker run -p 6052:6052 -v "$PWD":/config ghcr.io/esphome/esphome

The dashboard serves /config on port 6052. Every other subcommand (compile, run, logs, ...) still runs the classic esphome CLI, so direct command-line use is unchanged.

The three install paths each handle network reach and the auth gate differently. The Home Assistant add-on runs ingress-only with no password under the new preview, so access goes through the HA sidebar and port 6052 stays unbound; ESPHome Desktop binds only to 127.0.0.1, so there's nothing on the LAN to authenticate against in the first place; the standalone PyPI install binds 0.0.0.0:6052, is LAN-reachable by default, and prints a startup banner warning that there is no auth gate until you configure one.

On the Home Assistant add-on, the dashboard is reached through Home Assistant itself: you open it from the HA sidebar in your browser, and the Home Assistant Companion App opens it the same way. Both paths come in over Home Assistant Ingress, so the dashboard is already protected by your Home Assistant login; there's no separate username or password to configure for the add-on, and port 6052 stays unbound to keep the dashboard off the LAN by default.

This is the supported way to use the add-on. The classic dashboard also let you forward your Home Assistant username and password through the supervisor /auth endpoint to gate an exposed port 6052; that endpoint has no rate limiting or lockout, so it turned the dashboard into an open brute-force target against every account on the Home Assistant instance, and we don't carry that path forward (see device-builder issue #85).

The classic dashboard's other option, "Disable external authentication" (leave_front_door_open), is honored. With it on and port 6052 mapped in the add-on's Network options, the dashboard binds the port on the LAN with no authentication at all, for example so the VS Code ESPHome plugin can reach it. Both opt-ins are required, matching the classic add-on; the dashboard logs a loud banner because this leaves the dashboard wide open to anyone on your network. Turn the option off, or unmap the port, for ingress-only access. For password-gated LAN access instead, run the standalone PyPI install on the same network with its own dashboard-managed password.

export ESPHOME_USERNAME=admin
export ESPHOME_PASSWORD='<pick a strong password>'
esphome-device-builder ~/esphome-configs

Both values must be set together; setting only one fails the credential check at startup. The env var names are ESPHOME_USERNAME and ESPHOME_PASSWORD, not the legacy dashboard's bare USERNAME / PASSWORD, because the bare names collide with the OS-supplied $USERNAME on Windows and most login shells.

The --username / --password CLI flags are still accepted for parity with the legacy dashboard's CLI, but please avoid --password in particular: command-line arguments show up in process listings (ps output on Linux / macOS, Task Manager on Windows, plus /proc//cmdline on Linux unless hidepid is locked down), so another local user on the host can usually read the dashboard password. Use the env vars instead (or a .env / systemd EnvironmentFile= that's only readable by the dashboard's user).

The dashboard rejects browser WebSocket handshakes whose Origin doesn't match the server's Host header. When a proxy fronts the dashboard under a different hostname (nginx, Caddy, Traefik, nginx-proxy-manager, ...), the browser sends Origin: https://dashboard.example.com but the upstream sees Host: localhost:6052 — those don't match and the handshake gets 403'd. Same gate, same fix, regardless of whether the dashboard has a password set; it applies to every public-site deployment.

location / {
       proxy_pass http://localhost:6052;
       proxy_http_version 1.1;
       proxy_set_header Host $host;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_read_timeout 86400s;  # keep WS connections alive
   }

With proxy_set_header Host $host;, the dashboard sees Host: dashboard.example.com (the hostname the browser asked for), Origin matches, and the handshake passes.

esphome-device-builder /config \
     --trusted-domains dashboard.example.com,proxy.example.com

Or via the env var ($ESPHOME_TRUSTED_DOMAINS, same name the legacy dashboard used):

ESPHOME_TRUSTED_DOMAINS=dashboard.example.com esphome-device-builder /config

The list is comma-separated, case-insensitive, port-tolerant. IPv6 addresses work bracketed or bare (::1 and [::1] both match). Use * as the only entry to disable the Host restriction entirely (handy when the Host varies per request — but then operator-supplied auth becomes the only gate).

Listening on a UNIX socket (--socket)

esphome-device-builder /config --socket /run/esphome/dashboard.sock

--host and --port are then ignored for binding but still feed the dashboard's mDNS advertisement, so point them at where the proxy ultimately listens.

The socket file is created with the default permissions your process umask yields; the dashboard does not manage its mode. **Put the socket in a directory readable only by the dashboard and the proxy** (for example a dedicated /run/esphome/ owned by the dashboard user with the proxy's user granted access via group or ACL) — directory permissions are the reliable access control here, since socket-file mode bits are not enforced on every platform. Anything that can connect to the socket gets the same surface a TCP client would, gated by the same auth and Origin/Host checks.

proxy_pass http://unix:/run/esphome/dashboard.sock;

If you run the standalone dashboard behind an HTTP reverse proxy (nginx, Traefik, Caddy, nginx-proxy-manager, …) at a subpath (for example https://example.com/esphome/), the proxy must forward the mount prefix to the backend using the X-Forwarded-Prefix header so the server can render the SPA's correctly per request. The header value does not need a trailing slash — the server normalises the prefix internally.

location /esphome/ {
    proxy_pass http://localhost:6052/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /esphome;
    proxy_read_timeout 86400s;
}

CLI tools and the Home Assistant integration omit Origin entirely, so they're never affected — the gate is browser-only. The HA Ingress site (the --ingress-host listener the supervisor proxies to) skips both checks because the supervisor handles auth upstream. It binds only loopback plus the supervisor gateway (127.0.0.1 + 172.30.32.1), never all interfaces, and a peer guard rejects any source other than loopback or the supervisor (172.30.32.2) — so the no-auth site is never reachable from the LAN or another add-on even though the add-on runs host-network. This matches the legacy add-on's nginx allow/deny ACL.

If a dashboard you expected to show up doesn't appear in Known dashboards, run esphome-device-builder-discover on the sending host before troubleshooting the UI. The CLI browses the same mDNS service the dashboard does and prints what it sees, including the receiver's peer-link port and identity fingerprint:

Status |Name |Address:Port        |Server   |ESPHome   |RB Port |Pin (sha256)
-------+-----+--------------------+---------+----------+--------+--------------
ONLINE |mac  |192.168.1.75:6052   |0.1.0b39 |2026.4.5  |6055    |3968ef58…

After pairing, clicking Install on a device automatically routes through the paired receiver as soon as one is online. The scheduler prefers an idle receiver, but if every paired receiver is busy it queues the install behind the in-flight work rather than silently building locally; that keeps the toolchain warm and the artefacts coming from one place. The install dialog shows a "Building on {receiver}" sub-line so you can see which side is doing the work. You can override per-install via the **Build locally instead** link in the install dialog, or disable auto-routing entirely from **Settings → Send builds → Auto-route installs to remote build**.

If the dashboards are on different subnets, or if either side is running as the Home Assistant add-on (which doesn't advertise itself on mDNS), use the Pair with another dashboard section beneath Known dashboards. Open the receiving dashboard's Pairing requests screen first (same prerequisite as the discovered-dashboard flow above), then click **Pair with a build server** on the sending side, type the receiver's hostname and port, and submit; the pairing flow runs identically to the discovered-dashboard case from there. The peer-link is a WebSocket served at /remote-build/peer-link over TCP port 6055 by default; if a reverse proxy or firewall sits between the two dashboards it needs to allow WebSocket upgrades on that path. The wire is Noise-encrypted regardless of how you reach it, and the emoji-fingerprint comparison still gates pairing the same way.

Headless build server (--remote-build-only)

esphome-device-builder --remote-build-only /var/lib/esphome-builder

📌 🍎 🐙 ☎️ 🚀 🌏 🐰
   ...
   8MC5-KAXV-NN6N-PWAA

To pair, on your main dashboard open **Settings → Send builds → Pair with a build server**, enter the headless server's hostname and peer-link port (default 6055), and Continue. Check the emoji fingerprint matches the console; the dialog detects it's a headless server and shows a pairing-key field — enter the printed key and send. That's it — the server pairs and starts serving builds. Re-run the server if you don't pair within the window it prints. --allow-pairing-source optionally restricts which address may pair.

Receiver / sender ESPHome-version drift is governed by a version-match policy on the sending side (Settings → Send builds): any, release (major version must match), exact, or exact_required — the last refuses to build rather than falling back to a local compile when no version-compatible receiver is paired.

The dashboard keeps a local, git-backed history of your device configs. Every change to a YAML in the config directory is committed automatically shortly after it lands on disk, whether the edit came from the dashboard, an external editor, a script, or an AI agent working in the directory. The history powers viewing, diffing, and restoring earlier versions of a config, including bringing back a deleted one. Today those are exposed as the version_history/* commands in docs/API.md; a recovery UI in the dashboard is planned. Recording starts now precisely so that when that UI ships, your history is already there.