# 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](https://rustup.rs) 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

```sh
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](https://www.espx.dev/download) 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

```sh
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`:

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

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

```sh
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](https://jedisct1.github.io/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

### 1. Run setup

```sh
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`:

```sh
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](https://www.espx.dev/docs/reference/xtensa).

### 2. Check the result

```sh
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](https://www.espx.dev/download) lists each file with its size, SHA-256 and signature. The espx release key, key id `DC7D2A30607CC7E8`, is:

```text
RWTox3xgMCp93HqVQ/j9m4/fzGUwLrGpkBYgfduLhiPiHLS2oAyCiye3
```

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

```sh
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](https://www.espx.dev/docs/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:

```sh
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:

```sh
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`:

```sh
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:

```sh
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](https://www.espx.dev/docs/reference/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.

## Next

Follow the [Quick start](https://www.espx.dev/docs/cli/quick-start) to create a project and flash a board.