{"id":25676353,"url":"https://github.com/selfcustody/krux","last_synced_at":"2026-05-26T01:01:03.626Z","repository":{"id":39521373,"uuid":"385102171","full_name":"selfcustody/krux","owner":"selfcustody","description":"Open-source signing device firmware for Bitcoin","archived":false,"fork":false,"pushed_at":"2026-05-14T17:36:23.000Z","size":219919,"stargazers_count":326,"open_issues_count":54,"forks_count":69,"subscribers_count":18,"default_branch":"main","last_synced_at":"2026-05-14T19:35:10.198Z","etag":null,"topics":["bitcoin","python","wallet"],"latest_commit_sha":null,"homepage":"https://selfcustody.github.io/krux/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/selfcustody.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/support.en.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-07-12T02:24:17.000Z","updated_at":"2026-05-06T15:24:45.000Z","dependencies_parsed_at":"2025-07-17T23:24:38.270Z","dependency_job_id":"2a0b3bc0-6cd8-4d98-95fc-9c70cffbf0b2","html_url":"https://github.com/selfcustody/krux","commit_stats":null,"previous_names":["jreesun/krux"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/selfcustody/krux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfcustody%2Fkrux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfcustody%2Fkrux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfcustody%2Fkrux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfcustody%2Fkrux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/selfcustody","download_url":"https://codeload.github.com/selfcustody/krux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfcustody%2Fkrux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33499282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","python","wallet"],"created_at":"2025-02-24T14:02:18.770Z","updated_at":"2026-05-26T01:01:03.612Z","avatar_url":"https://github.com/selfcustody.png","language":"Python","funding_links":[],"categories":["Uncategorized","Python"],"sub_categories":["Uncategorized"],"readme":"[![created at](https://img.shields.io/github/created-at/selfcustody/krux)](https://github.com/selfcustody/krux/commit/bb8e2d63e031417111ff7cb2b8877c10e19410be)\n[![downloads](https://img.shields.io/github/downloads/selfcustody/krux/total)](https://github.com/selfcustody/krux/releases)\n[![downloads (latest release)](https://img.shields.io/github/downloads/selfcustody/krux/latest/total)](https://github.com/selfcustody/krux/releases)\n[![contributors](https://img.shields.io/github/contributors-anon/selfcustody/krux)](https://github.com/selfcustody/krux/graphs/contributors)\n[![commit activity](https://img.shields.io/github/commit-activity/y/selfcustody/krux)](https://github.com/selfcustody/krux/commits)\n[![codecov](https://codecov.io/gh/selfcustody/krux/branch/main/graph/badge.svg?token=XU80PT6Q9V)](https://codecov.io/gh/selfcustody/krux)\n[![calver](https://img.shields.io/badge/calver-0Y.0M.MICRO-22bfda.svg)](https://calver.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/selfcustody/krux/blob/main/LICENSE.md)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/img/maixpy_yahboom/logo-312.en.png\" alt=\"yahboom\" style=\"width: 11%;\"\u003e\n\u003cimg src=\"docs/img/maixpy_tzt/logo-314.en.png\" alt=\"tzt\" style=\"width: 11%;\"\u003e\n\u003cimg src=\"docs/img/maixpy_amigo/logo-300.en.png\"  alt=\"maixpy amigo\" style=\"width: 16%;\"\u003e\n\u003cimg src=\"docs/img/maixpy_dock/logo-302.en.png\" alt=\"maixpy dock\" style=\"width: 15%;\"\u003e\n\u003cimg src=\"docs/img/maixpy_wonder_mv/logo-304.en.png\" alt=\"wonder mv\" style=\"width: 11%;\"\u003e\n\u003cimg src=\"docs/img/maixpy_m5stickv/logo-250.en.png\" alt=\"m5stickv\" style=\"width: 6%;\"\u003e\n\u003cimg src=\"docs/img/maixpy_cube/logo-400.en.png\" alt=\"maixpy cube\" style=\"width: 10%;\"\u003e\n\u003c/p\u003e\n\nKrux 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.\n\n---\n## Disclaimer\n**WARNING**: *This software has not yet been formally audited by a third party. Use at your own risk!*\n\n---\n\n# Getting Started\nDetailed instructions for installing and running Krux can now be found in our [official documentation](https://selfcustody.github.io/krux/).\n\n## Krux-installer\nIf 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.\n\n### Download our Krux-Installer\n[\u003cimg src=\"docs/img/badge_github.png\" alt=\"github releases page\" width=\"186\"\u003e](https://github.com/selfcustody/krux-installer/releases)\n\n# Development\nThe **instructions below are intended for programmers or developers** who would like to contribute to the project.\n\n## Download our firmware releases\n[\u003cimg src=\"docs/img/badge_github.png\" alt=\"github releases page\" width=\"186\"\u003e](https://github.com/selfcustody/krux/releases)\n\n## Fetch the code\nThis will download the source code of Krux as well as the code of all its dependencies inside a new folder called `krux`:\n```bash\ngit clone --recurse-submodules https://github.com/selfcustody/krux\n```\n\nNote: When you wish to pull updates (to all submodules, their submodules, ...) to this repo, use:\n```bash\ngit pull origin main \u0026\u0026 git submodule update --init --recursive\n```\n\n## Krux (script) (Linux or WSL)\nThe [krux](krux) bash script contains commands for common development tasks. It assumes a Linux host, you will need to have [Docker Desktop or Docker Engine](https://docs.docker.com/desktop/) (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 \u0026 Verify (With Windows + WSL2 + Docker)](https://www.youtube.com/watch?v=Vmr_TFy2TfQ)\n\nTo build and flash the firmware:\n```bash\n# build firmware for Maix Amigo\n./krux build maixpy_amigo\n\n# flash the firmware to Maix Amigo\n./krux flash maixpy_amigo\n```\n\nThe 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.\n\n## Install Krux and dev tools\nKrux uses [Poetry](https://python-poetry.org/) as Python packaging and dependency management. This cmd installs development dependencies like [embit](https://github.com/diybitcoinhardware/embit), [ur](https://github.com/selfcustody/foundation-ur-py) and [urtypes](https://github.com/selfcustody/urtypes), and tools to run [tests](https://docs.pytest.org), review code with [pylint](https://pypi.org/project/pylint/), format code with [black](https://github.com/psf/black) and a lib to help handle i18n translations.\n```bash\npip install poetry\npoetry install\n```\n\nIf you have a problem installing Poetry on Linux OS:\n```bash\n# we considered the name of the venv .krux\npython -m venv .krux\nsource .krux/bin/activate\n```\nThe result will be something like:\n```bash\n(.krux) username:~/directory name$ \n```\nNow you can run normaly the pip of the poetry:\n```bash\npip install poetry\npoetry install\n```\n\nNote: when changing the dependencies in `pyptoject.toml` you need to generate a new `poetry.lock` file using the cmd: `poetry lock --no-update`.\n\n## Format code\n```bash\npoetry run poe format\n```\n\n## Review code\n```bash\npoetry run poe lint\n```\n\n## Run tests with coverage\n```bash\npoetry run poe test\n```\n\nNote: The coverage report will be created at the `htmlcov` folder `file:///path/to/krux/htmlcov/index.html`. \n\nFor more verbose output (e.g., to see the output of print statements):\n```bash\npoetry run poe test-verbose\n```\n\nTo run just a specific test from a specific file:\n```bash\npoetry run pytest --cache-clear ./tests/pages/test_login.py -k 'test_load_key_from_hexadecimal'\n```\n\n## Use the Python interpreter (REPL)\nThis is useful for rapid development of non-visual code:\n```bash\npoetry run python\n```\n```\nPython 3.9.1\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n\u003e\u003e\u003e from krux.key import Key\n\u003e\u003e\u003e Key(\"olympic term tissue route sense program under choose bean emerge velvet absurd\", False).xpub()\n'tpubDCDuqu5HtBX2aD7wxvnHcj1DgFN1UVgzLkA1Ms4Va4P7TpJ3jDknkPLwWT2SqrKXNNAtJBCPcbJ8Tcpm6nLxgFapCZyhKgqwcEGv1BVpD7s'\n\u003e\u003e\u003e\n```\n\n## Run the device simulator\nThis 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).\n\nBefore executing, make sure you have installed the poetry extras:\n```bash\n# This cmd will uninstall other extras\npoetry install --extras simulator\n\n# To install all extras, use:\npoetry install --all-extras\n```\n\nRun the simulator:\n```bash\n# Run simulator with the touch device Amigo, then use mouse to navigate\npoetry run poe simulator\n\n# 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)\npoetry run poe simulator-m5stickv --sd\n\n# Run simulator on the device dock, then use keyboard (arrow keys UP or DOWN and ENTER)\npoetry run poe simulator-dock\n\n# Run simulator with the touch device yahboom, then use mouse to navigate\npoetry run poe simulator-yahboom\n\n# Run simulator on the device cube, then use keyboard (arrow keys UP or DOWN and ENTER)\npoetry run poe simulator-cube\n\n# Run simulator with the touch device wonderMV, then use mouse to navigate\npoetry run poe simulator-wonder-mv\n\n# Run simulator with the touch device tzt, then use mouse to navigate\npoetry run poe simulator-tzt\n```\n\nNote: 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!\n\n```bash\n# ImportError: Unable to find zbar shared library\nsudo apt install python3-zbar\n\n# ImportError: libGL.so.1: cannot open shared object file: No such file or directory\nsudo apt install libgl1\n\n# `pygame.error: No available video device`\n# You are trying to run the simulator on an OS without a GUI (some kind of terminal only or WSL). Try one with GUI!\n\n# Depending on the OS, it may be necessary to install zbar-tools too:\nsudo apt install zbar-tools\n```\n\n### Simulator sequences execution\n\nThis is useful for taking screenshots of device screens to use in documentation:\n```bash\n# Run all sequences of commands on all devices and in all locales (languages) [Linux OS]\ncd simulator\n./generate-all-screenshots.sh\n\n# Run a specific sequence for a specific device's with SD enabled (folder `simulator/sd`)\npoetry run poe simulator --sequence sequences/about.txt --sd\n\n# Sequence screenshots are scaled to fit in docs. Use --no-screenshot-scale to get full size\npoetry run poe simulator --sequence sequences/home-options.txt --no-screenshot-scale\n```\n\n## Live debug a device (Linux)\nIt 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:\n\nIf you've made a fresh build and flashed it to your device, you can connect to the device over serial connection with:\n```bash\nscreen /dev/tty.usbserial-device-name 115200\n```\n\nIf successful, the device should restart and you should see:\n```bash\nK210 bootloader by LoBo v.1.4.1\n\n* Find applications in MAIN parameters\n0: '       firmware', @ 0x00080000, size=XXX, app_size=XXX, App ok, ACTIVE\n* Loading app from flash at 0x00080000 (XXX B)\n* Starting at 0x80000000 ...\n\n\n[MAIXPY] Pll0:freq:XXX\n[MAIXPY] Pll1:freq:XXX\n[MAIXPY] Pll2:freq:XXX\n[MAIXPY] cpu:freq:XXX\n[MAIXPY] kpu:freq:XXX\n[MAIXPY] Flash:0xef:0x17\n[MaixPy] gc heap=0x8029f430-0x8036f430(851968)\ninit i2c:2 freq:XXX\n[MAIXPY]: find ov7740\n[MAIXPY]: find ov sensor\n```\nSome devices like Amigo have two serial ports, check the second one if you don't read data from first.\n\nTo leave `screen` serial monitor press `Ctrl+a`, followed by `k`, then confirm with `y`.\n\n## Live debug a device using MaixPy IDE (Mac or Windows)\nUse [MaixPy IDE](https://dl.sipeed.com/shareURL/MAIX/MaixPy/ide/v0.2.5) to debug the devices. Click on `Tools \u003e Open Terminal \u003e New Terminal \u003e Connect to serial port \u003e 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.\n\n## WDT watchdog\nKrux makes use of MaixPy's [WDT watchdog module](https://wiki.sipeed.com/soft/maixpy/en/api_reference/machine/wdt.html), you can see it [here](src/krux/wdt.py). 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):\n```python\n# Run this everytime you want to stop the watchdog\n\nfrom krux.wdt import wdt\nwdt.stop()\n```\n\nNow, with watchdog disabled, you can use debug the device normally. Also remember to disable the `Settings \u003e Security \u003e 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.\n\n## Create new translations - i18n\nThe project has lots of translations [here](i18n/translations), if you add new english messages in code using `t()` function, you will need to:\n\n```bash\n# Clean unused translations:\npoetry run poe i18n clean\n\n# Create a new translation file in JSON:\npoetry run poe i18n new tr-TR\n\n# Use Google translate to create missing translations, copy them to respective files, review phrases and commas.\npoetry run poe i18n fill\n\n# Create missing translations for a single language. Ex: Brazilian Portuguese\npoetry run poe i18n fill pt-BR\n\n# Make sure all files have this new translated message:\npoetry run poe i18n validate\n\n# Format translation files properly:\npoetry run poe i18n prettify\n\n# Create the compiled table for krux translations.py\npoetry run poe i18n bake\n```\n\n## Fonts\nLearn about how to setup fonts [here](firmware/font/README.md)\n\n## Colors\nUse [this script](firmware/scripts/rgbconv.py) to generate device compatible colors from RGB values (usefull for color themes).\n\n## Documentation\nBefore change documentation, and run the mkdocs server, make sure you have installed the poetry extras:\n\n```bash\n# This cmd will uninstall other extras\npoetry install --extras docs\n\n# To install all extras, use:\npoetry install --all-extras\n```\n\nTo change lateral and upper menus on documentation, see `mkdocs.yml` file on `nav` section. To create or edit translations (TODO: need help!), read [here](i18n/README.md).\n\nCreate the documentation site locally - `http://127.0.0.1:8000/krux/`:\n```bash\npoetry run poe docs\n```\n\n# Inspired by these similar projects\n- https://github.com/SeedSigner/seedsigner for Raspberry Pi (Zero)\n- https://github.com/diybitcoinhardware/f469-disco for the F469-Discovery board\n\n# Powered by\n- [embit](https://embit.rocks/), a Bitcoin library for Python 3 and Micropython\n- [MaixPy](https://github.com/sipeed/MaixPy), MicroPython for K210 RISC-V\n- [MicroPython](https://github.com/micropython/micropython), a lean and efficient Python implementation for microcontrollers and constrained systems\n- [Kboot](https://github.com/loboris/Kboot) and [ktool](https://github.com/loboris/ktool)\n\n# Contributing\nIssues and pull requests welcome! Let's make this as good as it can be.\n\nFeel free to start a [new discussion](https://github.com/selfcustody/krux/discussions) or an [issue](https://github.com/selfcustody/krux/issues) 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).\n\n**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.\n\n# Support\nFor technical support installing or using Krux, you can join our [Telegram chat](https://t.me/KruxDIY). Follow us on [X (Twitter)](https://x.com/selfcustodykrux) or send a message to the [Bitcoin Forum](https://bitcointalk.org/index.php?topic=5489022.0). Also check out the [DIYbitcoin chat](https://t.me/diybitcoin) on Telegram, a broader community of tinkerers, builders and hackers!\n\nPlease do not use issues for support requests. If necessary, you can use our [Discussions](https://github.com/selfcustody/krux/discussions) to post your question here on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselfcustody%2Fkrux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fselfcustody%2Fkrux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselfcustody%2Fkrux/lists"}