Bitloom

Website · Documentation · Releases

A web dashboard and terminal cockpit for everyday Yocto and BitBake development. Build images, follow and diagnose failures, browse recipes by layer, create your own distribution, check SBOMs and vulnerabilities for the Cyber Resilience Act and manage caches: in the browser or in a keyboard-first terminal UI, both on one build service that keeps running when you close them.

Weaving layers, recipes and builds into one workspace.

🔌 Works with how you build

Bitloom does not change your build. Describe it once in a profile (the guided setup proposes it from your project folder) and every feature, from builds and logs to the image explorer, SBOM checks, Studio and the migration assistant, works the same on:

BitBake on the machine	kas	kas-container	Your Docker / Podman image	A running build container	Your launcher script
Poky, split repositories, bitbake-setup	kas shell -c	kas-container shell -c	docker run per command	docker exec	YML=… ./run_build.sh

Launcher scripts need to forward shell -c "<command>", keep standard input open and keep the build folder on the machine: the four-line change and a ready script are in Where your build runs. Bitloom runs next to your build (one install drives them all), or inside your build container: every release has bitloom.pyz, one file to mount or copy, no image rebuild.

🌐 Web dashboard

bitloom --web              # prints the URL (with its access token) and opens your browser

• Builds: live history (new jobs slide in on top), streaming output with search and an errors-only view, progress and ETA, stop, graceful stop and retry, Toaster-style Summary, Sstate reuse, Warnings, Timings and Compare with the previous run, root-cause diagnosis of failures.
• Target picker: the build field lists the image recipes found in your layers, kas target and images already built first.
• Image explorer: what you built, file by file, with sizes, owners, the biggest packages and folders, and the package and recipe behind every file; Services lists what starts on the device (systemd units or SysV scripts in boot order, udev rules, D-Bus), also as bitloom --services; Device tree decompiles the deployed DTBs without dtc and lists enabled and disabled devices; Insights charts where the space goes, licences, what listens on the network and a quick security look (also bitloom --insights). Which recipe installs… answers for any file or package (also bitloom --who-installs /etc/motd), and Change it with an append opens Studio already filled in, starting from the file as it is on the device.
• Add a layer from the OpenEmbedded Layer Index (or any Git URL, through your mirror if you have one) with its dependencies on your release branch: into the kas file, or cloned and added with bitbake-layers. → Projects
• Recipes: every layer with its counts, folders (recipes-core, classes-recipe…) that open on demand, filters for recipes, images, appends, classes and kas files, Use as target.
• SBOM & CRA: release support, SBOM quality gauges, vulnerabilities from sbom-cve-check, cve-check and Grype, exports to Markdown, HTML, CSV, JSON and SARIF, CRA readiness.
• Studio: create a layer, distribution, machine, image, recipe or append one step at a time: every option explained, where the files go and their content shown as you choose, a review of exactly what Create will do, then the next step (build it, use it, add an image to the new layer).
• BitBake assistant: completion of variables, classes, includes, overrides, flags, recipes, features, machines and licences from your own layers, the documentation of the word under the cursor, and the problems a parse would hit (old override syntax, :append without its space, typos) as you write, in Studio and in the terminal editors; bitloom --lint for CI. → BitBake assistant
• Migrate Scarthgap → Wrynose: the rules of the four official migration guides (5.1, 5.2, 5.3, 6.0) checked on your layers, configuration and kas files, the mechanical changes applied with a diff and undo, and the kas file for the new release written next to the current one with its own profile and work directory. Also bitloom --migrate. → Migrate
• Practices: how far the project follows the Yocto best practices (layers, appends, recipes, security, configuration), with the file and line of each finding and how to fix it. Switch rules on or off, change their severity, add your company's own rules in bitloom-practices.json; bitloom --practices fails CI on errors. → Best practices
• Projects: guided setup from a folder (kas files, bitbake-setup workspaces, Poky checkouts, YML=… ./run_kas.sh build launcher scripts, one profile per product), new projects pinned to Scarthgap or Wrynose with kas, or created by bitbake-setup from the official templates where the release has it (in the build container, nothing to install), clone from Git.
• Ctrl+K palette, ? keys, toasts and browser notifications, fifteen themes (System, Bitloom light and dark, Ubuntu, Darcula, Monokai, Nord, Dracula, Tokyo Night, Catppuccin, Gruvbox, Solarized, High contrast), phone and tablet layouts. → Web dashboard

A real run, recorded as it happened (about three times faster): force compile of busybox through a YML=… ./run_kas.sh launcher profile on Wrynose.

Over SSH keep the default loopback address and tunnel it: ssh -L 8765:127.0.0.1:8765 build-server.

⌨️ Terminal UI

bitloom opens the same service in the terminal, for SSH sessions and keyboard-only work: numbers open sections, letters act, / searches, ? lists every key, editors use nano keys (^O, ^X, ^W), and every section key can be changed (Help → c). TUI and dashboard share queue and history, so a build started in one is followed in the other. → Keyboard

