Documentation

TermuOS

TermuOS is a lightweight, open-source x86_64 operating system, built for learning kernel development and low-level programming. It boots through Limine into a kernel with its own memory manager, scheduler, virtual filesystem, drivers, shell, and an early GUI toolkit called Luna.

This page covers building it from source, what's where in the repository, the commands available at the shell prompt, and how the kernel is put together layer by layer.

Architecture: x86_64 Languages: C, C++, Assembly Build: Make Boot: Limine

Requirements

TermuOS builds on Linux. You'll need a cross-capable C/C++ toolchain, an assembler, an ISO builder, and QEMU to run the result. On Debian or Ubuntu:

shell

sudo apt install clang nasm make xorriso qemu-system-x86

clang — compiles the kernel's C and C++ sources.
nasm — assembles the low-level boot and context-switch routines.
make — drives the whole build.
xorriso — stitches the kernel and Limine into a bootable ISO.
qemu-system-x86 — runs the ISO without touching real hardware.

Building

Clone the repository and build it with make. The Makefile pulls in the vendored Limine bootloader, compiles the kernel, and produces a bootable termuos.iso in the project root.

shell

git clone https://github.com/TermuOS-Project/TermuOS.git
cd TermuOS
make

Tip: a clean rebuild after pulling changes is usually make clean && make — useful if you've touched anything under limine/ or the linker scripts.

Running in QEMU

Once termuos.iso exists, boot it straight into an emulated machine:

shell

make run

This drops you at the TermuOS shell prompt after the boot log finishes. From here, every command below is available — try help first.

Project structure

The repository is organized by subsystem, mirrored under kernel/:

kernel/ # the kernel itself arch/ # x86_64-specific code: GDT/IDT, paging, interrupts drivers/ # storage, input, RTC, serial, video, net fs/ # VFS, TFS (native filesystem), ramfs mm/ # physical/virtual memory management, heap sched/ # thread scheduler, context switching proc/ # processes, ELF launcher ob/ # kernel object manager ipc/ # inter-process communication net/ # IP stack, ARP shell/ # the built-in terminal shell luna/ # windowing system & widget toolkit lib/ # freestanding libc-ish helpers, C++ support user/ # syscall interface io/ # low-level I/O helpers apps/ # small userspace programs, e.g. "hello" limine/ # vendored bootloader tools/ # build & image-creation tooling assets/ # logo & project assets

Shell commands

TermuOS boots straight into its own shell — no login, no userland init, just a prompt over the kernel. It supports quoting, argument parsing, and a fixed set of built-in commands:

Command	What it does
help	Lists every available command.
clear	Clears the terminal.
echo	Prints its arguments back out.
uname	Prints kernel and build information.
uptime	Shows time since boot.
mem	Reports memory manager statistics.
threads / ps	Lists scheduler threads and processes.
pwd / cd / ls	Navigate the virtual filesystem.
cat / write / touch	Read, write, and create files.
mkdir / rm	Create and remove files or directories.
mkfs	Formats a disk with TFS, TermuOS's native filesystem.
ifconfig / ping / arp	Inspect and use the network stack.
smtp	Sends mail over the built-in network stack.
pid / sleep / yield	Inspect and control the current thread.
run / kill	Launch and terminate a program by path or PID.
obdir	Lists live kernel objects tracked by the object manager.
luna	Starts the Luna windowing system.
reboot / shutdown	Power-cycles or halts the machine.

Run help at the prompt at any time for the exact, up-to-date list — commands are added as subsystems land.

Kernel architecture

TermuOS follows a fairly classic monolithic layout: everything runs in ring 0, and subsystems are separated by directory and header boundaries rather than by process isolation. Roughly, from the hardware up:

Boot & arch

Limine loads the kernel image and hands off control along with a memory map and framebuffer. kernel/arch sets up the GDT, IDT, and interrupt handling for x86_64 before anything else runs.

Memory

The physical memory manager (pmm) tracks free pages from the Limine memory map. The virtual memory manager (vmm) builds page tables on top of it, and a kernel heap (heap) layers malloc-style allocation over both.

Scheduling

A thread scheduler in kernel/sched handles preemptive multitasking, with the actual register-level context switch written in x86_64 assembly for correctness and speed.

Storage & filesystems

An ATA driver talks to disk hardware; a VFS layer sits above it and can mount either TFS — TermuOS's own on-disk filesystem — or an in-memory ramfs, giving the shell a single, uniform way to open, read, and write files regardless of backing store.

Drivers

Keyboard and mouse input, the real-time clock, a serial console for debugging, framebuffer video with a text terminal renderer, and a virtio network device over PCI all live in kernel/drivers, each behind a small, focused header.

Processes & objects

kernel/proc adds process structure and an ELF launcher on top of threads, while kernel/ob is a lightweight object manager that gives kernel resources — files, processes, and the like — stable, listable handles.

Shell

The shell in kernel/shell is the default entry point after boot: it parses input, dispatches to built-in commands, and is the primary interface for everything above.

Luna GUI toolkit

Luna is TermuOS's early windowing system, started from the shell with the luna command. It's organized like a small, self-contained GUI framework living inside the kernel:

Desktop & window manager — desktop/wm.hpp and desktop.hpp own window placement and compositing.
Taskbar & start menu — persistent chrome for launching and switching between windows.
Widgets — buttons, labels, text fields, and a small graphics helper (gfx) that windows and widgets draw through.

It's early — the roadmap item "GUI" on the home page tracks where this is headed next — but it already runs windows with real input focus on top of the same kernel that serves the shell.

Contributing

Contributions, bug reports, and feature suggestions are always welcome. The project builds via GitHub Actions on every push and pull request, so a good first step is making sure make succeeds locally before opening a PR.

Fork the repository and create a branch off main.
Make your change, keeping subsystem boundaries in mind — see Kernel architecture above.
Confirm make and make run still work.
Open a pull request describing what changed and why.

For anything larger — a new driver, a filesystem change, work on Luna — opening an issue first to talk through the approach is welcome.

License

TermuOS is licensed under the MIT License. You're free to use, modify, and redistribute it, including commercially, provided the license and copyright notice are preserved. See LICENSE in the repository for the full text.