Get an app to run

Speculos runs a compiled device app: an .elf file. This page covers the three ways to obtain one, from easiest to most involved:

  1. Use a ready-made demo .elf — fastest, no build.

  2. Build a public app with Docker — the ledger-app-builder image, no local toolchain.

  3. Build with the VS Code extension — one-click build and run in Speculos.

Why not just grab the app from my Ledger? Production apps shipped on a real device are not directly extractable as runnable .elf files. To run an app in Speculos you either reuse a published demo binary or build it from source.

1. Use a ready-made demo .elf

The Speculos source tree ships a couple of small demo apps under apps/, e.g. apps/boil.elf (“BOILerplate”). They are perfect to verify your install:

speculos apps/boil.elf

These binaries are old and exist for Speculos’ own tests. Do not use them to validate a real integration — build the current app instead (below).

Most Ledger device apps are open source and public on GitHub, for example:

Their CI often attaches prebuilt .elf artifacts to releases/runs. When in doubt, build from source — it is one Docker command.

2. Build a public app with Docker

Ledger publishes ledger-app-builder, a Docker image with the full ARM toolchain and every device SDK preinstalled. You do not need to install anything else locally.

Clone a public app and open a build shell inside the container:

git clone https://github.com/LedgerHQ/app-boilerplate.git
cd app-boilerplate

docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder-lite:latest

docker run --rm -it \
  -v "$(realpath .):/app" \
  ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder-lite:latest

Inside the container, the SDK paths are exposed as environment variables ($NANOX_SDK, $NANOS2_SDK for Nano S+, $FLEX_SDK, $STAX_SDK, …). Build for the target you want:

# inside the container
make BOLOS_SDK=$FLEX_SDK
exit

The resulting binary lands in build/<target>/bin/app.elf on your host. Run it:

speculos build/flex/bin/app.elf
# or with Docker:
docker run --rm -it -v "$(pwd):/speculos/apps" -p 5000:5000 \
  speculos --display headless --api-port 5000 apps/build/flex/bin/app.elf

3. Build with the VS Code extension

The Ledger Dev Tools extension wraps the ledger-app-builder container and adds one-click tasks. It is the smoothest path if you already use VS Code.

  1. Install the extension from the VS Code Marketplace (requires Docker running).

  2. Open a Ledger app folder (e.g. a clone of app-boilerplate).

  3. From the extension sidebar (or the Command Palette → Ledger), use:

    • Select target — choose Nano X / S+ / Flex / Stax / Apex+

    • Build — compiles the app inside the container (output in build/)

    • Run with Speculos — launches Speculos on the freshly built .elf

    • Open Speculos Web display — opens the web UI in your browser

The extension manages the container, ports and .elf path for you, so it is also the quickest way to discover the workflow before scripting it yourself.

What’s next