This environment is meant to support Trezor development - both Firmware and Suite and other related projects. Its main goals are:
- Provide an easy websocket server that is capable of:
- Launching/stopping different versions of the firmware emulator.
- Launching/stopping trezord-go (Bridge).
- Send simple debug commands to the emulator.
- Enable full integration testing of Suite, firmware emulator and Bridge using the websocket server.
- Provide a HTML page that communicates with the server. This allows the developers to perform the actions above.
- To be Nix-native but also offer Docker image to allow non-NixOS developers to use it.
You can also run trezor-user-env "natively" if you are on NixOS but we mainly support the Docker way as described here.
In case you have installed Trezor Bridge previously there will be a port conflict, please make sure it is not running. Either uninstall it completely or stop the service.
Supported platforms are Linux and macOS (both Intel and Silicon).
- Docker (on Linux, you need to be able to run it as non-root user, follow those steps)
- Clone this repo and enter the directory
- Run
./run.sh- it will determine your platform and launch trezor-user-env. See./run.sh --helpfor some additional arguments. - Open http://localhost:9002. The emulator display is available via the browser-based VNC viewer embedded in the dashboard, or via a VNC client at
localhost:15900.
git clone https://github.com/trezor/trezor-user-env.git
cd trezor-user-env
./run.sh
Every image build also publishes the filesystem of the linux/amd64 image as a WSL rootfs tarball tenv-rootfs.tar.gz. It is an OCI artifact in GHCR, ghcr.io/trezor/trezor-user-env-rootfs, tagged like the image (commit SHA and latest). It is meant for Windows hosts that cannot run Linux containers, e.g. GitHub-hosted Windows runners in Trezor Suite desktop e2e tests, which run trezor-user-env inside WSL2 instead.
oras pull ghcr.io/trezor/trezor-user-env-rootfs:latest
wsl --import trezor-user-env <install-dir> tenv-rootfs.tar.gz --version 2
wsl -d trezor-user-env --cd /trezor-user-env -- uv run python src/main.py
The tarball is the plain image root including the uv venv. Environment variables from the Dockerfile ENV are not part of it.
Trezor Suite normally relies on it's own bundled Bridge. To use the Bridge from trezor-user-env instead, you need to disable the bundled Bridge in Suite's debug settings.
- To enable debug settings, open Trezor Suite -> Settings and 5x click on the "Settings" title at the top of the page.
- Go to the "Debug" tab, scroll down to "Transport backends" and disable "Bridge server".
- Also disable "Run on startup" if you want to remember this setting for next launches of Suite.
- If you want to use a real device again, make sure to re-enable the "Bridge server" option.
- Controller
- Websocket server running on localhost:9001
- Has the functionality to control trezor components (run emulators, bridges, etc.)
- Used by Dashboard (below) or by automated end-to-end tests in Trezor Suite
- Dashboard
- HTML page being accessible on localhost:9002
- Instructs the websocket server what to do by predefined functionality
- Used by developers testing their firmware/suite applications manually
- Bridge
- Service running on localhost:21325
- Connection between the trezor device (or running emulator) and the host
- Used by applications needing to communicate with trezor device (for example Suite)
- Bitcoin regtest
- Bitcoind with blockbook running in regtest mode
- Default credentials for bitcoin backend
- user and password:
rpc/rpcand that you can run
- user and password:
- You can test the connection with
bitcoin-cli -rpcport=18021 -rpcuser=rpc -rpcpassword=rpc -getinfo
See docs/development.md.
- On Apple Silicon Macs,
trezor-user-env-regtestruns in an emulation layer as there is no arm native image. You may experience some slowness or issues when using it on arm Macs.
- instead of running the
developversion of the node bridge, downloadable fromhttps://dev.suite.sldev.cz/transport-bridge/develop/dist/bin.js, it is possible to run thebin.jsserver from the local Suite build - it is necessary to create a symbolic link to the ./trezor-suite dir with the local Suite repository - e.g.
ln -s ~/trezor-suite trezor-suitein the root of the trezor-user-env repo