GentleOS - Questions and Answers

On this page you can find common questions and answers for GentleOS/32 and GentleOS/16.

General

Why did you build GentleOS?

I first started tinkering with a hobby OS around 2007, thanks to the excellent tutorial by JamesM. I kept coming back to it from time to time, but never had a good idea where to take it.

Then, during the pandemic, I got hooked on, and slightly addicted to, buying for cheap and restoring vintage laptops from local auction sites, often sold in unknown condition by people clearing out their attics.

A few more years later, as they mostly kept lying on a shelf collecting dust, I finally got the idea to take my latest codebase, remove lots of unnecessary features, and turn it into a "fantasy" OS made specifically for tinkering with my collection.

Why are there two versions?

The 32-bit/VGA version was first, as it was derived from an older, 64-bit codebase. Only later I started experimenting with porting it down to 16-bit/CGA.

Since I didn't want to give up either of them, and didn't have a clear idea how to merge them into one, I decided to keep both of them around, while trying to keep their code as close as possible.

What are the future development plans?

Mostly bug fixes, refactoring, adding new apps.

I'm probably going to focus on G/16 since I like the extra constraints of primitive displays and ancient CPUs. I want to keep exploring what fun apps/demos can be done within those limitations.

How were LLMs involved?

First of all, the project originated many years before LLMs went mainstream. Even the latest iteration, called GentleOS, began long before I started using coding agents.

In early 2026 I gradually started using agents for research, scoping new features, code reviews, and bug hunting. However, no code or assets in the repos were taken directly from them.

For once, because I'm pretty opinionated and their raw output is never exactly what I want. But mostly because it would defeat the whole purpose of this project, which is to have fun tinkering, learning and creating.

All the final output was carefully crafted by me, with proper understanding, and intention to be easy to follow by fellow humans. Even at the cost of being less advanced, having less apps, being less optimized, etc.

How to contribute?

I'm making this project just for fun and sharing it as-is. I don't take requests for new features nor accept pull requests.

However, if you manage to boot GentleOS on any cool hardware, or otherwise do anything interesting with it, please drop me an email!

Are the photos real? The screen on my device doesn't look that good.

All the photos are real. They were taken with an iPhone 16, lit using a softbox, and slightly enhanced with GIMP (cropping, white balance, exposure, etc).

GentleOS/16

How to compile GentleOS/16?

The only prerequisite is DOSBox, the entire toolchain (OpenWatcom, NASM, Perl) is included in the repo.

To build GentleOS, start DOSBox from the source directory and run the following commands: 

Z:\>MOUNT C .
Z:\>C:
C:\>ENV
C:\>AUTOGEN
C:\>WMAKE

How to add images to the gallery and songs for the player?

Songs must be saved in the custom SPK file format.

Images must be saved in the ascii-encoded monochrome PBM format, and must not exceed 320x166px.

To add songs and images to the system, put them in usrmedia/ and follow the compilation steps from the question above.

If you run out of space, you can delete some of the bitmaps in vendor/misc/

How to speed up compilation?

In the DOSBox config file (the path is printed on launch), try setting cycles=fixed 99999 in the [cpu] section. Despite the name, max is not the fastest mode.

You can also try installing Turbo C 2.01 to C:\TMP\TC and run WMAKE TC=1. It's much faster than the default OpenWatcom compiler, but also generates larger and slower binaries.

How to boot GentleOS/16 in DOSBox?

Run BOOT GT16FD14.IMG to boot it as a standalone system, or GT16.COM to start it like an app.

How to boot GentleOS/16 on a real PC?

You can raw-write (e.g. using dd) GT16DISK.IMG to a 1.44M/720K/360K floppy, HDD or USB flash disk, and use it for boot.

Note, writing the image to a disk will erase its previous content, please be careful!

How to start GentleOS/16 from DOS?

Copy both GT16.COM and GT16.DAT to the same directory and run the former. You can press Shift+Q to return to DOS.

What does "timer unavailable" mean?

Your device doesn't trigger timer interrupts which drive some of the apps. On certain devices, e.g. Sharp PC-3000, it can be fixed by disabling low-power mode in the device settings.

GentleOS/32

How to compile GentleOS/32?

The only prerequisites are Docker & Docker Compose, supporting linux/amd64 platform.

To compile GentleOS/32, run: 

docker compose run --rm dev make

To test it, open gentleos32-web.html in your web browser.

How to boot GentleOS/32 on a real PC?

You can raw-write (e.g. using dd) gentleos32-disk.img to a 1.44M/720K floppy, HDD or USB flash disk, and use it for boot.

Note, writing the image to a disk will erase its previous content, please be careful!

How to boot GentleOS/32 using GRUB 2?

If the native bootloader doesn't work, or if you already have GRUB 2 installed, you can download gentleos.bin and gentleos.rd files, and then use the following entry: 

menuentry "GentleOS/32" {
    multiboot /gentleos.bin
    module /gentleos.rd
}

Optionally you can request higher resolution by adding a command like set gfxpayload=1024x768x8 at the end. Only 8bpp VESA video modes are supported with that.

How to boot GentleOS/32 using GRUB4DOS?

Does it support a serial mouse?

Yes, as long as it's compatible with the Microsoft serial mouse protocol. You can turn it on in the bootloader menu, or later by pressing Ctrl+Shift+S.

How to add files?

Additional assets like wallpapers and songs can be provided using an initial RAM disk (initrd). To create an initrd and automatically install in a disk image, run: 

uv run tools/mkinitrd.py [FILES] -d gentleos32-base.img

The initrd replaces the one already present in the image. Use option -a to also include all the default assets shipped with the prebuilt images.

Certain emulators, including v86, only accept disk images which follow the geometry of physical disks. Use option -p to automatically pad the final image with zeros to the right size.

If you're using a 3rd-party bootloader like GRUB, use option -o gentleos.rd to save the initrd to a separate file.

How to add a wallpaper?

To add a wallpaper, save it in PNG/JPG/GIF/BMP/PBM/PPM format and add to initrd.

Three kinds of wallpapers are supported:

In planar video mode (the default one), wallpapers are supported but only rendered using the first 16 colors.

For best results, in GIMP you can use an indexed mode with the provided vga-256.gpl and vga-16.gpl color palettes.

How to add a song?

Songs need to be saved in the custom SPK file format and added to initrd.