ESPHome 2026.5.0 Device Builder beta in docker?

koying · May 22, 2026, 11:10am

I don't see a way to run the beta device builder of 2026.5.0 out of HAOS, in plain docker, documented.

Did I miss it? Did someone mange, already?

Thanks

cromelex · May 22, 2026, 11:13am

Have been looking for the same but I do not see anything in the documentation.

mattjacobson6 · May 22, 2026, 12:27pm

Was really excited about this update... Was hoping for an easy self-contained docker solution like ESPHome-Fleet (GitHub - weirded/fleet-for-esphome: Fleet for ESPHome — Home Assistant add-on for managing fleets of ESPHome devices: distributed compile workers, version pinning, scheduled upgrades, fleet tags, and config history. · GitHub) - but it's not quite there yet.

As of now, been running the base ESPHome in HAOS + ESPHome-Desktop as a remote build server on a Windows box.

Krivatri · May 22, 2026, 12:48pm

I have a builder running in a docker container for testing purposes and use this to change versions:

docker stop esphome && \
docker rm esphome && \
docker run -d \
  --name esphome \
  -v /home/krivatri/ha-stack/esphome-config:/config \
  -p 6052:6052 \
  ghcr.io/esphome/esphome:2026.5.0b1

you'll need to change the pad to yours

koying · May 22, 2026, 12:51pm

But 2026.5.0b1 is beta1, isn't it?
Was the beta builder enabled by default there?

Krivatri · May 22, 2026, 12:52pm

yes this is a beta version, I tried it on a fresh container install and worked out of the box.

Krivatri · May 22, 2026, 12:58pm

to see all available versions:

curl -s https://api.github.com/repos/esphome/esphome/releases | grep '"tag_name"'

Arh · May 22, 2026, 2:06pm

Are you talking about the new ui for builder? If so it is not enabled yet in docker. There is way which is explained in the discord channel, but don't ask me anymore as it is above my ability

koying · May 22, 2026, 2:39pm

Ok, thanks.
If you happen to have the discord discussion handy, it would be nice to paste it here.
I never considered a chatroom like something useful for support or knowledge management

Arh · May 22, 2026, 2:47pm

unfortunately as much as i dislike discord, it is the best place to get the latest info, and ask the people who can help some questions.

but here you are.

Container Image Users

To use the new ESPHome Device Builder with the standard container image that we provide, alter the entrypoint of your container. uv pip install esphome-device-builder && exec esphome-device-builder /config

koying · May 22, 2026, 2:59pm

Thanks!

In details:

Add (to docker-compose.yaml):

        volumes:
            - ./entrypoint.sh:/entrypoint.sh:ro

with entrypoint.sh being

#!/usr/bin/env bash

# If /cache is mounted, use that as PIO's coredir
# otherwise use path in /config (so that PIO packages aren't downloaded on each compile)

if [[ -d /cache ]]; then
    pio_cache_base=/cache/platformio
else
    pio_cache_base=/config/.esphome/platformio
fi

if [[ ! -d "${pio_cache_base}" ]]; then
    echo "Creating cache directory ${pio_cache_base}"
    echo "You can change this behavior by mounting a directory to the container's /cache directory."
    mkdir -p "${pio_cache_base}"
fi

# we can't set core_dir, because the settings file is stored in `core_dir/appstate.json`
# setting `core_dir` would therefore prevent pio from accessing
export PLATFORMIO_PLATFORMS_DIR="${pio_cache_base}/platforms"
export PLATFORMIO_PACKAGES_DIR="${pio_cache_base}/packages"
export PLATFORMIO_CACHE_DIR="${pio_cache_base}/cache"

# If /build is mounted, use that as the build path
# otherwise use path in /config (so that builds aren't lost on container restart)
if [[ -d /build ]]; then
    export ESPHOME_BUILD_PATH=/build
fi

uv pip install esphome-device-builder && exec esphome-device-builder /config
# exec esphome "$@"

pOpY · May 23, 2026, 3:06pm

thx, working as expected.
Building now on my unraid i5-14500T instead of an old N100

Cadster · June 6, 2026, 9:20pm

Thanks for your solution for docker.
I tried this, but get this response:

 ✔ Container esphome  Created                                              0.0s
Attaching to esphome
esphome  | /usr/bin/env: ‘bash\r’: No such file or directory
esphome  | /usr/bin/env: use -[v]S to pass options in shebang lines
esphome exited with code 0
[/share/Container/esphome] #

Nevermind solved it with:

sed $'s/\r$//' ./entrypoint.sh > ./entrypoint.sh.Unix.sh

Found here.

cameron · June 7, 2026, 6:06am

Hi how did you include this in Unraid?

Do you have Docker Compose Manager or the basic way of installing apps?

pOpY · June 7, 2026, 9:27am

Basic way of installing apps with the default container “ghcr.io/esphome/esphome:stable“.

You have to create and specify the entrypoint.sh from above. This just loads the new builder and starts it in the container.

