Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Browser Wizard (esphome.cloud/app)

You don’t need an AI tool at all if you don’t want one. The same espctl backend powers the wizard at esphome.cloud/app, where you can configure, build, and flash an ESP32 device entirely from a browser tab.

Not to be confused with the browser-based MCP at esphome.cloud/mcp/esp-idf, which gives you the raw MCP tools in a web console. This page is the guided wizard — simpler, more hand-holding.

Who this is for

  • ESPHome users who already think in YAML and want a click-through flow instead of a chat.
  • First-time users who want to try this without installing anything.
  • People who don’t want to install an AI tool at all.
  • Workshops and demos where the goal is “click these buttons, plug in the device, see it light up”.

What it looks like

The wizard has two modes: component mode (legacy, manual component selection) and solution mode (recommended, guided flow). Solution mode is a 7-step process:

  1. Domain — pick your target domain (Vehicle & Aircraft Control, IoT Device Tooling, Network Security, Home Data Center, or Edge AI). This scopes the wizard to show only relevant modules and solutions.
  2. Device — pick a chip (ESP32, ESP32-S3, ESP32-C6, etc.), board variant, device name, and Wi-Fi configuration.
  3. Module — select a hardware module that matches your board. Modules define what hardware capabilities are available (motor control, camera, IMU, failsafe relay, etc.). Filtered by domain and chip target.
  4. Solution — choose a pre-optimized firmware configuration. Each solution bundles orchestration steps, required components, and user-configurable parameters. For vehicle domains, a chain-priority summary (control uplink / video downlink / telemetry) is shown.
  5. Parameters — configure the solution. Parameters render as dropdowns (for enum values like IMU chip, control protocol, actuator type), toggles (for booleans), or number inputs (for numeric values). Cascading visibility: selecting “No IMU” hides the chip selector. A GPIO pin map table shows which pins are assigned and updates dynamically based on your selections.
  6. Review — verify your module, solution, and parameters. Pin conflicts are detected and warned. For dual-MCU solutions, two firmware targets are shown (Control Board + Camera Board).
  7. Build — compile the firmware remotely, then flash over USB.

You can switch to component mode at any time using the toggle at the top.

No file ever touches your local disk unless you choose to download it.

Security note: Your compiled firmware may contain embedded secrets (Wi-Fi credentials, API keys). Treat downloaded .bin files as sensitive and don’t share them publicly.

Architecture (browser side)

┌─────────────────────────────────────┐
│   Browser (ESPHome wizard)          │
│  - Asks the build server to talk    │
│  - Opens 3 channels:                │
│    * espctl  — build control + events
│    * pty     — live terminal stream │
│    * firmware — binary chunks       │
└──────┬──────────────────────────────┘
       │ HTTPS (connection setup)
       ▼
┌─────────────────────────────────────┐
│  Build server (esphome.cloud)       │
│  - Issues a build permission        │
│  - Picks the best build machine     │
│  - Helps both sides connect         │
└──────┬──────────────────────────────┘
       │ Job assignment
       ▼
┌─────────────────────────────────────┐
│  Build machine                      │
│  - Receives the permission          │
│  - Talks directly to your browser   │
│  - Runs the build in a sandbox      │
│  - Streams logs + firmware back     │
└─────────────────────────────────────┘

The build server never touches the build itself — it only helps the two sides find each other. Once the channels are open, all build traffic flows directly between your browser and the build machine. Logs, firmware, even keystrokes for the serial console go peer-to-peer.

The three channels

ChannelDirectionCarries
espctlBrowser ↔ Build machineThe build request, status events, structured progress, and any other control messages.
ptyBuild machine → BrowserRaw terminal bytes — idf.py output as it scrolls past.
firmwareBuild machine → BrowserThe compiled .bin file in chunks (with a final checksum for verification).

The channels open once when you connect, and stay open for the lifetime of the build.

What happens when you click “Compile”

  1. Permission request: Your browser asks the build server: “I want to build something, with these channels, for this long.”
  2. Permission issued: The build server signs a short-lived token saying what you’re allowed to do, then picks a build machine.
  3. Connection setup: Your browser and the build machine exchange a few messages through the build server to find each other on the network.
  4. Direct connection: Your browser and the build machine connect directly (or via a relay if your network can’t do direct connections).
  5. Build: Your browser sends the build request. The build machine verifies the permission, runs the build in a sandbox, and streams logs and the finished firmware back over the channels.
  6. Flash: Your browser feeds the firmware into a built-in flasher, which writes it over USB to your device.

Security model in the browser

  • Permissions are short-lived. The build server won’t issue a permission longer than 30 seconds for general use, and won’t extend an existing one — you’d start a new build.
  • Channel allow-list. A permission lists exactly which channels you can open; the build machine enforces this. Your browser can’t open a channel it wasn’t granted.
  • Bandwidth and message-rate limits. Each permission has a bandwidth cap and a message-rate cap, enforced by the build machine.
  • Encrypted end-to-end. All channel traffic is encrypted between your browser and the build machine. The build server can’t read it.

See Grants & Security for the full model.

Things the web wizard doesn’t do

The wizard exposes the most common slice of espctl. A few advanced features are AI-tool-only:

  • Custom build profiles beyond debug / release.
  • Manual task_id management (the wizard handles task lifecycles for you).
  • Reading arbitrary project://* resources from your local disk (the browser doesn’t have a local disk in the same sense).
  • Long-running serial sessions beyond a few minutes (permission TTLs make this intentional — restart the session if you need more time).

If you need any of these, use Claude Code or another AI tool instead.

See also