Environment Variable Index
Every environment variable referenced anywhere in this manual, 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, retrieved from /etc/aegis/secrets.env on the build server host. Treat like an API key. 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 build server (operator concern)
These are not set on user machines — they’re for the operator running the build server host.
| Variable | Required? | Default | Description |
|---|---|---|---|
ALLOWED_ORIGINS | Yes | — | Comma-separated list of exact origins allowed to call /grant/* and /signaling/*. Include scheme; do not use wildcards. Example: https://esphome.cloud,https://www.esphome.cloud. |
CONTROL_PUBLIC_BASE_URL | Yes | — | The public-facing URL of the build server, used in some response bodies and permission fields. Must match the actual deployed URL. |
TURN_EXTERNAL_IP | Yes | — | Public IP of the fallback server (typically the same host as the build server). |
MCP_AUTH_SECRET | Yes | — | Master auth token. Issued to clients via the same env var. |
AGENT_AUTH_SECRET | Yes | — | Auth token used by build machines to register with the build server. |
Used by the build machine (operator concern)
| Variable | Required? | Default | Description |
|---|---|---|---|
CONTROL_BASE_URL | Yes | — | The URL the build machine uses to check for jobs. Must be a routable URL, not an SSH alias. The installer defaults to https://3qMq which will fail with a DNS error in most environments — edit /etc/aegis/agent.env after install. |
AGENT_PUBLIC_IP | No | auto-discovered | The public IP the build machine reports to the build server. Auto-discovered if unset, but auto-discovery can be unreliable behind some network restrictions. |
AGENT_AUTH_SECRET | Yes | — | Auth token for registering with the build server. Same value as on the build server side. |
ESPCTL_STORE_ROOT | Yes | — | Path to the toolchain store the build machine should use. |
RUST_LOG | No | info | Log level. RUST_LOG=debug produces detailed logs. |
Used by the type-driven-ui frontend
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. |
Set automatically by the build system
You don’t normally set these by hand, but they appear in some logs and config files.
| Variable | Set by | Description |
|---|---|---|
IDF_PATH | The build machine (inside the sandbox) | Path to the chosen IDF version inside the sandbox. Don’t override this in your client config; let the build machine set it. |
PKG_TEMP_DIR | The release script | Where the makeself package is staged on the build host. |
TMPDIR | The release script | Temp directory used during packaging — set on the build host when /tmp is a small tmpfs. |
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 = <from your operator>
For a browser user (esphome.cloud flow), you set nothing — the browser talks to the build server directly via the same-origin REST API.