BareMetal OS: a build script for an exokernel written in x86-64 assembly

The repository is the build script, not the operating system

This repository is a build script for BareMetal OS and its related utilities. That single sentence in the project description sets the expectation correctly, because the top level of the repository contains very little else: a README, a LICENSE, a .gitignore, an editor config, a GitHub directory, a bochs.cfg file, an images directory and one shell script named baremetal.sh.

The operating system itself lives in five separate projects, and the README lists them with what each one does.

Pure64 is the software loader. BareMetal is the kernel. Monitor is a simple command line interface. BMFS is the BareMetal File System utility. BareMetal-Demo holds various demo programs.

That split is the design, not an accident of packaging. A loader, a kernel, a userspace shell, a filesystem tool and a set of demos are separate codebases with separate repositories, and this script is the thing that pulls them together into a bootable disk image. It is the equivalent of a top-level Makefile or a build orchestrator for a much larger system than the script itself.

The system itself is described as exokernel-based and crafted entirely in x86-64 assembly, designed to provide what the README calls unparalleled levels of flexibility and efficiency. The stated mechanism is exposing hardware resources directly to applications, which lets developers tune their software for specific tasks, and the minimalist exokernel design is said to minimise the overhead imposed by traditional operating systems.

The primary language of this repository is recorded as Shell, which is accurate: the deliverable here is a script that orchestrates the other five projects.

The audience is a systems programmer. This is a project to read and modify an operating system, not a product to install on a laptop.

The toolchain is NASM, QEMU, GCC, Git and mtools

The prerequisites are specific and the script assumes all of them are present, which is why the setup step exists.

NASM is the assembly compiler, used to build the loader and the kernel as well as the applications written in assembly. QEMU is the computer emulator, for anyone who plans to run the OS for quick testing. GCC is the C compiler, for building C and C++ applications. Git is needed to pull the source code from GitHub. mtools provides the utilities to access DOS FAT32 disk images in Unix, which is how the script writes into the image.

On a Debian-based Linux system the whole set installs with one command.

	sudo apt install nasm qemu-system-x86 gcc git mtools

On macOS the equivalent goes through Homebrew.

	brew install nasm qemu gcc git mtools

The README is explicit that the script depends on a Debian-based Linux system such as Ubuntu or Elementary, and that macOS is also supported to build and test the OS and the assembly applications if you are using Homebrew.

The mtools dependency is the one that reveals how the build works. Because the target filesystem is FAT32 and the build happens on a Unix-like system, the script uses mtools to put files into the disk image rather than needing to mount a loop device. That is why the build does not require root on the build machine, and why the same script produces an image you can then write to a real disk.

The toolchain is deliberately minimal. There is no linker, no build system, no package manager, no cross compiler in the usual sense. NASM assembles, GCC compiles the C applications, and everything is assembled by hand into a flat image.

setup, build, install, demos, run: the whole loop is five commands

The workflow is short enough to hold in your head, and the script's subcommands map onto the stages of producing a bootable image.

The first step is a clone followed by the setup command.

	git clone https://github.com/ReturnInfinity/BareMetal-OS.git
	cd BareMetal-OS
	./baremetal.sh setup

The README states that the setup command automatically runs the build and install functions, and that once setup is complete you can execute the run command to verify that everything installed correctly. So setup is the fast path for a first attempt, and the individual commands below are the manual route.

The build command produces the disk image.

	./baremetal.sh build

It builds the boot sector, the loader, the kernel and the simple command line interface to the disk image. There is one documented extension: if you want to attach your own binary to the end of the kernel, you pass the filename, so a call like build with a binary argument appends your own code to the kernel image.

The install and demos commands push content into that image.

	./baremetal.sh install

	./baremetal.sh demos

The install command installs the software to the disk image, and the demos command installs the demo programs to the disk image.

The run command then starts it in an emulator.

	./baremetal.sh run

The separation between build, install and run is the useful part of the design. The image is a build artefact you can inspect, copy and re-install into, and the demos are optional content rather than part of the system. The git clone of five projects also means the components are pulled at their own revisions, so a failure halfway through the build is a failure in one component rather than a corrupted tree.

QEMU, VMware, VirtualBox and Bochs, each with a different target format

The script offers one run command per virtual machine format, and the differences between them are not cosmetic.

QEMU is the default path, and there are two variants. The plain run command starts it, and the run-uefi variant boots through UEFI instead of BIOS, which matters because the image supports both boot paths. A third command, run-2, launches a cloned second instance, and the README explains why: it is useful for testing network connectivity between QEMU systems.

	./baremetal.sh run

	./baremetal.sh run-uefi

	./baremetal.sh run-2

