ESPHome Fleet

Manage a fleet of ESPHome devices from one place, inside Home Assistant. Compile, flash, schedule, and track dozens or hundreds of devices without babysitting the stock ESPHome dashboard.

Is this for you?

If you have more than ten or fifteen ESPHome devices and you've started feeling friction — compiles that take forever on a Raspberry Pi, a dashboard that scrolls off the screen, "which of these is on the latest version again?", no way to schedule an overnight upgrade of the whole house — ESPHome Fleet is aimed at you.

It's built as a Home Assistant add-on. If you're already running Home Assistant and you use ESPHome today, installing it takes one click (details below) and your existing YAML in /config/esphome/ is picked up automatically. Nothing to copy, migrate, or reconfigure.

What it gives you

• A single view of every ESPHome device. Online status, current firmware version, which Home Assistant entity it's wired up to, IP address, WiFi vs Ethernet, pinned ESPHome version — all sortable, filterable, deep-linkable to the device's HA page.
• Bulk operations — upgrade every outdated device tonight, pin half of them to a known-good ESPHome version, rebuild the whole fleet after an ESPHome release.
• Offload compilation to a fast machine. If your HA runs on a Pi or mini-PC and compiles feel slow, spin up one or more build workers (small Docker containers) on whatever's fastest in the house — a gaming PC that's idle overnight, a NAS, a mini PC — and point them at the add-on. The built-in local worker also works; remote workers are a choice, not a requirement.
• Scheduled upgrades. Upgrade the office lights every Sunday at 3am. One-time "upgrade this device tomorrow at 8pm when nobody's home". Per-device version pins so critical devices don't jump to a broken ESPHome release.
• An inline YAML editor with autocomplete. Monaco (the VS Code editor) in the browser, powered by ESPHome's own schema. Validate a config without running a compile.
• Native Home Assistant integration. Every managed device shows up in HA's device registry with an Update entity, sensors for firmware version / queue depth / worker status, and a compile Action you can call from automations.
• Safe by default. The browser UI sits behind Home Assistant's own authentication (Ingress); the direct-port API on :8765 requires a bearer token. Every compile job, schedule change, and config edit is attributed to the HA user who made it.

How it works

Three moving parts:

                              ┌──────────────┐
                         ┌───►│   Worker 1   ├───► ESP devices
  Home Assistant         │    └──────────────┘
┌──────────────────┐     │    ┌──────────────┐
│  ESPHome Fleet   ├─────┼───►│   Worker 2   ├───► ESP devices
│    (add-on)      │     │    └──────────────┘
└──────────────────┘     │    ┌──────────────┐
                         └───►│   Worker N   ├───► ESP devices
                              └──────────────┘

1. The add-on runs inside Home Assistant. It owns the device list, the job queue, the web UI, and coordinates everything.
2. Build workers are small Docker containers that do the actual compiling. The add-on ships with a built-in local worker so you don't need any remote hardware to get started — just increase its slot count in the Workers tab.
3. ESP devices on your network receive firmware OTA-style, directly from the worker that built it — same mechanism as the stock ESPHome dashboard, just triggered from this UI.

Installation

As a Home Assistant add-on (recommended)

Or manually:

1. Settings → Add-ons → Add-on Store → ⋮ (top right) → Repositories and add https://github.com/weirded/distributed-esphome.
2. Find ESPHome Fleet in the store and click Install.
3. Start the add-on. Open the web UI from the HA sidebar.

Home Assistant also auto-discovers the add-on and offers to add the companion integration — accept that notification once to get the device, sensor, and update entities into HA.

As a standalone Docker container

Only if you're running the server outside Home Assistant. Most people don't need this.

docker run -d \
  --name esphome-fleet-server \
  --network host \
  -v /path/to/esphome/configs:/config/esphome \
  -v esphome-dist-data:/data \
  -e SERVER_TOKEN=choose-a-random-string \
  ghcr.io/weirded/esphome-dist-server:latest

The UI is at http://your-host:8765. --network host is required so the server can discover ESP devices over mDNS.

To test pre-release builds, use :develop instead of :latest — that tag advances on every push to develop and isn't meant for production.

A tour of the UI

• Devices — every ESPHome config you have. One-click Upgrade on any row; Upgrade dropdown for bulk actions (upgrade all outdated, upgrade selected, upgrade everything). Edit YAML inline with autocomplete and validation. Pin a device to a specific ESPHome version. Open a live device log. Deep-link to the HA device page.
• Queue — what's compiling, what just finished, what failed, what's queued. Live build logs. Retry, cancel, clear, download the compiled .bin.
• Workers — the workers you have connected, their platform, online status, number of build slots, what they're currently building. One-click + Connect Worker generates the docker run / docker compose snippet for adding a new one.
• Schedules — every scheduled upgrade across your fleet in a single view. See what's due next, when it last ran, whether the run succeeded.

Dark/light theme toggle + a "streamer mode" that blurs tokens and secrets for screen-sharing are in the header.

More in DOCS.md — configuration options, image signature verification, and the less-common operational workflows.

License

MIT.

Support