# live-bootstrap: Building a Linux System From Auditable Source > live-bootstrap is an attempt at a reproducible, automatic bootstrap from a handful of binary seeds to a working operating system, using a hex0 kernel, a C compiler written in assembly and a set of rules about what may be trusted. It suits people who want to know exactly what code produced their system. **fosslinux/live-bootstrap** — An attempt to provide a reproducible, automatic, complete end-to-end bootstrap from a minimal number of binary seeds to a supported fully functioning operating system. - Repository: https://github.com/fosslinux/live-bootstrap - Stars: 759 · Forks: 63 - Language: Shell - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/fosslinux-live-bootstrap ## The problem statement, which is stricter than it first looks The overarching problem statement is a single question: how can a usable Linux system be created with only human-auditable, and wherever possible, human-written, source code. The two clarifications matter more than the headline. Usable means a modern toolchain, with appropriate utilities, that can be used to expand the amount of software on the system, interactively or non-interactively, so the goal is not a minimal kernel that stops at a shell prompt but a system you can keep building on. Human-auditable is described as discretionary but usually fairly strict. That is the project in one line, and it explains why the effort is large: the constraint is on what you are allowed to trust, not on what you are allowed to build. ## Why bootstrapping a compiler is the hard part The readme explains the difficulty in terms of self-hosting. The core of a modern Linux system is primarily written in C and C++, and those languages are self-hosting, meaning nearly every single C compiler is written in C. Every single version of GCC was written in C. To avoid using an existing toolchain, there has to be a way to compile a GCC version without C, so a less well-featured compiler, TCC, is used, and so on, until you reach a fairly primitive C compiler written in assembly called cc_x86. Going up through that ladder requires a bunch of other utilities as well, the autotools suite, guile and autogen, and each of those has to be matched appropriately to whatever toolchain is available at that level. It is a dependency graph where every node is a program that has to be built by the node below it. ## The files that are not allowed, and the projects doing similar work The project lists the file types it deems unsuitable for bootstrapping. Binaries are out, apart from the seed hex0, kaem and builder-hex0, so those three are the acknowledged exceptions. Pre-generated configure scripts or Makefile.in files from autotools are excluded, which is why the autotools suite has to be part of the ladder rather than shipped. Pre-generated bison and flex parsers, identifiable through a .y file, are excluded for the same reason. Anything downloaded inside a software's own build system that is outside the project's control to verify before use is excluded, and any non-free software must carry an FSF-approved licence. For comparison, the readme says GNU Guix is currently the furthest along project to automate bootstrapping, but notes that many of their packages use non-auditable files, which is the specific gap live-bootstrap is aiming at. ## How the ladder starts, with a hex0 kernel The first thing launched is builder-hex0, described as a minimal kernel written in hex0, which exists in three self-boots. The image names in the QEMU instructions follow the same pattern, with builder-hex0-x86-stage1.img and a hex0 payload written in sequence onto a blank disk, and a stage2 hex0 following it, padded with zeros to the next sector. The first stage is produced by stripping comments out of a hex0 source file and converting the hex text to binary. ```bash sed 's/[;#].*$//g' builder-hex0/builder-hex0-x86-stage1-hex0 | xxd -r -p ``` That is the whole trust anchor. One small assembly-like file, in a notation where the program is literally bytes, is the first thing that runs, and everything above it is built from source by something you can read. ## Three ways to run the bootstrap, and the honest caveat The readme asks you to consider whether you will run this in a chroot, in QEMU, or on bare metal, and says all of it can be automated but not in a trustable way, with the details in the further reading section. The caveat in the quick start is worth reading before anything else: currently, there is no way to perform the bootstrap without external preparations, and the documentation calls this a currently unsolved problem. The chroot route is the most manual, since you create a directory, run the download script and copy the entire contents of seed/stage0-posix into it, all other files in seed, and the steps and distfiles directories, and at least the files listed in steps/pre-network-sources must be in place before the network is available, after which you run the kaem optional seed inside the chroot. The QEMU route needs two blank disk images and a network card model of E1000 with the split kernel irqchip. ## Mirrors, and why the project wants you to run your own Everything else in the bootstrap is fetched over the network, and the mirror is where that happens. The readme is explicit that repackaging distfiles for live-bootstrap is generally permissible, particularly from git repositories, and gives two reasons: live-bootstrap currently supports only tarballs and raw files as input rather than git repositories, and it reduces load on servers. You may use an existing mirror from the project's wiki, in which case you are trusting that mirror's operator to some varied extent. The project would rather you ran your own, and there is a script for that, invoked with a mirror directory and a state directory. ```bash ./mirror.sh path/to/mirror/dir path/to/mirror/state ``` Then you pass the mirror to rootfs.py with the --mirror option. The project also invites you to run a public mirror on a timer with a systemd timer or a cron job, served over HTTP or HTTPS. ## The Python driver, and the manual route it replaces The quick start recommends the Python driver, where you pass the mirror as --mirror to rootfs.py and follow the instructions given by ./rootfs.py --help. The driver uses a variety of userland tools to prepare the bootstrap, which is the practical difference from the manual route: the manual route is a list of copying steps and a chroot invocation, while the driver automates the parts that can be automated. The alternative, spelled out step by step, is to clone the repository, pull the submodules with git submodule update --init --recursive, and then follow the chroot, QEMU or bare metal path. ```bash git clone https://github.com/fosslinux/live-bootstrap git submodule update --init --recursive ``` The distfiles the bootstrap needs are fetched by a separate script, which is what the QEMU instructions mean when they say distfiles can be obtained using ./download-distfiles.sh. ## What the repository contains and what state the project is in The top level shows the shape of the project. There is a builder-hex0 directory for the hex0 kernel source, a seed/ directory holding the seed files including the stage0-posix tree, a steps/ directory with the build steps, a lib/ directory, a substitutes.license file, a LICENSES/ directory, and a REUSE.toml file for licence tracking. The source_manifest.py and rootfs.py scripts sit at the root, along with mirror.sh, download-distfiles.sh, parts.rst and DEVEL.md. The readme points to bootstrappable.org, the Trusting Trust attack as described by Ken Thompson, the GNU Guix bootstrapping manual and CollapseOS as related reading for anyone who wants the reasoning behind the project rather than the instructions for it. The licence is stated in the readme as a Creative Commons Attribution-ShareAlike identifier, while the licence field in the repository metadata is recorded as unknown, so the file is the reference. The repository is not archived and the last push was on 2026-09-17, though it publishes no GitHub releases. ## Conclusion live-bootstrap fits a person who wants to be able to audit the entire chain from binary seed to running system, and who is prepared to spend real effort on mirrors, chroots and QEMU images. It is the wrong tool if you just want a working Linux, since a normal distribution install is far simpler, and it is the wrong tool for a machine with no patience for a multi-stage manual procedure. Before you start, pick a mirror you trust and read the parts.rst document, because the project names the files it considers auditable and that list is the standard your build has to meet. ## FAQ ### What problem is live-bootstrap trying to solve? How can a usable Linux system be created with only human-auditable and, wherever possible, human-written source code. Usable means a modern toolchain that can keep expanding the software on the system, and human-auditable is described as discretionary but usually fairly strict. ### Which files are not allowed in a live-bootstrap build? Binaries apart from the seed hex0, kaem and builder-hex0, pre-generated configure scripts and Makefile.in files from autotools, pre-generated bison and flex parsers, anything downloaded inside a software's own build system that cannot be verified before use, and any non-free software without an FSF-approved licence. ### How do I start a live-bootstrap build? Choose or create a mirror, then pass it as the --mirror option to rootfs.py and follow the instructions from ./rootfs.py --help. Without the Python driver, clone the repository, run git submodule update --init --recursive, and follow the chroot, QEMU or bare metal path. ### Why does bootstrapping a C compiler take so many stages? C and C++ are self-hosting, since nearly every C compiler is written in C, and every version of GCC was written in C. To avoid using an existing toolchain, a less capable compiler, TCC, is used, and the chain continues until it reaches a primitive C compiler written in assembly called cc_x86, with the autotools suite, guile and autogen needing to be matched to the toolchain available at each level. ### Should I run my own mirror for live-bootstrap? The project would prefer it. A local mirror is created with ./mirror.sh given a mirror directory and a state directory, and it suggests running a public mirror on a timer with systemd or cron, served over HTTP or HTTPS, because you would otherwise be trusting the operator of an existing mirror to some varied extent. ## Sources - [fosslinux/live-bootstrap on GitHub](https://github.com/fosslinux/live-bootstrap) - [Issues](https://github.com/fosslinux/live-bootstrap/issues) - [README](https://github.com/fosslinux/live-bootstrap/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fosslinux-live-bootstrap