Configuration
The files espx reads and writes, what lives in ~/.espx, and the environment variables it reads.
espx has two configuration files of its own, both optional: espx.toml in a project and ~/.espx/boards.toml. Everything else lives where the tool that owns it reads it. Command-line flags override every file.
espx.toml
Next to a project's Cargo.toml. It binds the project to a board and holds the AI agent policy.
| Key | Type | Default | Meaning |
|---|---|---|---|
board.id | string | none | The board flash, run and monitor use when --port is not given. A board id, a name from boards.toml, or a port path |
board.baud | integer | none | The flashing speed for flash and run when --baud is not given |
agent.boards | array of strings | [board.id], or none | Boards AI agents may touch, by id, name or port |
agent.flash | boolean | true | Agents may flash the allowed boards |
agent.erase | boolean | false | Agents may erase the allowed boards |
Written by espx new --board-id (the [board] section), espx agent set, espx agent allow and the desktop app, which edit the [agent] lines in place and keep your comments. A missing file means the defaults. An unknown key is an error that names the file, the line and the key. See Boards and ports and Agent policy.
boards.toml
~/.espx/boards.toml gives physical boards names:
Each key is a board id (the USB serial number, or the port path when there is none), each value a name: unique, at most 64 characters of ASCII letters, digits, -, _ and ., starting with a letter or digit. Ids compare without regard to case; names compare exactly. espx boards name and the desktop app's rename write it, replacing the whole file, so comments do not survive. An unknown key is an error.
Files other tools own
espx reads these and leaves their contents to their tools.
| File | Owner | What espx uses |
|---|---|---|
espflash_ports.toml | espflash | [connection] serial, step 3 of the board selection order. espx new --port writes it |
espflash.toml | espflash | [flash] size and the partition_table and target_app_partition in [idf_format_args] or [idf], for the partition check. espflash itself reads baudrate and the rest of [flash] (mode, size, frequency) |
.cargo/config.toml | cargo | [build] target, from which espx derives the chip |
rust-toolchain.toml | rustup | channel; esp means an Xtensa project that needs Espressif's fork |
Cargo.toml | cargo | The binary name, whether defmt is a dependency, esp-hal's features, and the crate requirements before the first build |
Cargo.lock | cargo | The resolved esp-hal crate versions, also from an enclosing workspace |
The ~/.espx folder
| Path | Contents |
|---|---|
bin/ | espflash, cargo-espflash, esp-generate, and espup after an Xtensa setup |
export-esp.sh | Written by espup: LIBCLANG_PATH and PATH for the Xtensa fork |
update-check | The daily update check's cache |
boards.toml | Board names |
agent.log | The agent audit log, one JSON object per line |
sessions/ | Recordings made by the desktop app: one folder per board, a .jsonl file per recording and a .toml beside it with its name, board and project |
hub.sock, hub.lock | The board hub's Unix socket and lock, present while an espx process serves it. Both are readable and writable by your user only |
desktop.toml | The desktop app's settings; see Desktop app |
desktop-state.toml | The desktop app's recent projects |
Set ESPX_HOME to use another folder. espx uninstall --home deletes the whole folder.
Outside ~/.espx, rustup keeps the RISC-V targets and the esp toolchain in ~/.rustup, and espup keeps its files in ~/.espup. espx setup --shell adds one line to ~/.zshrc or ~/.bashrc. Nothing goes into ~/.cargo/bin except the espx binary you installed with cargo.
Environment variables
| Variable | Read by | Effect |
|---|---|---|
ESPX_HOME | espx | The folder espx keeps its tools and state in, instead of ~/.espx |
ESPX_NO_UPDATE_CHECK | espx | Set to any value to turn off the daily background update check and its notices |
MONITOR_BAUD | espx, espflash | The monitor speed when --baud is not given. Default 115200 |
ESPFLASH_BAUD | espflash | The flashing speed when neither --baud nor [board] baud is set |
ESPFLASH_PORT | espflash | The port when espx leaves the choice to espflash (erase and info without --port, flash -i). espx's own board selection does not read it |
SHELL | espx | Which shell config espx setup --shell and espx uninstall --shell edit: zsh or bash |
CLAUDE_CONFIG_DIR, CODEX_HOME | espx | Where espx looks for Claude Code's and Codex's configuration when it checks or changes an MCP client |
ESPX_BASE_URL, ESPX_TOOLS_URL | espx | Point espx at another release server or tool mirror |
espx gives cargo and rustup one environment: yours, plus the lines of ~/.espx/export-esp.sh when it exists, with ~/.espx/bin first on PATH and RUSTUP_TOOLCHAIN removed so the project's rust-toolchain.toml decides the toolchain.