# Introduction

espx installs the esp-rs tools, creates esp-hal projects, and builds, flashes and monitors your ESP32.

espx is Rust on ESP32 with zero setup. One binary installs the esp-rs tools, scaffolds a bare-metal [esp-hal](https://github.com/esp-rs/esp-hal) project, then builds, flashes and monitors your board.

```sh
espx setup        # tools into ~/.espx/bin, RISC-V targets into rustup
espx new blinky   # an esp-hal project for the ESP32-C6
cd blinky
espx run          # build, flash and open the serial monitor
```

With one board connected you never pass a port.

## Three surfaces, one core

espx is one core with three interfaces on top of it. They share the same board handling, so a board that one of them has open is reachable from the others.

| Surface            | What it does                                                                                       | Start it with                                      |
| ------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| The `espx` command | Every feature as a terminal command. Headless by default, with `--json` output for scripts and CI  | `espx --help`                                      |
| The desktop app    | A window for your projects, attached boards, serial output, recordings and AI agent clients        | `cargo run -p espx-desktop` in the espx repository |
| The MCP server     | The build, flash and monitor loop as tools for coding agents such as Claude Code, Cursor and Codex | `espx mcp`                                         |

## What espx installs

`espx setup` downloads pinned binaries into `~/.espx/bin` and adds the Rust pieces through rustup.

| Tool                     | Version        | Role                                                          | Where                        |
| ------------------------ | -------------- | ------------------------------------------------------------- | ---------------------------- |
| espflash                 | 4.5.0          | list ports, board info, flash, erase, monitor                 | `~/.espx/bin/espflash`       |
| cargo-espflash           | 4.5.0          | build and flash in one step                                   | `~/.espx/bin/cargo-espflash` |
| esp-generate             | 1.3.0          | scaffold a project from the current esp-hal template          | `~/.espx/bin/esp-generate`   |
| rust-src, RISC-V targets | rustup-managed | `riscv32imc-unknown-none-elf`, `riscv32imac-unknown-none-elf` | `~/.rustup`                  |

Only when you ask for an Xtensa chip (esp32, esp32s2, esp32s3):

| Tool            | Version          | Role                                                   | Where                                  |
| --------------- | ---------------- | ------------------------------------------------------ | -------------------------------------- |
| espup           | 0.17.1           | installs Espressif's Rust fork                         | `~/.espx/bin/espup`                    |
| `esp` toolchain | what espup ships | Xtensa-capable rustc, clang and GCC linker, about 1 GB | `~/.rustup/toolchains/esp`, `~/.espup` |
| export file     | written by espup | `LIBCLANG_PATH` and `PATH` for the fork                | `~/.espx/export-esp.sh`                |

Every binary is checked against the SHA-256 in the tool manifest before it is written to disk. Nothing goes into `~/.cargo/bin`. Set `ESPX_HOME` to keep everything somewhere other than `~/.espx`, and run `espx uninstall --all` to take it all back out.

## What espx never does

espx never reimplements the toolchain. A build is `cargo build --release`, a flash is `cargo espflash flash --release`, a new project is `esp-generate --headless`, and targets come from `rustup target add`. espx fills in the flags and tells you which command it runs:

```text
=> building blinky for the ESP32-C6 (cargo build --release)
```

The one part espx does itself is the serial monitor when you script it. Reading the port directly lets espx decode defmt frames, name the reason for each boot, resolve panics to source lines and share one board between several processes. [Monitor and replay](https://www.espx.dev/docs/cli/monitor) explains when that happens.

Two more rules hold everywhere:

- No command waits for input unless you pass `-i`. Every choice is a flag, and a missing choice is an error that names the flag.
- Builds are always `--release`. A debug esp-hal binary is slow and often too big to flash.

## Platforms

espx runs on Apple silicon macOS and on Linux (arm64 or x86_64). The tool mirror ships no build for Intel Macs, so `espx setup` stops with an `unsupported_platform` error there.

It supports every chip esp-generate can scaffold: the ESP32, ESP32-S2 and ESP32-S3 (Xtensa), and the ESP32-C2, C3, C5, C6, C61 and H2 (RISC-V). The C5 and C61 are marked preview. [Chips and boards](https://www.espx.dev/docs/reference/chips) has the full table.

## Next steps

- [Installation](https://www.espx.dev/docs/installation): install the app and the `espx` command with one script, then the tools.
- [Updating](https://www.espx.dev/docs/updating): how the app and the command update, and how to pin a release.
- [Quick start](https://www.espx.dev/docs/cli/quick-start): from an empty folder to a board printing its boot log.
- [Projects](https://www.espx.dev/docs/cli/projects), [Build and flash](https://www.espx.dev/docs/cli/build-and-flash) and [Monitor and replay](https://www.espx.dev/docs/cli/monitor): the everyday commands.
- [MCP server](https://www.espx.dev/docs/agents/mcp): let a coding agent build, flash and debug on the board on your desk.
- [Commands](https://www.espx.dev/docs/cli/commands): every command and flag.