✨ Highlights

• Builds that survive the window: a local build service with a serial queue and history; detach, reconnect, follow from the browser or the terminal. Graceful stop and recovery.
• Release aware: one registry knows what each Yocto release can do (SPDX 2.2 or 3.0, cve-check or sbom-cve-check, VEX, fragments, bitbake-setup…), checked in the project's own layers and BitBake; what a release lacks is never offered, and Bitloom says what to use instead. → Release capabilities
• SBOM, CRA and releases: SPDX 3 / 2.2 quality, VEX, vulnerabilities with reports, CRA readiness and timeline, SBOM settings with explanations. → Compliance
• Studio: your own distribution, machines, images, recipes and layers, explained field by field. → Studio
• Developer workbench (F10 in the TUI): variable origins, rebuild signatures, failed-task investigation, devtool, SDK/IDE setup, image comparisons, devices. → Developer
• Daily helpers: notifications when a build ends (desktop, ntfy, Slack/Teams), ETA, run comparison, tmp/work usage. → Guide
• Build server: bitloom --service-install --web runs the build service and the dashboard as systemd user services, with a dashboard URL that survives restarts. → CI and build servers
• CI and build servers: headless --ci matrix with JUnit and annotations, profiles shared by a team, infrastructure checks, device fleet, image matrix, builds started outside Bitloom. → CI and build servers

📥 Install

From the Releases page (replace 1.2.3):

sudo apt install ./bitloom_1.2.3_all.deb      # Debian / Ubuntu, dependencies included

tar -xzf bitloom-1.2.3.tar.gz && cd bitloom-1.2.3   # any Linux / WSL2
python3 -m venv .venv && .venv/bin/python -m pip install .

python3 bitloom-1.2.3.pyz --web               # one file, nothing to install: Python 3.10+ only

Verify with sha256sum --check --ignore-missing SHA256SUMS; bitloom --version prints the installed version. Each release also ships bitloom-1.2.3.spdx.json, the SPDX SBOM of Bitloom and every Python package bundled in the .deb (also installed as /usr/share/doc/bitloom/sbom.spdx.json). Docker or Podman, kas and Yocto are separate tools for real builds. Details: installation.

🚀 Start

./setup-demo.sh            # from a checkout: venv, sample workspace, opens the TUI
bitloom --web --demo       # the dashboard on the Scarthgap and Wrynose samples
bitloom --demo             # the same samples in the terminal (P switches profile)
bitloom --web              # in your project: the guided setup proposes a profile

Animations: tours of the dashboard and the TUI

📚 Documentation

User guide	Profiles and runtimes, workflows, logs, caches, analysis, themes, troubleshooting
Manual testbook	Step-by-step acceptance of every feature and all 82 operations
Command reference · Keyboard	Generated from the code
Validation	Real Scarthgap and Wrynose builds through kas-container and what was verified
Research map	Sources, criticisms of earlier Yocto interfaces and how Bitloom answers them

Browse it locally with python tools/serve_docs.py --port 8000; every page has search (/), a page list, light and dark themes, and a Yocto-docs mode (¶) for those who miss Sphinx.

🛡️ CRA and EN 40000

The CRA harmonised standards are being drafted as the EN 40000 series; prEN 40000-1-3 covers vulnerability handling (receipt, assessment, remediation, communication, tracking). Bitloom does not implement or certify the standard: its compliance views are organised around the build evidence such a process relies on. It is engineering evidence, not legal advice.

🛠️ Development

python3 -m venv .venv && .venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q

Screenshots, the documentation site, release packages and the real kas validation builds are described in Documentation and verification and Build, launch and try the local Yocto workspace.

🤝 Contributing

Issues and pull requests are welcome: read CONTRIBUTING.md first. Report security problems privately, as SECURITY.md explains.

🙏 Inspiration and thanks

Bitloom is inspired by the idea behind yoctui: bringing everyday Yocto and BitBake work into a terminal interface. Thank you to 0xbadcaffe, the author of yoctui, for the inspiration and for sharing the project with the community. Bitloom has its own implementation and interface. Hob, Toaster and knotty taught what to avoid; see the research map.

📄 License

Bitloom is free software, released under the GNU Affero General Public License v3.0 or later with the additional terms in NOTICE.

• Use it freely, at home or at work, in any company, for any project, including commercial products built with Yocto. Running it, internally or for your team, costs nothing and asks nothing of you.
• Change it and share it under the same licence: whoever distributes a modified Bitloom, or offers it to others over a network (the web dashboard), must publish the full source of that version under the AGPL.
• Keep the credits: copies and modified versions keep the NOTICE file and the attribution to the original author, are marked as modified, and do not use the Bitloom name for themselves.

Bundled Python dependencies retain their own licenses. Releases up to v0.0.2 were published under the MIT License and remain available under it.