📦 bitlaForge has moved into the Forge Suite
Since 22 October 2026 bitlaForge lives in jetomev/forge-suite, with its full history. New releases are tagged
bitlaforge-vX.Y.Zthere, and issues go there too (the open ones moved: #9 → forge-suite#115, #10 → #116, #11 → #117, #12 → #118). This repository is archived: its releases (up to 1.1.0) and issues stay readable, and the AUR packagebitlaforgekeeps working.
Solo Bitcoin mining, honestly framed: start and stop the miner, watch it work, and see your real chance of finding a block. It never starts mining on its own, and it stops the miner when it closes.
🖥 Where it runs: any Linux distribution (it needs
minerd) · no desktop needed · works on a plain text console (a tty).
🛡 Security — every release is GPG-signed and every commit is GitHub-Verified. Where We Stand covers our response to the 2026 AUR supply-chain attacks and how to check us yourself.
Bitcoin mining is a race to guess a number. Mining solo means your computer guesses alone: if it wins, the whole block reward (about 3 bitcoin) is yours; almost certainly, it never wins. On 2 October 2026 a 16-core desktop had about 1 in 36 billion chance per day, or 1 in 98 million per year.
That's the game: a lottery ticket your processor keeps buying. bitlaForge is the screen you watch it from. It runs the miner (minerd, from the cpuminer project), shows what it's doing in plain words, keeps your sessions, and tells you your real odds instead of pretending.
This is a hobby, not income. Mining uses real electricity and makes real heat; expect to spend more on power than you'll ever earn. Do it because it's interesting.
- 🏠 Dashboard: is it mining, how fast (with a chart of the last 30 minutes and a bar per core), is it safe (processor temperature, how much of the processor the miner uses), and your real chance of finding a block today and this year.
- 🔧 Settings as a form, in three groups: Pool & wallet (solo pools picked from a list; your wallet checked as you type, on your computer), Miner (cores to use, a gentle priority), Safety (pause when hot, the lottery odds).
- 📜 Log in plain words: share accepted, share rejected and why, can't reach the pool, paused for heat. Filter, find, follow. Your wallet is never shown.
- 🗂 History: every session, kept between runs, with why it stopped, and the totals since you started.
- 🌡 Pause when hot: the miner is paused when the processor reaches 85 °C (your choice), and goes on by itself when it cools.
- 🎲 The lottery, honestly: once an hour, mempool.space is asked how big the Bitcoin network is. Nothing about you is sent, and a switch turns it off.
- 🛑 The miner never outlives bitlaForge: closing asks first, then stops it; if bitlaForge itself were to crash, the system stops the miner with it.
- 💾 Save with a review: F10 shows every change, old → new, makes a backup first, and keeps everything else in the file.
- 📖 A manual inside the app (Help ▸ Manual), and F1 on any setting opens its page.
- 🐧 Every major distribution, tested with each one's own miner; readable on a plain text console; nothing cut off at 100 columns.
Built on forgekit, the Forge Suite's shared base, so it looks and works like grubForge and alacrittyForge.
The pictures come from the running app (python docs/screenshots/generate.py), with a stand-in miner and an example wallet from Bitcoin's own specification.
Everything it needs to build, run and test, with why, is in docs/PACKAGING.md, measured from the code (the Forge Suite's dependency audit, 2026-10-11).
- Linux, Python 3.11 or newer
python-textual,python-rich,python-tomlkitandpython-forgekit0.10.0 or newerutil-linux(forsetpriv, already on every distribution)minerdto actually mine (see below); bitlaForge runs without it and says how to get it
nog install bitlaforge # KognogOS
nog install cpuminer # the miner itself (minerd)With any other AUR helper: yay -S bitlaforge and yay -S cpuminer.
git clone https://github.com/jetomev/bitlaforge.git
git clone https://github.com/jetomev/forge-suite.git # forgekit lives inside it
cd bitlaforge
python3 -m venv .venv && .venv/bin/pip install textual rich tomlkit
PYTHONPATH=../forge-suite/forgekit .venv/bin/python main.pyA virtual environment is used because most distributions refuse pip install into the system Python.
Tested on 2 October 2026 in a fresh install of each:
| Distribution | How |
|---|---|
| Arch, KognogOS | nog install cpuminer (AUR) |
| openSUSE Tumbleweed | sudo zypper install cpuminer |
| Debian 13, Ubuntu 24.04, Fedora 44 | not packaged: the cpuminer project's own ready-made program (pooler-cpuminer-2.5.1-linux-x86_64.tar.gz), unpacked and installed to /usr/local/bin/minerd. The step-by-step is in the manual (Installing the miner). |
In each, bitlaForge's tests ran, and that distribution's miner was driven through the app: tested, pointed at a pool, stopped on quit (scripts/vm-distro-check.py).
bitlaforge # open bitlaForge
bitlaforge --version # print the version
bitlaforge --help # print the usageNo sudo: bitlaForge only changes its own files (~/.config/bitlaforge/, ~/.local/share/bitlaforge/).
First time: press 2, paste your Bitcoin address into Wallet, press F10 to save; then 1, T to test the miner (10 seconds, one core, nothing sent anywhere), and M to start.
When it closes, the terminal gets a short record: how long it mined, the shares, what was saved, where the run was logged, and a thank-you.
| Key | Does |
|---|---|
| M | start or stop mining |
| T | test the miner (10 seconds, one core, nothing sent) |
| 1 – 5, or Ctrl + the underlined letter (D, S, L, I, H) | Dashboard, Settings, Log, History, and the Help menu (its number again closes it) |
| Tab / Shift+Tab | next / previous field or button |
| Enter | open a list, press a button, confirm |
| Space | flip a switch |
| ↑ ↓ in a number | step through its presets |
| Esc | close a window, or leave a field |
| F10, or S | save settings, with a review first |
| R | read the settings file again (your unsaved changes stay) |
| F1 | help on what is selected |
| / F C | in the Log: find, follow, clear |
| ? | all keys |
| Q, or Ctrl+Q | quit (stops the miner, after asking); not there inside hypeForge Settings |
Letter keys and numbers never act while you're typing in a field; Ctrl + a letter always works. On a plain text console (and some older terminals) Ctrl+I is the same key as Tab, so there 4 goes to History. The manual (Help ▸ Manual, or F1), the keys list (?), Help ▸ About and Help ▸ License open as pages in the window; Esc goes back. Each button shows its key in brackets, like Start Mining (m). The full manual is in bitlaforge/manual/, and inside the app.
hypeForge (the KognogOS desktop) shows bitlaForge as one page of its Settings window. It starts it with a hidden option, bitlaforge --hypeforge (--hypeForge works too), which you never need to type. On that page bitlaForge has no Quit: Q and Ctrl+Q do nothing, and Settings closes it. If the miner is running, or a change isn't saved, bitlaForge asks first, just as its own Quit would, so the miner still never outlives it.
Mining is always your choice. It's real processor load, electricity and heat, so bitlaForge:
- Never starts mining on its own. Only M or the Start button does, and only with a valid wallet.
- Never leaves the miner running. Closing asks first and stops it. The miner is started with a parent-death signal (
setpriv --pdeathsig), so if bitlaForge were killed or crashed, the system stops the miner too. - Pauses for heat when the processor reaches your limit (85 °C by default), and goes on when it has cooled 5 °C.
- Checks your wallet here: a Bitcoin address carries its own check digits, so a typo is caught before it is ever used. Nothing is sent anywhere to check it.
- Never loses your settings to a save: a review first, one backup (the newest 20 kept), a one-step write. A settings file that can't be read is never saved over; the newest backup is offered instead.
A human and AI collaboration. The 1.0 redesign was drawn screen by screen and approved before any code was written: docs/design/v1.0.0-screens.html. The testing/ folder holds the test matrices and results, published on purpose.
Still on the plan from before 1.0:
- Check that the pool can be reached when you save, not only when you start (#9)
- Optionally restart the miner if it stops by itself (#10)
- Switch between saved setups with one key (#11)
- v1.1.0 (#13): the same keys as every Forge app (a number and Ctrl + the underlined letter for every menu entry, Help included; the manual, Keys, About and License as pages); a page of hypeForge Settings with no Quit of its own; buttons that show their key, like Start Mining (m)
- v1.0.0 (#4): rebuilt to match grubForge 2.0; the miner never outlives bitlaForge; real odds; History; pause when hot; the wallet checked; every major distribution
- Earlier releases: docs/ROADMAP.md
The same keys as every Forge app (#13). On 8 October Javier ran the Forge apps inside hypeForge Settings and asked for all six to move together. bitlaForge now gets its menu keys from forgekit 0.10.0, the suite's shared base, instead of writing its own:
- ⌨ A number for every menu entry, Help included: 1 Dashboard, 2 Settings, 3 Log, 4 History, 5 opens the Help menu, and 5 again closes it. The open menu's title stays lit while its list is showing. The bottom bar says 1-5 menu instead of 1-4 screens.
- 🔤 Ctrl + the underlined letter, by Javier's rule: each entry gets the first letter of its name, unless another entry already has it; then the next letter of its name. Help is always H. So Ctrl+D Dashboard, Ctrl+S Settings (was Ctrl+E), Ctrl+L Log, Ctrl+I History (was Ctrl+Y: H is Help, so the next letter), Ctrl+H Help. They work even while you're typing in a field. On a plain text console Ctrl+I is the same key as Tab, so there 4 goes to History.
- 📄 The manual, the Keys list, About and License open as pages in the window instead of windows on top (Javier: "yes, Keys and Manual as pages too"). Help stays lit while they show, and Esc goes back to where you were; in the manual, Backspace goes back to the previous manual page. F1 still opens the manual at the page for what is selected.
- 🧩 A page of hypeForge Settings: started with the hidden option
--hypeforge, bitlaForge has no Quit of its own (Q and Ctrl+Q do nothing) and Settings closes it. If the miner is running, it asks first and then stops it, so the miner still never outlives bitlaForge. The option is left out of--helpand the man page on purpose: it is for hypeForge, not for people. - 🔘 Buttons say their key (Javier, 3 October): Start Mining (m), Test Miner (t), Save Changes (s), Clear (c), Stay (Esc). In the review before saving, S now presses Save.
- 🛠 A rare error at closing is gone: the Dashboard's once-a-second refresh could fire while bitlaForge was closing and end the run with an error message. Found by the new tests.
- 📚 The install-from-source steps now fetch forgekit from the Forge Suite repository, where it lives since 6 October.
Tests: 64 → 86; warnings 0 → 0. Dependency: python-forgekit ≥ 0.10.0. Nothing changes in your settings or history.
bitlaForge, rebuilt, and safe. Every screen was redesigned to match grubForge 2.0, from a plan Javier approved screen by screen before any code was written. Taking stock of 0.2.1 first found that closing it left the miner running, with the processor at full load and nothing on screen to stop it. That and three more are fixed, each with a test:
- 🛑 The miner never outlives bitlaForge (#5): closing asks, then stops it; a parent-death signal stops it even if bitlaForge is killed.
- 📊 Rejected shares are counted (#6): the miner reports them inside its "accepted" line; 0.2.1 always showed 0.
- 🔌 Pools typed as
name:portconnect (#7): withoutstratum+tcp://the miner contacted the pool as a website. Pools are now picked from a list. - 💾 A broken settings file is never saved over (#8): 0.2.1 read a file with one typo as blank settings, and the next save erased the wallet. Saves are reviewed, backed up and written in one step.
- ⌨ Esc leaves a field (#3); readable on a plain text console (#2).
- 🆕 Four screens (Dashboard, Settings, Log, History), the speed chart and per-core bars, the honest odds, pause when hot, the wallet checked offline, Bitcoin only, a manual inside the app,
--version/--help, the closing note. - 🐧 Every major distribution: tested with each one's own miner in Debian, Ubuntu, Fedora and openSUSE VMs; the manual says how to get the miner on each.
Tested by Javier on KognogOS with real mining: "so much better!" Tests: 0 → 64; warnings 0. Dependencies: python-tomlkit (new), python-forgekit ≥ 0.5.1, util-linux; no longer python-tomli-w. Your 0.2.x settings carry over as they are.
The complete history lives in docs/CHANGELOG.md.
This was once BitLA, a Qt desktop prototype from November 2025 with a simulated interface and no real miner behind it. In May 2026 it was rebuilt as a terminal application under the Forge Suite. The original prototype is preserved on the v0.1.0-qt-archived tag; main has been the terminal version from its first commit.
- KognogOS: the distribution the Forge Suite ships with
- forgekit: the shared foundation for the Forge apps, part of the Forge Suite
- nog: tier-aware package manager
- grubForge: bootloader manager
- alacrittyForge: Alacritty's settings
Javier (@jetomev): idea, direction, testing
Claude (Anthropic): co-developer, architecture, implementation
bitlaForge is a collaboration between a human with an idea and an AI that helps build it, one commit at a time. Co-author credit appears in the commits, this README, the man page, the package and the release notes, on purpose.
GPL v3. See LICENSE.
Feedback, bug reports and ideas are welcome via GitHub Issues. If you find bitlaForge useful, a star helps others find it.