# 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. ```toml title="espx.toml" [board] id = "58:8C:81:53:AD:2C" # the board this project flashes by default: an id, a name or a port baud = 460800 # flashing speed when --baud is not given [agent] boards = ["58:8C:81:53:AD:2C"] # boards an agent may flash, erase or reset; [] = none erase = false # default false flash = true # default true ``` | 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](https://www.espx.dev/docs/cli/boards#bind-a-project-to-a-board) and [Agent policy](https://www.espx.dev/docs/agents/policy). ## boards.toml `~/.espx/boards.toml` gives physical boards names: ```toml title="~/.espx/boards.toml" [names] "58:8C:81:53:AD:2C" = "bench-c6" ``` 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](https://www.espx.dev/docs/cli/boards#how-espx-picks-a-board). `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](https://www.espx.dev/docs/cli/build-and-flash#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 | ```toml title="espflash.toml" baudrate = 460800 [flash] size = "8MB" ``` ## 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](https://www.espx.dev/docs/desktop#settings) | | `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. ## Related - [Boards and ports](https://www.espx.dev/docs/cli/boards) - [Agent policy](https://www.espx.dev/docs/agents/policy) - [Desktop app](https://www.espx.dev/docs/desktop)