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

Prerequisites

A short list of what you actually need.

On your computer

ThingWhy
The espctl programThis is the bridge between your AI tool and the build server. Download a release binary; you don’t need to build it from source.
An AI tool that supports MCPClaude Code, Cursor, Claude Desktop, Codex CLI, or OpenCode. Pick whichever you already use. See Part II — Client Setup.
An internet connectionOnly for actual builds. If you only want to plan and review (no real building), you can work offline.

That’s all. You do not need:

  • ESP-IDF installed locally. The build server has it.
  • Python, the C/C++ toolchain, or any other compiler. The build server has those too.
  • A Rust toolchain. You only need that if you want to build espctl from source — and you don’t, because there are ready-made downloads.

On the network

For actual builds, your computer talks to the build server over the same ports your browser uses (80 / 443). Nothing special.

If your network is very strict and blocks UDP, the build still works — it just falls back to a slower path. You don’t need to configure anything; this happens automatically.

An account

You need an access key from your build server. Treat it like a password: don’t paste it into screenshots, don’t put it in a public repository, and rotate it if you think someone else has seen it.

If you use esphome.cloud, the access key is issued to you when you sign up. If you run your own build server, the operator gives you one.

Once you have the key, save it with:

espctl login --token <your-access-key>

This stores your credentials in ~/.config/espctl/credentials.json and is all you need for CLI usage. For MCP server mode (AI tool integration), you’ll also set CONTROL_BASE_URL and MCP_AUTH_SECRET in your AI tool’s config — see Quick Start step 3.

Quick checklist

  • espctl somewhere on disk, you know its full path
  • An MCP-capable AI tool installed (Claude Code, Cursor, Codex, OpenCode, or Claude Desktop)
  • Access key from your build server
  • Run espctl login --token <key> (for CLI usage)
  • Set CONTROL_BASE_URL + MCP_AUTH_SECRET in AI tool config (for MCP server mode)

If those boxes are checked, jump to Quick Start.