Installation

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.

One script installs espx on an Apple silicon Mac or on Linux. It downloads the release from espx.dev, checks it, and puts it in place. espx then installs the ESP32 tools itself.

Requirements

Apple silicon macOS, or Linux on arm64 or x86_64. The desktop app is for Apple silicon Macs only.
rustup with a stable toolchain. espx calls rustup and cargo and stops with rust_not_found if they are missing.
curl and tar, which the script and espx use to download and unpack files.

You do not need espflash, esp-generate or any Rust target beforehand. espx setup installs them.

Install the desktop app

curl -fsSL https://www.espx.dev/install.sh | sh -s -- --desktop

This installs the app as ~/Applications/espx.app and links ~/.espx/bin/espx to the espx command inside it, so the command your terminal and your agents run comes from the same build as the app, and it updates with the app. An older espx.app is moved aside and replaced in one rename, so a failed install leaves the old one in place.

If you installed the app another way, Install Command Line Tool in the espx menu makes the same link.

The disk image

The download page also has the app as a disk image. Open it and drag espx to Applications.

Open Anyway

The app is signed ad hoc and not notarized by Apple, so the first time you open it from the disk image macOS refuses. Open System Settings, go to Privacy & Security, and click Open Anyway next to the message about espx. The install script does not run into this: curl does not mark what it downloads as quarantined, so Gatekeeper does not check it.

Install the espx command

curl -fsSL https://www.espx.dev/install.sh | sh

The script puts the espx command in ~/.espx/bin, or in $ESPX_HOME/bin when ESPX_HOME is set. When that folder is not on your PATH it prints the line to add to ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.espx/bin:$PATH"

To install a specific release instead of the latest, set ESPX_VERSION:

curl -fsSL https://www.espx.dev/install.sh | ESPX_VERSION=0.1.0 sh

The script checks the SHA-256 of every file it downloads. When minisign is installed (brew install minisign, or your Linux package manager) it also checks each file's signature against the espx release key and stops when either check fails. Without minisign it says that it checked only the SHA-256.

Install the tools

Run setup

espx setup

This downloads espflash, cargo-espflash and esp-generate into ~/.espx/bin, runs rustup component add rust-src, and adds the RISC-V targets for every RISC-V chip. It is idempotent: a second run checks versions and installs nothing new. The desktop app's Toolchain page runs the same setup with one click.

To set up specific chips, pass a comma-separated list or all:

espx setup --chip esp32c3
espx setup --chip esp32c6,esp32s3
espx setup --chip all

Any Xtensa chip in the list (esp32, esp32s2, esp32s3) also installs Espressif's Rust fork through espup, which is about 1 GB. See Xtensa chips.

Check the result

espx doctor

doctor checks rustup, cargo, each tool, rust-src and the RISC-V targets offline, and prints the fix for anything missing. The Xtensa rows (espup, the esp toolchain and the export file) are optional and never fail the check.

Verifying downloads

Every release file has a minisign signature beside it, its own name plus .minisig. The download page lists each file with its size, SHA-256 and signature. The espx release key, key id DC7D2A30607CC7E8, is:

RWTox3xgMCp93HqVQ/j9m4/fzGUwLrGpkBYgfduLhiPiHLS2oAyCiye3

To check a file you downloaded yourself, keep its .minisig next to it and run:

minisign -Vm espx-0.1.0-macos-arm64.dmg -P RWTox3xgMCp93HqVQ/j9m4/fzGUwLrGpkBYgfduLhiPiHLS2oAyCiye3

minisign prints the signature's trusted comment. It must read espx <version> <file>, here espx 0.1.0 espx-0.1.0-macos-arm64.dmg. A signature that verifies with another comment belongs to another file or another release. The install script, espx update and the app's updates all make the same two checks.

Updates

The desktop app updates itself once a day, and Check for Updates… in the espx menu checks now. espx update updates a command the script installed. Updating covers both, the setting that turns the app's checks off, and updating the tools.

Build from source

You can also build espx from a checkout of the repository:

git clone https://github.com/arc1hq/espx
cd espx
cargo install --path crates/espx-cli

The repository root is a virtual workspace, so cargo install --path . does not work. Name the crates/espx-cli package. cargo puts the espx binary in ~/.cargo/bin, which rustup already added to your PATH. To update it, pull and run the same command again; espx update leaves a cargo install alone.

To run the desktop app from the checkout:

cargo run --release -p espx-desktop

On Linux, building the app needs the X11 and Wayland development libraries (libxkbcommon, libwayland, libxcb).

Plain cargo

espx runs every tool by its full path, so espx build, espx flash and the rest work without changing your shell. If you also want cargo run --release or espflash to work on their own, put the tools on your PATH:

eval "$(espx env)"

espx env prints the export lines for ~/.espx/bin and, after an Xtensa setup, the lines from ~/.espx/export-esp.sh. To add that line to your shell config once, run espx setup --shell. It supports zsh (~/.zshrc) and bash (~/.bashrc).

Uninstall

espx uninstall removes what setup installed. Say what with flags, or pass -i to be asked about each item:

espx uninstall --all      # everything below
espx uninstall --home     # all of ~/.espx: tools, export file, board names, recordings, agent log
espx uninstall --xtensa   # espup uninstall, ~/.espup, the export file
espx uninstall --targets  # the RISC-V targets in rustup
espx uninstall --shell    # the eval "$(espx env)" line in your shell config
espx uninstall --self     # the espx binary

--home deletes the whole ~/.espx folder, including boards.toml, the recordings under sessions/ and agent.log. The Configuration reference lists what lives there. For the app's copy of espx, --self removes only the link in ~/.espx/bin. To remove the app, move ~/Applications/espx.app to the Trash.

Follow the Quick start to create a project and flash a board.