Quickstart

This page gets you from nothing installed to an app running in Speculos in a few minutes, whatever your operating system. It is the recommended entry point if you have never used Speculos before.

Speculos emulates Ledger devices (Nano X, Nano S+, Flex, Stax, Apex+) on a regular computer, so you can run and drive a device app without any hardware.

TL;DR

# 1. Install (Linux/macOS, inside a virtualenv)
pip install speculos

# 2. Run the demo app shipped with the source tree.
#    boil.elf embeds its API level, which Speculos auto-detects, so no -a needed.
speculos apps/boil.elf

# 3. Open the web interface
#    -> http://127.0.0.1:5000

If you don’t have an app yet, see Get an app to run. To drive the device programmatically (tests, agents, CI), see Driving Speculos from code or an agent.

Choose your setup

There are three independent choices to make. Pick one cell per row, then jump to the matching command below.

Question

Options

How do I install it?

pip (native) · Docker (no local toolchain)

What is my OS?

Linux · macOS (Intel & Apple Silicon) · Windows

How do I want to see the screen?

Qt (native window) · Web (browser, port 5000) · VNC · headless (no display)

Rules of thumb:

  • pip is the simplest if you are on Linux or macOS and just want to script the device. Docker is the most portable (and the only realistic path on Windows) because it bundles the ARM toolchain and all dependencies.

  • The Web display (--display headless + the REST API on port 5000) works everywhere, including Docker, and needs nothing but a browser. Start with it.

  • Qt gives a native window but requires pip install and a graphical session (an X server on Windows/WSL). VNC is mostly useful from Docker or over a network.

Install with pip (Linux & macOS)

Always work inside a virtualenv to avoid needing admin rights:

python3 -m venv venv
source venv/bin/activate
pip install speculos

pip install speculos ships a prebuilt launcher, so you do not need the ARM cross-toolchain for this path. If you want to build from source instead (to hack on Speculos itself), follow Linux requirements and build.

macOS note: the pip package works on both Intel and Apple Silicon. If you hit a build or dependency wall, use the Docker path below — it is the recommended option on macOS.

Install with Docker (Linux, macOS, Windows)

The official image bundles everything; it is multi-arch (works natively on Apple Silicon, no Dockerfile edit needed):

docker pull ghcr.io/ledgerhq/speculos:latest
docker image tag ghcr.io/ledgerhq/speculos:latest speculos

See Docker for build-from-source and docker-compose setups.

Run it

In every command below, replace path/to/app.elf with your own app (see Get an app to run). The model is auto-detected from recent apps; override it with --model {nanox,nanosp,stax,flex,apex_p} if needed.

Just want to check your install with no app of your own? Use the bundled demo: speculos apps/boil.elf.

Web display (works everywhere — start here)

pip:

speculos --display headless path/to/app.elf
# open http://127.0.0.1:5000

Docker (mount your apps folder, publish the API port):

docker run --rm -it \
  -v "$(pwd)"/apps:/speculos/apps \
  -p 5000:5000 \
  speculos --display headless --api-port 5000 apps/app.elf
# open http://127.0.0.1:5000

Qt native window (pip only, needs a graphical session)

speculos --display qt path/to/app.elf

On Windows/WSL 2, Qt needs an X server exported from Windows — see Windows (WSL 2).

VNC (handy from Docker)

docker run --rm -it \
  -v "$(pwd)"/apps:/speculos/apps \
  -p 41000:41000 \
  speculos --display headless --vnc-port 41000 apps/app.elf
# connect a VNC client to 127.0.0.1:41000

macOS Screen Sharing requires a password: add --vnc-password <pwd>.

Headless (no display, for CI / agents)

speculos --display headless --api-port 5000 --apdu-port 9999 path/to/app.elf

You then interact entirely through the REST API (port 5000) and the APDU TCP server (port 9999). This is the setup most automation and agentic workflows use — see Driving Speculos from code or an agent.

What’s next