Skip to content

ESPHome Device Builder

Most people don't need this

Your CAST-1 ships ready to use. You only need the ESPHome Device Builder if you want to rename it or make manual edits to its YAML. To just add your CAST-1 to Home Assistant, follow the Getting Started guide.

ESPHome Device Builder is the software that gives you a user interface for editing, compiling, and flashing ESPHome YAML. You'll use it to take control of your CAST-1 and edit its configuration.

Install ESPHome Device Builder

Pick the platform you'll be running ESPHome Device Builder on:

  1. Open desktop.esphome.io and click Download installer under the Windows tab.
  2. Open the installer and click Next then click Next again to start the installation process. Once it shows completed, click Next again then Finish to complete the installation.

You may see Windows prompts during install

  • If Windows shows a blue Windows protected your PC warning, click More info → Run anyway to continue.
  • If Windows Security asks whether to allow public and private networks to access Python, click Allow.
  • If the installer fails or the Device Builder can't compile firmware, install Git for Windows from gitforwindows.org and try again. Future installer builds will bundle this for you.

Once installed, a web browser should launch and navigate to http://localhost:6052/. On first launch, ESPHome Device Builder asks how you will use it. Select Build and manage devices, then select New to ESPHome and click Finish.

  1. Open desktop.esphome.io. The page detects your OS and shows the macOS downloads. Pick the build that matches your chip:

    • Apple Silicon (M1, M2, M3, M4, M5)
    • Intel Mac

  2. Open the .dmg and drag ESPHome Builder into your Applications folder. Launch it from Applications or Spotlight.

    • On first launch, macOS may block the app with a Gatekeeper warning. If that happens, right-click the app in Applications and choose Open, then click Open in the confirmation dialog. After the first launch, double-click will work normally.

Once installed, a web browser should launch and navigate to http://localhost:6052/. On first launch, ESPHome Device Builder asks how you will use it. Select Build and manage devices, then select New to ESPHome and click Finish.

The ESPHome Device Builder runs as a Home Assistant app served right inside your existing HA dashboard. This is the easiest option if you already run Home Assistant OS or a supervised install.

Method 1

To add the ESPHome Device Builder to your Home Assistant instance, use this My button:

Open your Home Assistant instance and start setting up a new app.

Method 2

  1. In Home Assistant, open Settings → Apps → App Store.
  2. Search for ESPHome Device Builder and click Install.
  3. Once installed, click Start, then Open Web UI. The Device Builder will open inside your Home Assistant dashboard.

  1. Open desktop.esphome.io. The page opens on the Linux tab and shows Download .deb as the default. Click Download .deb to grab the Debian / Ubuntu package.

    If your distro fits a different format, switch to the matching tab on the download page first:

    • Fedora / RHEL → downloads a .rpm
    • Arch (AUR) → opens the AUR package page
    • AppImage → downloads a portable AppImage that runs on any distro

  2. Install the package. Pick the workflow you're more comfortable with:

    Works for the .deb download. Skip to the CLI tab if you grabbed a .rpm, AUR package, or AppImage.

    1. Open your Downloads folder in your file manager.
    2. Right-click the ESPHome.Builder_*.deb file and choose Open with → Archive Manager (or whichever archive viewer your distro ships).
    3. In the archive viewer, click Extract and pick a folder you can find again, like ~/esphome-desktop.
    4. Open the extracted folder, then navigate into usr → bin.
    5. Double-click esphome-desktop to launch the app.

    From a terminal, run the installer that matches the file you downloaded:

    • .deb (Debian / Ubuntu): sudo apt install ./ESPHome.Builder_*.deb
    • .rpm (Fedora / RHEL): sudo dnf install ./ESPHome.Builder*.rpm
    • AppImage (any distro): chmod +x ESPHome.Builder_*.AppImage then double-click the file, or run it from a terminal.

Once installed, a web browser should launch and navigate to http://localhost:6052/. On first launch, ESPHome Device Builder asks how you will use it. Select Build and manage devices, then select New to ESPHome and click Finish.

Take Control of Your CAST-1

1. Open the ESPHome Device Builder.

Open your Home Assistant instance and show the dashboard of a Supervisor add-on.

2. Click Show next to Discovered at the top, then click Take Control next to your CAST-1. Change the Name and Friendly Name if you'd like, or leave them, then click Take Control again.

3. Click Install (the up arrow icon), then click On the network and watch it finish installing. (1)

  1. This takes 5 to 10 minutes depending on how fast your device is.

4. Once it completes, click Stop, then press the Reset button on your device. Your CAST-1 will reboot and it's now ready to test out!

You're all set!

Your CAST-1 is now adopted into the ESPHome Device Builder, where you can rename it or edit its YAML.