VMware and VirtualBox have their own commands, because each needs a different image format.

	./baremetal.sh vmdk

	./baremetal.sh vdi

The VDI command carries two notes. The script rewrites the disk ID of the VDI file to avoid the disk warning in VirtualBox, and the Chipset Type for the VirtualBox virtual machine must be ICH9. That second one is a hard requirement, and getting it wrong produces a machine that does not boot.

Bochs is not driven through the script at all. It is started directly with its own configuration file.

	bochs -f bochs.cfg

The notes for Bochs are about portability of that configuration file. It was created for a Linux-based system, and the display library is set to use the x X Windows backend with the GUI Debugger by default, while on macOS or Windows you need to use sdl2 with no additional options. The file paths for romimage and vgaromimage also have to be updated if the Bochs BIOS files live somewhere else.

So the script covers the mainstream emulators, and the one that needs hand-editing is the one that emulates the hardware most directly.

The supported hardware list is short, and that is the honest scope

The README lists the supported hardware, and the list is short enough to be useful rather than aspirational.

For the CPU, it is multi-core on 64-bit x86 systems from Intel or AMD. The buses are PCIe and PCI. The network device is Virtio-Net, and the storage device is Virtio-Blk. For human interface devices, only the PS/2 keyboard is listed.

Every one of the I/O devices is a Virtio interface except the keyboard. That is a significant constraint, and it is the clearest statement of the project's stage. Virtio is the paravirtualised interface that hypervisors expose, so the disk and network support is aimed squarely at virtual machines. A physical machine with an ordinary SATA controller or an Intel NIC is not in the list, which is what the note about some physical hardware configurations possibly not working correctly is about.

The single input device is a further narrowing. There is no USB keyboard, no mouse, no graphics output device in the list, no audio, no printer, no serial, and no PCI VGA. The only human interface is a PS/2 keyboard, which is a legacy connector, and the display situation is implied rather than listed.

For booting on real hardware, the README describes BIOS and UEFI as supported, with the requirement that secure boot in UEFI mode must be disabled because the software is not signed. You may need to press DEL or F12 on power-up to select the boot drive. Booting from a floppy or a USB drive works, and for BIOS-based floppy boot and UEFI-based USB booting there is a RAM drive image loaded that contains the demo programs.

The floppy path is the simplest. You write the floppy.sys image to a diskette and boot from it. The hybrid disk image is the general path.

	dd if=baremetal_os.img of=/dev/sdc

That baremetal_os.img file is a hybrid disk image supporting both BIOS and UEFI systems, and the README puts a caution next to it: doublecheck that you are writing the disk image to the correct disk. For the UEFI USB route, you copy the BOOTX64.EFI file to the EFI/BOOT directory on a USB drive and boot from it.

Where BareMetal OS is the wrong tool

The first wrong-tool case is anything that needs to be a general purpose or production operating system. An exokernel that exposes hardware resources directly to applications is a research and teaching substrate. It has no user-facing generalisation, no scheduler worth the name, no security model, and the hardware list shows exactly how narrow the target is.

The second case is a machine with ordinary hardware. Because the storage and network support is Virtio-Blk and Virtio-Net, and because the only input device is a PS/2 keyboard, real consumer hardware is largely out of reach. Writing the image to a disk and expecting it to boot on a laptop with an Intel NIC and a SATA controller is the case the README's own caution is about.

The third case is a team that wants a maintained system. The repository has no GitHub releases, the primary language here is Shell, and the last push was on 2026-04-16. The README notes that some physical hardware configurations may not work correctly, and it points at the development status of the project, which is a fair signal that the system is not finished.

There is a second cost that is easy to overlook. Because every component lives in its own repository and the build script pulls them, understanding a failure means understanding which of five codebases is responsible. The build is fast, but it is not hermetic, and there is no vendored snapshot of the tree.

On licensing, the project is MIT with a LICENSE file at the root, which is a permissive grant with no copyleft obligation on anything you write against it. For an operating system research project that matters less than it would for a product, but it means nothing stops you from taking the kernel and building something of your own on top.

Editorial conclusion

BareMetal OS suits a systems programmer who wants to read and modify an exokernel written in assembly, since the component split is clean and the build script exposes every stage from boot sector to disk image. It does not suit a team that needs a general purpose operating system, a production system, or a machine with real hardware drivers, because the driver support is limited to what the README lists. Before running it, install the toolchain the script expects, and remember that the last push was on 2026-04-16, which is over six months ago, with the explicit warning that some physical hardware configurations may not work correctly.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. ReturnInfinity/BareMetal-OS on GitHub