Minimal-OS

Is a OS made in C and Assembly made for x86_64 processors, It currently runs with 1024MB and tested up to 16GB (I havent tested lower yet)

find roadmap in roadmap.txt or below (might be old or un-synced!)

Hyperlinks

User application developers can find the syscall and SDK integration guide in docs/user-sdk-syscalls.md. Install packages and service definitions are documented in docs/install-and-services.md. The full kernel, boot, storage, networking, process, and build architecture is summarized in docs/system-overview.md. New contributors can use the development workflow, build target reference, and testing guide to navigate and validate changes. 3D graphics: FarcadeGL (the 3D API), its GLSL-style shading language FGSL, and the GPU side in docs/gpu.md (including what hardware rendering on NVIDIA cards needs). An optional browser-accessible XFCE desktop with Firefox is documented in desktop/README.md.

Nvidia firmware setup

NVIDIA firmware for an RTX 20 / GTX 16 card: make gpu-setup (RTX 2060) or make gpu-setup GPU="GTX 1660 Ti", then make mosdesk.

Beatifull logo (i know)

Commands in MinimalOS terminal

General

• help [-c | --classic] Shows grouped, paged command help. Press Enter for the next category or q to exit. Use -c or --classic to use the old list.
• echo [Text] Echoes text back to the terminal.
• clear Clears the terminal.
• sleep [Seconds | milliseconds"ms"] Pauses for seconds or milliseconds.
• systime Shows the current system time.

System information

• info Shows system, CPU, PCI, and memory information.
• cpu Shows CPU information.
• gpu Shows GPU adapters (NVIDIA GTX 10 / RTX 20 and QEMU drivers), VRAM, and capabilities.
• fglcube [seconds] [--shader] FarcadeGL 3D demo: a rotating, lit cube (--shader: drawn with FGSL shaders).
• memsize Returns the size of available memory in MB.
• usage Shows memory and process usage.
• chgres [Width] [Height] Changes the display resolution.

---

Audio related commands

• play [File path] Plays .adi files from the disk.
• stop Stops music or audio playback.
• pause Toggles pause and resume of music or audio playback.
• volume [0 - 100] Sets the system volume.

---

Files and directories

• list, ls [Path] [--recursive] Lists the current or entered path.
• listroot, lsroot Shows the root of the disk, including metadata.
• cd [Path] Changes the current directory.
• mdr [Path] [--hidden] Creates a folder at the entered path.
• insert [File Path] [Text] Creates or replaces a file with [Text].
• read, rd [Path] [--metadata] Reads a file.
• remove, rm [Path] [-r | --recursive] Removes a file or folder.
• meta [Option] [File] Views or edits file metadata.

Storage and packages

• disks, lsblk Lists disks (SATA and NVMe), partitions and filesystems.
• part [Disk] Shows or edits a partition table (MBR or GPT).
  • part <disk> init [gpt|mbr] --yes Writes a new, empty table.
  • part <disk> add <size|rest> [minimafs|esp|fat|biosboot] [label] Adds a partition (sizes like 512M, 20G, 2T).
  • part <disk> del <number> Deletes a partition.
• format [Device] [Drive] [Label] Formats a disk or partition as MinimaFS (up to 16 TiB). Without arguments: the system volume as 0: with system files.
• mount [Device] [Drive] Mounts a volume as N: (for example mount sata1p2 2). Without arguments it lists the mounted drives.
• umount [Drive] Unmounts a drive.
• drives Lists mounted drives and how full they are.
• install [Disk] [--mbr] [--yes] Installs Minimal-OS on a disk so it boots by itself on BIOS and UEFI PCs (see docs/installing.md).
• initdisk Rescans the disks.
• importmusic Copies the built-in music file to the disk as music.adi.
• pkg Extracts or creates a package archive.
  • unzip [Archive] [Target] Extracts to a folder named after the archive by default.
  • zip [File or folder] [lzss | store] Creates a package archive.
• pkginfo [Archive] Displays package information.
  • installpkg [Archive] [Target] Alias for pkg unzip.

During make build-x86_64, the SDK builds minimaSSL.slib, copies it into src/resources/install1, and packages that directory as an embedded install1.mpkg. Running format extracts the package into 0:/etc, so the library is installed as 0:/etc/minimaSSL.slib. The kernel TLS client is linked with the same freestanding minimaSSL crypto sources; the current OS has no dynamic .slib loader, so the filesystem copy is not executable code by itself.

Keyboard and programs

• kbrlayout [set | get | list] Manages keyboard layouts.
• run [File] Runs a .run executable.
• services Lists registered services.

Adding a service

Put a file ending in .service in src/resources/install3. It is packaged automatically and installed to 0:/services when format runs. Services are registered automatically after the boot disk is mounted; no C registration call is needed.

Example src/resources/install3/example.service:

[GENERAL]
name="Example Service"
desc="Starts an example program"
exit=Restart

[STARTUP]
exec="0:/programs/example.run"

Use exactly one [STARTUP] entry. exec can load a .run bundle directly or run a terminal command such as exec="echo service started". script="run 0:/programs/example.run" starts through the command system. Command-style entries run once without PID tracking. The services command lists successfully parsed and registered services.

