# espx

> espx sets up the ESP32 toolchain, creates esp-hal projects, and builds, flashes and monitors the boards on your desk.

espx is a toolkit for bare-metal Rust (esp-hal) on ESP32 chips: a desktop app, the `espx`
command and an MCP server for coding agents, all on one core. It installs pinned espflash,
cargo-espflash and esp-generate into `~/.espx/bin` and delegates to them, to cargo and to
rustup. Install it with `curl -fsSL https://www.espx.dev/install.sh | sh`, add `-s -- --desktop` for the
desktop app, or build it from source, as Installation describes.

Every link below is Markdown. The same page as HTML is at the URL without `.md`.

## Get started

- [Introduction](https://www.espx.dev/docs.md): espx installs the esp-rs tools, creates esp-hal projects, and builds, flashes and monitors your ESP32.
- [Installation](https://www.espx.dev/docs/installation.md): Install the desktop app and the espx command with one script or the disk image, check the signatures, then install the tools with espx setup.
- [Quick start](https://www.espx.dev/docs/quick-start.md): This page is coming soon.
- [Updating](https://www.espx.dev/docs/updating.md): How the desktop app and the espx command update themselves, and how to check a release by hand.

## Desktop

- [Overview](https://www.espx.dev/docs/desktop.md): What the desktop app does with your projects, boards, serial output, recordings and agents.
- [Projects](https://www.espx.dev/docs/desktop/projects.md): This page is coming soon.
- [Run, build and flash](https://www.espx.dev/docs/desktop/run.md): This page is coming soon.
- [Boards and serial monitor](https://www.espx.dev/docs/desktop/boards.md): This page is coming soon.
- [Recordings](https://www.espx.dev/docs/desktop/recordings.md): This page is coming soon.
- [Toolchain](https://www.espx.dev/docs/desktop/toolchain.md): This page is coming soon.
- [AI agents](https://www.espx.dev/docs/desktop/agents.md): This page is coming soon.
- [Settings](https://www.espx.dev/docs/desktop/settings.md): This page is coming soon.

## CLI

- [Quick start](https://www.espx.dev/docs/cli/quick-start.md): Install the tools, create an esp-hal project and run it on a board, with what each step prints.
- [Projects](https://www.espx.dev/docs/cli/projects.md): Create an esp-hal project with espx new, pick its chip, board and options, and read its dependencies.
- [Build and flash](https://www.espx.dev/docs/cli/build-and-flash.md): Build release firmware with a size check, flash it, and pass extra arguments to cargo and espflash.
- [Monitor and replay](https://www.espx.dev/docs/cli/monitor.md): Serial output with decoded defmt logs, named boot reasons and symbolized panics. Record it, play it back.
- [Boards and ports](https://www.espx.dev/docs/cli/boards.md): Find attached boards, name them, bind a project to one, and pick the port and baud rate.
- [Scripts and CI](https://www.espx.dev/docs/cli/scripting.md): Run espx unattended: wait for log lines, read --json output, act on exit codes.
- [Command reference](https://www.espx.dev/docs/cli/commands.md): Every espx command with its arguments and flags, as the CLI defines them.

## Agents

- [MCP server](https://www.espx.dev/docs/agents/mcp.md): Connect a coding agent to espx mcp so it can build, flash and debug firmware on your board.
- [Agent policy](https://www.espx.dev/docs/agents/policy.md): Choose which boards agents may flash, erase and reset, and read every call they made.
- [Agent context](https://www.espx.dev/docs/agents/context.md): What a coding agent reads before it writes firmware: the AGENTS.md from espx new, and espx context.

## Reference

- [JSON events](https://www.espx.dev/docs/reference/events.md): Every event espx prints with --json, its fields, and the JSON documents the data commands print.
- [Configuration](https://www.espx.dev/docs/reference/configuration.md): The files espx reads and writes, what lives in ~/.espx, and the environment variables it reads.
- [Chips and boards](https://www.espx.dev/docs/reference/chips.md): The chips espx supports with their Rust targets, and the dev boards it knows with their pins.
- [Xtensa chips](https://www.espx.dev/docs/reference/xtensa.md): Install Espressif's Rust fork for the ESP32, S2 and S3, and build Xtensa projects with espx or cargo.
- [Exit codes](https://www.espx.dev/docs/reference/exit-codes.md): The four exit codes espx uses, and the stable error codes that agents and scripts key on.

## Releases

- [Download](https://www.espx.dev/download.md): Download the espx desktop app for Mac, or install the espx command on macOS and Linux in one line.
- [Changelog](https://www.espx.dev/changelog.md): What changed in each espx release of the command line and the desktop app.

## Optional

- [All pages](https://www.espx.dev/llms-full.txt): Every page above in one file, in this order
- [Source](https://github.com/arc1hq/espx): The repository