Quick Start (5 minutes)
The fastest path from “I have nothing” to “my first build worked”.
1. Get the espctl tool
You need the espctl program on your computer. Download a ready-made
release binary from the
aegis releases page and put
it somewhere on your disk. Note where it is — you’ll need the full path
in step 3.
(If you’d rather build from source, you can — but you don’t have to.)
2. Log in
Get your access key from whoever runs your build server (or from esphome.cloud), then run:
espctl login --token <your-access-key>
That saves your credentials. From now on, every espctl build goes to
your build server automatically.
You don’t need to install ESP-IDF, you don’t need a toolchain, you don’t need anything else. The build server has all of that already.
3. Tell your AI tool how to start espctl (MCP server)
If you want your AI assistant to use espctl, pick the tool you use and follow the matching chapter — each one is just 3 lines of config:
The shape is the same in all of them: you tell the tool to run
/path/to/espctl mcp serve with your build server URL and access key
in the environment. (The MCP server uses env vars CONTROL_BASE_URL and
MCP_AUTH_SECRET — this is separate from espctl login, which is for
CLI usage.)
Restart your AI tool so it picks up the new settings.
4. Check it’s working
In your AI tool’s chat, ask:
What espctl tools do you have?
You should see a list of about 40 things it can do — build, doctor,
store_versions, and so on. If you don’t, see
Troubleshooting.
Then ask:
Run doctor.
You should get back a “healthy” report. If anything fails, double-check the build server URL and access key from step 2.
5. Build your first firmware
Open the folder of any ESP-IDF project (or ask your assistant to make a new one) and say:
Build it for esp32s3 and tell me if anything breaks.
espctl build is remote by default — no --remote flag needed. Your
assistant will:
- Send the build to the build server.
- Watch it run (this can take a few minutes).
- Show you the result: either “build succeeded, the firmware is X KB, here’s the breakdown” or “build failed at this line, here’s the error in plain English”.
When the build works, you can ask the assistant to download the firmware file or hand it straight to a flasher.
5b. Pre-flight your hardware (optional)
Before flashing, the CLI has three quick commands that confirm your board is connected and ready:
# What serial ports are visible?
espctl ports
# What chip is on this port?
espctl probe --port /dev/cu.usbmodem1101
# Flash the bundle your build produced
espctl flash ./build/flash_bundle.tar.gz --port /dev/cu.usbmodem1101
See Firmware & Flash for the full reference,
including espctl monitor for streaming serial output.
6. Where to go next
- Want the full list of things your assistant can do? Tool Reference.
- Want to use a web page instead of an AI tool? Browser Wizard.
- Curious how it works under the hood? System Overview.
- Something broken? Troubleshooting.
That’s it. You’re up.