Krux is an open-source firmware facilitating the creation of Bitcoin signing devices from readily available components, such as Kendryte K210 devices. It transforms these devices into airgapped tools capable of handling transactions for both single and multisignature wallets, supporting offline signing via QR code or SD card, thus empowering users to securely self-custody their Bitcoin.

WARNING: This software has not yet been formally audited by a third party. Use at your own risk!

Detailed instructions for installing and running Krux can now be found in our official documentation.

If you just want to flash (or "install") Krux firmware on your device and are not familiar with the command line, just use our Krux-Installer.

The instructions below are intended for programmers or developers who would like to contribute to the project.

This will download the source code of Krux as well as the code of all its dependencies inside a new folder called krux:

git clone --recurse-submodules https://github.com/selfcustody/krux

Note: When you wish to pull updates (to all submodules, their submodules, ...) to this repo, use:

git pull origin main && git submodule update --init --recursive

The krux bash script contains commands for common development tasks. It assumes a Linux host, you will need to have Docker Desktop or Docker Engine (don't forget to add your user to the docker group sudo usermod -aG docker $USER), openssl, and wget installed at a minimum for the commands to work as expected. It works on Windows using WSL. The channel Crypto Guide from Youtube made a step-by-step video - Krux DIY Bitcoin Signer: Build From Source & Verify (With Windows + WSL2 + Docker)

To build and flash the firmware:

# build firmware for Maix Amigo
./krux build maixpy_amigo

# flash the firmware to Maix Amigo
./krux flash maixpy_amigo

The first time, the build can take around an hour or so to complete. Subsequent builds should take only a few minutes. If all goes well, you should see a new build folder containing firmware.bin and kboot.kfpkg files when the build completes.

Krux uses uv for Python packaging and environment management. Install uv by following its installation guide, then sync the project to install runtime deps (embit and uUR, the native UR module compiled from the same sources the devices run) along with the dev group (pytest, pylint, black and i18n helpers):

uv sync

uUR is a C extension It is built from the bc-ur submodule nested under firmware/MaixPy, so clone with --recursive (or run git submodule update --init --recursive) and make sure a C compiler and the Python development headers are installed (python3-dev on Debian/Ubuntu). After changing the submodule, rebuild it with uv sync --reinstall-package uUR.

uv sync creates a .venv in the project root, resolves uv.lock if needed, and installs everything — this is the day-to-day command. When dependencies in pyproject.toml change but you only want to refresh uv.lock without touching the venv, run uv lock instead; uv sync will then pick the new pins on its next run.

CI uses uv sync --frozen The workflows refuse to silently re-resolve when uv.lock drifts (we value a lot reproducible builds). Whenever you edit pyproject.toml (add, remove, or bump a dependency), run uv lock (or uv sync) and commit uv.lock (in same change). Otherwise CI will fail.

If your clone was set up with Poetry, remove the old environment before the first uv sync so the two managers do not shadow each other:

rm -rf .venv poetry.lock
uv sync

uv run poe format

uv run poe lint

uv run poe test

Before the first run, build the libsecp256k1 that the embit submodule pins (needs gcc and make):

uv run poe secp256k1-build

Without it embit falls back to its pure Python EC implementation, which is slower and does not always match the C library the firmware runs, so some signature paths get exercised differently than on device. CI builds it and fails if the fallback is in use. To check your own setup:

uv run poe secp256k1-check

Note: The coverage report will be created at the htmlcov folder file:///path/to/krux/htmlcov/index.html.

For more verbose output (e.g., to see the output of print statements):

uv run poe test-verbose

To run just a specific test from a specific file:

uv run pytest --cache-clear ./tests/pages/test_login.py -k 'test_load_key_from_hexadecimal'

This is useful for rapid development of non-visual code:

uv run python

Python 3.9.1
Type "help", "copyright", "credits" or "license" for more information.
>>> from krux.key import Key
>>> Key("olympic term tissue route sense program under choose bean emerge velvet absurd", False).xpub()
'tpubDCDuqu5HtBX2aD7wxvnHcj1DgFN1UVgzLkA1Ms4Va4P7TpJ3jDknkPLwWT2SqrKXNNAtJBCPcbJ8Tcpm6nLxgFapCZyhKgqwcEGv1BVpD7s'
>>>

This is useful for rapid code development that utilizes UI/UX. It is also good for newcomers to try Krux before purchasing a device. However, the simulator does not behave exactly as the HW device and may not have all features implemented (e.g. scanning via camera a TinySeed currently only works on the HW device).

Before executing, make sure you have synced the simulator extras:

# This cmd installs the simulator extras alongside the dev group
uv sync --extra simulator

# To install all extras, use:
uv sync --all-extras

Run the simulator:

# Run simulator with the touch device Amigo, then use mouse to navigate
uv run poe simulator

# Run simulator with SD enabled (folder `simulator/sd`) on the small button-only device M5stickV, then use keyboard (arrow keys UP or DOWN and ENTER)
uv run poe simulator-m5stickv --sd

# Run simulator on the device dock, then use keyboard (arrow keys UP or DOWN and ENTER)
uv run poe simulator-dock

# Run simulator with the touch device yahboom, then use mouse to navigate
uv run poe simulator-yahboom

# Run simulator on the device cube, then use keyboard (arrow keys UP or DOWN and ENTER)
uv run poe simulator-cube

# Run simulator with the touch device wonderMV, then use mouse to navigate
uv run poe simulator-wonder-mv

# Run simulator with the touch device tzt, then use mouse to navigate
uv run poe simulator-tzt

Note: With emulated SD card it is possible to store settings, encrypted mnemonics, also drop and sign PSBTs. After some time running, the simulator may become slow. If that happens, just close and open again!

# ImportError: Unable to find zbar shared library
sudo apt install python3-zbar

# ImportError: libGL.so.1: cannot open shared object file: No such file or directory
sudo apt install libgl1

# `pygame.error: No available video device`
# You are trying to run the simulator on an OS without a GUI (some kind of terminal only or WSL). Try one with GUI!

# Depending on the OS, it may be necessary to install zbar-tools too:
sudo apt install zbar-tools

This is useful for taking screenshots of device screens to use in documentation:

# Run all sequences of commands on all devices and in all locales (languages) [Linux OS]
cd simulator
./generate-all-screenshots.sh

# Run a specific sequence for a specific device's with SD enabled (folder `simulator/sd`)
uv run poe simulator --sequence sequences/about.txt --sd

# Sequence screenshots are scaled to fit in docs. Use --no-screenshot-scale to get full size
uv run poe simulator --sequence sequences/home-options.txt --no-screenshot-scale

It is not possible to drop into a live Python REPL anymore as we disabled the MICROPY_ENABLE_COMPILER flag in firmware\MaixPy\components\micropython\port\include\mpconfigport.h. If you enable it again it will be possible to drop into a live Python REPL by issuing an interrupt with Ctrl-C:

If you've made a fresh build and flashed it to your device, you can connect to the device over serial connection with:

screen /dev/tty.usbserial-device-name 115200

If successful, the device should restart and you should see:

K210 bootloader by LoBo v.1.4.1

* Find applications in MAIN parameters
0: '       firmware', @ 0x00080000, size=XXX, app_size=XXX, App ok, ACTIVE
* Loading app from flash at 0x00080000 (XXX B)
* Starting at 0x80000000 ...


[MAIXPY] Pll0:freq:XXX
[MAIXPY] Pll1:freq:XXX
[MAIXPY] Pll2:freq:XXX
[MAIXPY] cpu:freq:XXX
[MAIXPY] kpu:freq:XXX
[MAIXPY] Flash:0xef:0x17
[MaixPy] gc heap=0x8029f430-0x8036f430(851968)
init i2c:2 freq:XXX
[MAIXPY]: find ov7740
[MAIXPY]: find ov sensor

Some devices like Amigo have two serial ports, check the second one if you don't read data from first.

To leave screen serial monitor press Ctrl+a, followed by k, then confirm with y.

Use MaixPy IDE to debug the devices. Click on Tools > Open Terminal > New Terminal > Connect to serial port > Select a COM port available (if didn't work, try another COM port). We have removed some support for MaixPy IDE (due to size constraints), but the debug works.

Krux makes use of MaixPy's WDT watchdog module, you can see it here. This will reset the device if not fed for some time. To stop the watchdog, when connected through the terminal, run the following (starting from v24.07.0 this is no loger possible because the Python real-time compiler and REPL were disabled):

# Run this everytime you want to stop the watchdog

from krux.wdt import wdt
wdt.stop()

Now, with watchdog disabled, you can use debug the device normally. Also remember to disable the Settings > Security > Shutdown Time setting it to 0 to no more automatic resets, and if you added any print statements to the code, they should appear whenever your code is reached.

The project has lots of translations here, if you add new english messages in code using t() function, you will need to:

# Clean unused translations:
uv run poe i18n clean

# Create a new translation file in JSON:
uv run poe i18n new tr-TR

# Make sure all files have this new translated message:
uv run poe i18n validate

# Format translation files properly:
uv run poe i18n prettify

# Create the compiled table for krux translations.py
uv run poe i18n bake

Learn about how to setup fonts here

Use this script to generate device compatible colors from RGB values (usefull for color themes).

Before change documentation, and run the mkdocs server, make sure you have synced the docs extras:

# This cmd installs the docs extras alongside the dev group
uv sync --extra docs

# To install all extras, use:
uv sync --all-extras

To change lateral and upper menus on documentation, see mkdocs.yml file on nav section. To create or edit translations (TODO: need help!), read here.

Create the documentation site locally - http://127.0.0.1:8000/krux/:

uv run poe docs

• https://github.com/SeedSigner/seedsigner for Raspberry Pi (Zero)
• https://github.com/diybitcoinhardware/f469-disco for the F469-Discovery board

• embit, a Bitcoin library for Python 3 and Micropython
• MaixPy, MicroPython for K210 RISC-V
• MicroPython, a lean and efficient Python implementation for microcontrollers and constrained systems
• Kboot and ktool

Issues and pull requests welcome! Let's make this as good as it can be.

Feel free to start a new discussion or an issue for work. When making your pull request, explain what it solves, ideally each PR should focus on solving one issue (exceptions can be made if the work is related or tightly coupled).

Note for PR's: Checkout and branch off of the develop branch, please also make sure to explicitly target develop; main is the default branch for the latest version and also for downloading and installing Krux from source.

For technical support installing or using Krux, you can join our Telegram chat. Follow us on X (Twitter) or send a message to the Bitcoin Forum. Also check out the DIYbitcoin chat on Telegram, a broader community of tinkerers, builders and hackers!

Please do not use issues for support requests. If necessary, you can use our Discussions to post your question here on GitHub.