Device app development framework

Ledger maintains a set of repositories that, together, give you everything you need to build, test, load, and submit a Ledger device application. This page lists each tool, what it does, and when to reach for it.

At a glance

When to pick which

Starting a new app

Fork one of the boilerplates:

• app-boilerplate: new device app written in C. The most common starting point. Comes with C unit tests (cmocka), Ragger functional tests, CI workflows, and a Makefile already wired to the SDK.
• app-boilerplate-rust: same scope as above, in Rust, for teams that prefer it.
• app-plugin-boilerplate: only for Ethereum-app plugins (Clear Signing for an EVM contract). Different lifecycle: a plugin runs alongside the Ethereum app, not as a standalone app.

Building locally

Pick one of:

• VSCode + ledger-dev-tools: the recommended path on macOS and Windows. The extension launches the ledger-app-dev-tools Docker image behind the scenes and exposes Build / Run with Speculos / Run tests / Load on device as IDE tasks.
• Docker images from ledger-app-builder, in three flavours:
  • ledger-app-builder-lite (C only),
  • ledger-app-builder (default, C + Rust),
  • ledger-app-dev-tools (full image with Speculos and Ragger; what the VSCode extension uses).
• Bare host with the SDK directly: works for advanced users on Linux who already have ARM toolchains; see the SDK README.

For each device target you set the matching BOLOS_SDK variable: $NANOX_SDK, $NANOSP_SDK, $STAX_SDK, $FLEX_SDK, or $APEX_SDK.

Running and emulating

Speculos emulates Nano S+, Nano X, Stax,and Flex on a desktop computer; install with pip install speculos and run, for example:

speculos --model nanosp build/nanos2/bin/app.elf

Caveats from the Speculos README to keep in mind:

• It implements only the subset of syscalls common apps use (no app-install, firmware-update, or OS-info syscalls).
• Memory-alignment behaviour differs from a real Nano S+ device.
• The internal watchdog enforced on Nano X / Flex / Nano Gen5 / Stax is not emulated.

Writing functional tests

Ragger gives a single pytest interface that runs the same tests against three backends (Speculos, LedgerComm, and LedgerWallet), so you can switch between emulator and physical device with a flag:

pytest <tests/path>                                   # Speculos by default
pytest --backend ledgerwallet <tests/path>            # against a connected device

Install with pip install 'ragger[all_backends]'. The app-boilerplate repo ships an example suite you can copy.

Continuous integration

ledger-app-workflows provides reusable GitHub Actions workflows:

• guidelines_enforcer.yml: checks your repo against Ledger’s published app guidelines. Passing this workflow is a mandatory step to be listed on the Ledger app store.
• Build-and-test workflows that build the app for every supported device and run the Ragger suite on Speculos.

The boilerplates already wire these in.

Putting it together

A typical project layout uses these tools as follows:

1. Fork the right boilerplate (app-boilerplate, app-boilerplate-rust, or app-plugin-boilerplate).
2. Develop locally in VSCode with ledger-dev-tools, or directly with ledger-app-builder Docker images.
3. Run the app interactively in Speculos and write Ragger tests as features land.
4. Push to GitHub; the workflows from ledger-app-workflows build for every device, run the Ragger suite on Speculos, and run the guidelines enforcer.
5. When green, follow the submission process to ship the app through the Ledger Manager.

See also

• Get started: set up a development environment and build your first app.
• Submission process: how an app reaches end users.
• Architecture: where the device app fits in the wider system.
• Ledger Secure SDK: the underlying SDK referenced by BOLOS_SDK.