Environment Variable Index
Every environment variable you might need to set on your own machine, in one table.
Enables remote build mode
Setting both of these enables the MCP server’s remote build mode. See Plan-only vs Remote Build.
| Variable | Required? | Default | Description |
|---|---|---|---|
CONTROL_BASE_URL | No | — | URL of the build server (e.g. https://esphome.cloud). Must include the scheme. Without this, all build calls return an error explaining the mode. |
MCP_AUTH_SECRET | No | — | Auth token for the build server, issued by the control plane. Treat like an API key; rotate immediately if leaked or suspected leaked. Without this, calls to /grant/request return 401. |
Used by espctl CLI on user machines
Read by the espctl CLI on the user’s machine (and by
espctl ide sync in particular).
None are required — all have fallback paths.
| Variable | Required? | Default | Description |
|---|---|---|---|
DEFAULT_IDF_VERSION | No | — | Last-resort fallback when no IDF version is found in --idf-version, .idf-version, or [idf_version] in .espctl.toml. Used by espctl ide sync and a few build paths. |
ESPCTL_SYSROOT | No | ~/.espctl/sysroot | Base directory for the local IDE sysroot. Per-version sysroots live at <base>/<idf-version>/. |
ESPCTL_SERVER | No | saved login server → https://esphome.cloud | Server URL override for espctl ide sync. The --server flag overrides this in turn. |
ESPCTL_ALLOW_INSECURE | No | unset | Set to 1 to allow non-HTTPS server URLs (local development only). Affects espctl login and espctl build --remote. |
Used by the type-driven-ui frontend
If you build the web frontend yourself, these are Vite environment
variables, prefixed with VITE_. They are baked into the bundle at
build time, not read at runtime.
| Variable | Required? | Default | Description |
|---|---|---|---|
VITE_API_BASE_URL | No | (empty) | Base URL the frontend uses to call the build server. Empty string means same-origin (recommended for production deployments behind a reverse proxy). Set to http://localhost:8080 for local development against a build server on the same machine. |
Quick reference: what to set on a fresh user machine
For an MCP user (CLI/IDE flow), you only need two env vars in your
client config (e.g. .claude/settings.json):
CONTROL_BASE_URL = https://esphome.cloud # your build server URL
MCP_AUTH_SECRET = <access key issued by the control plane>
For a browser user (esphome.cloud flow), you set nothing — the browser talks to the build server directly via the same-origin REST API.