vit50411 · June 7, 2026, 9:44am

There is an issue with authentication in new builder, it uses new environment variables, but strange it worked only for desktop browser and did not work for mobile.

I had to use basic authentication through nginx to expose the ESPHome WebUI to Internet.

JFYI.

cameron · June 7, 2026, 9:47am

Sorry i am a bit of a newby on Unraid. i have installed the app from where you suggested.
but not sure how to add the volume with the .sh file.

pOpY · June 7, 2026, 11:21am

Here is an guide (yes, AI generated - so take it a with a bit grain of salt ).
But you should get the needed infos.

How to Set Up an ESPHome Distributed Build Server on unRAID (Device Builder Beta)

With the introduction of the new ESPHome Device Builder (replacing the old "Fleet for ESPHome" worker system), you can easily offload heavy compiling tasks from your Home Assistant server to your unRAID server.

Instead of a traditional background worker, the new system runs the Device Builder dashboard on unRAID and pairs it with your Home Assistant instance. To get this running using the official docker image, we need to inject a custom entrypoint.sh script to start the new builder. Here is how to set it up:

Step 1: Prepare the entrypoint.sh Script

By default, the official ESPHome Docker image runs a script called /entrypoint.sh on startup. We will override this file by mounting our own script from unRAID, which installs and launches the new Device Builder.

Open the unRAID Terminal (the >_ icon in the top right corner).
Create the appdata folder for the new build server:

mkdir -p /mnt/user/appdata/esphome-build-server/config

Create the bash script:

nano /mnt/user/appdata/esphome-build-server/entrypoint.sh

Paste the following code (this handles PlatformIO caches correctly and starts the new builder):

#!/usr/bin/env bash

# Define PlatformIO cache paths so packages aren't lost during updates
if [[ -d /cache ]]; then
    pio_cache_base=/cache/platformio
else
    pio_cache_base=/config/.esphome/platformio
fi

if [[ ! -d "${pio_cache_base}" ]]; then
    mkdir -p "${pio_cache_base}"
fi

export PLATFORMIO_PLATFORMS_DIR="${pio_cache_base}/platforms"
export PLATFORMIO_PACKAGES_DIR="${pio_cache_base}/packages"
export PLATFORMIO_CACHE_DIR="${pio_cache_base}/cache"

if [[ -d /build ]]; then
    export ESPHOME_BUILD_PATH=/build
fi

# Install the new Device Builder via uv and execute it instead of the standard dashboard
uv pip install esphome-device-builder && exec esphome-device-builder /config

Save the file (Ctrl+O, Enter) and exit the editor (Ctrl+X).
Make the script executable:

chmod +x /mnt/user/appdata/esphome-build-server/entrypoint.sh

Step 2: Create the unRAID Docker Container

Go to your unRAID Docker tab and click "Add Container" at the bottom.
Fill in the basic configuration:
- Name: esphome-build-server (or whatever you prefer)
- Repository: ghcr.io/esphome/esphome:stable (or :latest if you are using a stable release that already includes the new builder)
- Network Type: Host (Crucial: This is required for mDNS so your Home Assistant server can discover the unRAID server on your local network).
Click "Add another Path, Port..." to map the config directory:
- Config Type: Path
- Name: Config
- Container Path: /config
- Host Path: /mnt/user/appdata/esphome-build-server/config/
- Access Mode: Read/Write
Click "Add another Path, Port..." again to map our custom script over the default one:
- Config Type: Path
- Name: Entrypoint Override
- Container Path: /entrypoint.sh
- Host Path: /mnt/user/appdata/esphome-build-server/entrypoint.sh
- Access Mode: Read Only
Click Apply. The container will start, install the new frontend via uv pip in the background, and spin up on port 6052.

Step 3: Pair Home Assistant with unRAID

The new system relies on a handshake process (similar to Bluetooth pairing) to establish trust between the instances.

Open the ESPHome Dashboard of your unRAID server in your browser (e.g., http://<unRAID-IP>:6052).
Navigate to Settings -> Build server -> Pairing requests.

Important: Leave this specific page open! If you close it, incoming pairing requests will be automatically blocked for security reasons.
In a new browser tab, open the ESPHome Dashboard of your Home Assistant.
Navigate to Settings -> Send builds -> Known dashboards.
Your unRAID server should automatically appear in this list via mDNS. Click Pair next to it.
Both screens will now display an emoji fingerprint (a grid of emojis). Verify that the emojis match on both screens.
Switch back to your unRAID dashboard tab and click Accept.

That's it! The pairing is saved persistently. Your Home Assistant instance will now automatically delegate heavy firmware compilation tasks to your unRAID server.

cameron · June 7, 2026, 6:49pm

Wow thank you very much excellent guide I will try this later when am home.
Hope this helps others with Unraid.

pOpY · June 7, 2026, 8:46pm

You're welcome.
Saved me a ton of time already, and there are just a few versions of esphome I have built/flashed for my devices.

Just let us know, if you successfully rocking the distributed build feature.