Diagnostics

• testwrite Runs the MinimaFS write test.
• verifyfile Verifies a file on disk.
• diskusage Shows disk usage.
• trace_on Enables execution tracing.
• trace_off Disables execution tracing.
• trace_stack Shows the execution trace stack.

---

Keyboard related commands

• kbrlayout Handles kbr layout stuff.
  • set [inbuiltlayout | kbr file path] sets the current and default keyboard layout.
  • get Outputs the currently used keyboard layout.
  • list lists all available keyboard layouts.

---

Path formatting

0:/Dir/example.txt

0: is the drive (the system volume; other volumes and partitions are 1:, 2:, ...)

0:/ is the root of that disk or the top directory.

0:/Dir is a folder inside disk 0

0:/Dir/example.txt is a file with .txt suffix which is called "example"

ROADMAP

Last synced 2026 - 11-05, 09:00

X = Done

C = Come back later

N = New plans

V 0.4.00

• Panic screen
• simple audio [C]
• allocator
• startupRoutine
• Processes and ProcessManager
• GRAPHICS!!! 🥳🥳🥳

V 0.4.05

• Better allocator

• Time Scheduler

• Improved scheduler and proc

• Graphics handler (display.h)

• Time handler (time.h)

• Displaying and reading images !limited support!

• Fonts !also a little limited for now!

• USB 1.1

• Keyboard

• Simple Audio !

• File system !!! (MinimaFS)

V 0.4.4X

• Multithreading And Multicore usage
• Services manager
• Syscalls and User layer
• .run executable file

V 0.4.50

• Simple Desktop
• Window Manager
• MinimaFS file browser (within minimal-os)
• Text editor

V 0.4.51

• Golf
• GPU support (not just display adapter)
• FarcadeGL (Minimal-OS Graphics Library)
• Partitions & Larger disk's
• Installer & Disk bootable installs

V 0.4.52

• GPU engine and GLSL style shaders (Pascal)
• Fix various apps.

V 0.4.53

• Webbrowser (Mxplorer)

Usage

To run Minimal-OS (direct iso) download from github releases ( Minimal-OS Downloads ) Then after downloading the .iso file of any version use qemu-system-x86_64 which can be downloaded using the systems package manager or Mingw on windows. And before running the operating system create a disk file for it to use in the same directory as you are running from by using this command fallocate -l 256M sata256.img Then run this command for the suitable configuration for current Minimal-OS support.

qemu-system-x86_64 -cdrom kernel.iso -m 1024M -boot d -d guest_errors,int,cpu_reset,unimp -serial -usb -device usb-kbd stdio \
-audiodev pa,id=speaker -machine pcspk-audiodev=speaker  -audiodev pa,id=audio0 -device AC97,audiodev=audio0 -device ahci,id=ahci \
-drive id=disk0,file=sata256.img,if=none,format=raw -device ide-hd,drive=disk0,bus=ahci.0

Building from Source

1. Download the source code, git clone https://github.com/fsminecrafter/Minimal-OS.git
2. Enter the folder and run the dependency install command (this one is for debian 13, Ubuntu 24.04/26.04 or at least tested on them)

sudo apt update
sudo apt install -y \
  build-essential \
  bison \
  flex \
  libgmp3-dev \
  libmpc-dev \
  libmpfr-dev \
  texinfo \
  libisl-dev \
  wget \
  curl \
  make \
  nasm \
  xorriso \
  grub-pc-bin \
  grub-common \
  mtools \
  qemu-system

3. Run the included gcc / binutils installer

./build_gccbinutils.sh

4. Create a sata256.img file in root of Minimal-OS project folder.

fallocate -l 256M sata256.img

5. Get submodules

git submodule update --init --remote

6. Compile and run using make make run -j$(nproc) If audio doesnt work use either make run-sdl or make run-alsa

To fetch and build MOSDesk and mosWM, include them in the install packages, and boot the desktop-enabled image, run:

make run-mosdesk

This uses the same cross-compiler and sata256.img prerequisites above. The desktop files and mosWM startup service are installed when format is run in Minimal-OS; formatting erases the selected disk, so back up an existing disk before formatting it.

Every MOSdesk build (or make mosdesk-dlr on its own) also writes the whole desktop as a Deliver package, ready for dlr serve:

dist/x86_64/dlr/packages/MOSdesk/       package files + MOSdesk.pkg manifest
dist/x86_64/dlr/packages/MOSdesk.mpkg   the archive clients download

Copy both into 0:/var/dlrd/packages/ on the serving machine and run dlr serve; other machines install it with dlr install MOSdesk (it installs below 0:/, including 0:/services/mosWM.service).

MOSdesk (Minimal-OS Desktop Enviroment)

Now you can find Minimal-OS's's's's's's completly own desktop enviroment (mosWM not included... Im joking)

at MOSdesk

Have fun!

Development For Minimal-OS Via .run Executables

Now you can create .run files for Minimal-OS viaaa... (Drumroll)

Minimal-OS SDK

More info is found on Minimal-OS SDKs Github Page.

Development Stuff

Format / Install Placement

• install1 -> 0:/etc
• install2 -> 0:/programs
• install3 -> 0:/services