Setting up a pure remote build server in docker compose

ESPHome
1

As I just went through the trouble of figuring out the details of this and couldn’t find any clear documentation on it, here is how I set up a remote build server in docker compose using the official image:

services:
  esphome:
    restart: unless-stopped
    container_name: esphome
    image: ghcr.io/esphome/esphome
    ports:
      - 6055:6055 #RemoteBuild
      #- 6052:6052 #WebUI
    volumes:
      - config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - ESPHOME_USERNAME=esphome_remote_builder
      - ESPHOME_PASSWORD=<password>
    command:
      - dashboard
      - /config
      - --remote-build-only
      - --allow-pairing-source
      - <IP of main ESPHome instance>

volumes:
  config: null

This requires 2026-07 in order for the remote build only flag to work correctly and ask for a pairing key in “Send build > Pair with a build server”

I really like the feature and was kinda sad to only now discover it. Or maybe it just is entirely new, IDK.

Also the official documentation still uses USERNAME & PASSWORD rather than ESPHOME_USERNAME

One limitation I have found is that automatic timezone detection uses “Etc/UTC” from the docker image rather than from the build host.

2 Likes