GentleOS/32 builds a 32-bit hobby kernel from Docker and shows it in a browser tab

A kernel built to run on i386 machines without a host OS

GentleOS/32 describes itself as a hobby operating system for vintage 32-bit PCs, built for tinkering with old hardware on the bare metal. That phrase sets the scope precisely. This is not a Linux distribution or a hosted environment, it is a system that owns the machine from boot, and the audience is people who want to read kernel code written in C and assembly and change it. The primary language in the repository is C, and the top level directory listing shows the structure of a real small operating system: kernel/, lib/, gui/, feat/, apps/, boot/, include/, plus assets/, tools/, misc/ and vendor/. The Makefile compiles the kernel from the directories lib, kernel, gui, feat and apps, which tells you the code is organised as a layered tree rather than a single blob. It is also not the only project by this author: the documentation points to a spin-off called GentleOS/16, which targets even older 16-bit PCs.

Alpine, nasm and binutils inside a container

The build environment is described as a single prerequisite: Docker and Docker Compose, supporting the linux/amd64 platform. The Dockerfile pins that platform and starts from alpine:3.20, then installs the toolchain in one layer: bash, gcc, nasm, binutils, make, perl, mtools, gzip, python3 and py3-pillow. Two entries in that list explain the project better than any prose can. nasm is the assembler, so parts of the system are written in x86 assembly rather than C. mtools is a set of utilities for handling DOS formatted disk images without mounting them, which is how a floppy disk image gets built on a modern host. python3 with py3-pillow points at image generation work, and the compose file mounts the repository into the container so the build sees your edits directly.

One compose command produces the binaries

The build is a single command, documented verbatim in the project. You run the dev service defined in compose.yaml, which builds from the local Dockerfile, uses the image name gentleos32, pins platform linux/amd64, mounts the current directory at /src and runs make by default. The documented invocation adds the parallelism flag:

docker compose run --rm dev make -j4

The resulting binaries land in build/, so that directory is where you look after a successful run. Cleaning the Docker side of things has its own command, which is worth knowing before you start pulling images around:

docker compose down --rmi all

That second command removes the containers and the images, which matters on a machine where you would rather not keep a toolchain container around between sessions.

Two kernels, an initrd and a pair of disk images

The Makefile names the artefacts, and those names describe the design. There are two kernel link targets, kernel-himem and kernel-lomem, each producing an ELF file and a flat binary, with the himem binary named gentleos.bin and the lomem one gentleos.bin in the lomem variant naming, plus a separate initrd named gentleos.rd. The two kernels are built from the same C sources but linked against different linker scripts, misc/kernel-himem.ld and misc/kernel-lomem.ld, so the difference is where the kernel is placed in memory rather than what it does. On top of that sit two disk images, gentleos32-disk.img for a real floppy and gentleos32-web.img for the browser page. The C flags make the era explicit: the kernel compiles with -std=c11 -m32 -march=i386 -O2 and -ffreestanding, meaning no hosted runtime and no C library underneath it.

The browser page is the first thing to try

The documented way to see the system work does not involve a floppy drive. The project states that the easiest way to test is to open gentleos32-web.html in a browser. That file is one of the outputs named in the Makefile, sitting alongside the web disk image, so the build produces both the page and the image it draws. This is the fastest loop available to a newcomer: build once with the compose command, open the page, and interact with the system without hunting for period hardware or a hypervisor configuration. For the tinkering audience the project describes, that removes the largest practical barrier, since the interest lies in the kernel and the applications rather than in the ceremony of booting a 386 machine.

Where the practical limits sit

Several constraints are visible and worth stating plainly. The build is tied to the linux/amd64 platform, so on an Apple Silicon machine the compose file asks the container runtime to emulate that platform, which slows the build and adds a layer you cannot inspect from inside the container. The target hardware is 32-bit x86, and the compiler flags are pinned to -march=i386, so any code you add has to respect that instruction set. The boot code is even more constrained: the boot section compiles with -m16, which fits a real mode boot sector but means the earliest stage cannot use protected mode conveniences. The project also self-describes as a hobby operating system, and the documentation is short, which means the surface area for support questions is small. There is no upgrade or rollback path described anywhere in the documentation, so treat a working tree as the only copy of your work.

GentleOS/16 is the sibling with a different target

The named alternative comes from the same author, and the difference is precise rather than a matter of opinion. GentleOS/16 targets even older, 16-bit PCs, so it runs on hardware that GentleOS/32 cannot boot. If your interest is a 386 or 486 era machine, the 32-bit project is the relevant one. If you own a machine from the 8086 era, the sibling project is the only one of the two that can run. The other difference between the two approaches is where you test them. GentleOS/32 can be exercised from a browser page generated by its own build, whereas a 16-bit target has no such path documented here, so its verification story is tied to actual hardware or an emulator you configure yourself. Neither project competes with a general purpose operating system, so the choice is between the two of them and a classic OS rather than between two feature sets.

GPLv2 for the code, separate terms for the fonts and icons

The licence field on the repository says GPL-2.0, and the documentation states that except where otherwise noted, GentleOS/32 is licensed under GPLv2. That qualifier matters because the vendor directory holds third party assets with their own terms. Icons in vendor/icons8 were sourced from Icons8 using the free license and modified. Fonts in vendor/mona were extracted from the Mona Font project and modified, and assets in vendor/int10h were extracted from The Ultimate Oldschool PC Font Pack and modified, each with its own LICENSE file in the directory. Practically, the code you write on top of the system sits under GPLv2, while the bundled font and icon assets carry the terms of their original projects, and the attribution file records that the assets were modified rather than used untouched.

Editorial conclusion

GentleOS/32 suits people who want to read and modify a complete bare metal operating system without assembling a toolchain by hand, and the Docker path plus the browser test page make that possible on a modern Linux machine. It does not suit anyone expecting a supported general purpose system, since it targets i386 hardware that stopped being mainstream long ago, and the project describes itself as a hobby operating system for tinkering on the bare metal. Before you invest time in it, confirm that your Docker installation can run the linux/amd64 platform, build the image with docker compose run --rm dev make -j4, and check whether the browser test page at gentleos32-web.html gives you the behaviour you need before chasing real hardware.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. luke8086/gentleos32 on GitHub
3. Project website
4. README
5. Releases