Glossary

Terms you’ll see throughout this manual.

A

Aegis — The umbrella project that contains the build server, the build machine software, and the espctl CLI/MCP server. Lives in github.com/ff4415/aegis.

artifacts.manifest — The MCP tool that returns the official manifest.json from a completed build, including flash offsets for each binary.

B

Bandwidth limiter — Per-channel byte counter that enforces max_bandwidth_kbps from a permission. Slows down sends when exceeded; does not disconnect.

Bootloader — The first-stage firmware that runs before your application on an ESP32. The build produces a separate bootloader.bin you flash at offset 0x0 (or 0x1000, depending on the chip).

Build machine — A Linux host that runs the actual ESP-IDF builds inside a sandbox. Checks the build server for jobs over HTTPS and accepts WebRTC peer connections from clients. Never opens an inbound TCP port for build traffic.

build (tool) — The MCP tool that submits a firmware build to a remote build machine. Returns a task_id immediately; the build itself runs in the background.

Build cache — On-disk state under build/ that lets incremental builds skip already-compiled translation units. Switching chip targets invalidates the cache.

Build server — The public HTTP service. Issues permissions, helps set up WebRTC connections, schedules jobs to build machines. Stateless. Never sees build contents.

build.status — The MCP tool you use to check whether a build is still running, finished, or failed.

C

CMake — The build system ESP-IDF uses under the hood. The build machine runs idf.py build, which is itself a thin wrapper over CMake + Ninja.

cwd — In MCP server configs, the working directory the MCP server should run in. For espctl, this is typically the absolute path to the ESP-IDF project the build machine should operate on.

D

Data channel — A WebRTC building block that lets two peers exchange messages over an encrypted connection. Aegis uses three: espctl, pty, and firmware.

doctor — The MCP tool that runs a comprehensive health check across the store, the project config, the env vars, and the build server connectivity. Run this first when troubleshooting.

E

ESP-IDF — Espressif’s official IoT Development Framework — the C/C++ SDK and toolchain for ESP32 family chips.

espctl — The CLI binary at the heart of this manual. Subcommands include mcp serve (to launch the MCP server), plus standalone CLI verbs for doctor, build, etc.

ESPCTL_STORE_ROOT — Environment variable pointing at the toolchain store directory. Used by the build machine.

F

Firmware channel — The third WebRTC data channel, dedicated to streaming the compiled .bin from the build machine back to the client. Has its own bandwidth budget separate from the other channels.

Flash — Both a verb (write firmware to a device) and a noun (the device’s non-volatile storage). The output of a build is one or more .bin files at specific flash offsets.

I

IDF version — A specific tagged release of ESP-IDF (e.g. v5.3.1). Stores can hold multiple versions side-by-side; projects pin the version they want via .idf-version or .espctl.toml.

J

job_id — A unique ID identifying a single permission + build session. Used in URLs like /signaling/{job_id}/offer.

M

MCP (Model Context Protocol) — The open protocol for connecting AI agents to tools, resources, and prompts. See modelcontextprotocol.io.

MCP_AUTH_SECRET — Auth token clients send to the build server to prove they’re allowed to request permissions.

P

Permission — A signed token that names a user, a job, the allowed WebRTC channels, the bandwidth/rate limits, and the expiration time. Issued by the build server, verified by the build machine.

Permission TTL — How long a permission is valid. Default 5-30 seconds. Short on purpose.

Plan-only mode — The MCP server’s mode when CONTROL_BASE_URL and MCP_AUTH_SECRET are not set. The server can read state and generate plans but cannot actually build. See Plan-only vs Remote Build.

Prompt — In MCP, a parameterized message template the server vends to the client. Aegis ships eight built-in prompts; see Built-in Prompts.

project.init — The MCP tool that initializes an espctl project by writing .espctl.toml.

PTY (pseudo-terminal) — A Unix kernel feature that creates a pair of file descriptors mimicking a real terminal. Aegis uses PTYs for interactive sessions like idf.py monitor.

R

Remote build mode — The MCP server’s mode when CONTROL_BASE_URL and MCP_AUTH_SECRET are set. Builds run on a remote build machine.

Resource — In MCP, a read-only URI the server exposes to the client. Aegis ships 15 readable URLs (13 fixed plus 2 templates) covering install snippets, store state, project state, and live build logs.

S

Sandbox — The isolation environment that keeps each build in its own space with no network access, no host filesystem access (except an explicitly mounted workspace), and restricted capabilities.

Store — The on-disk directory containing all installed IDF versions and toolchains. See ESPCTL_STORE_ROOT.

Store manifest — A JSON file in the store that maps IDF versions to their tool paths and checksums. Provisioned by provision-store.sh.

T

task_id — A unique identifier for a single build, returned by build. You check build.status and read build://log/{task_id} to follow the build.

Toolchain — The compiler, linker, and supporting binaries for a specific ESP chip family (xtensa-esp32-elf, riscv32-esp-elf, etc.). The store holds one toolchain per IDF version per family.

W

WebRTC — The browser standard for real-time peer-to-peer communication. Aegis uses it (specifically, data channels) to ship build requests, logs, and firmware between clients and build machines.

See also

• System Overview — sees most of these terms in context.