Skip to main content

​
Quick Start Guide

The fastest way to try Aeolos is to download a pre-built ISO image and run it in QEMU.

​
Prerequisites

You’ll need a virtualization tool to run the OS. We recommend QEMU for its wide compatibility and excellent x86_64 support. 
# Debian/Ubuntu
sudo apt-get install qemu-system-x86

# Fedora/RHEL
sudo dnf install qemu-system-x86

# Arch Linux
sudo pacman -S qemu-system-x86

​
Download Pre-built Image

1

Get the ISO from GitHub Actions

Navigate to the Aeolos GitHub Actions page.
You’ll need to be logged into GitHub to download artifacts from GitHub Actions.
  1. Click on the most recent successful workflow run (look for a green checkmark)
  2. Scroll down to the Artifacts section
  3. Download os.iso
  4. Extract the downloaded ZIP file to get os.iso
2

Run in QEMU

Once you have the os.iso file, boot it with QEMU:
qemu-system-x86_64 \
  -cdrom os.iso \
  -m 128 \
  -smp 4 \
  -cpu host \
  -M accel=kvm:tcg
  • -cdrom os.iso: Boots from the ISO image
  • -m 128: Allocates 128MB of RAM
  • -smp 4: Enables 4 CPU cores for SMP testing
  • -cpu host: Uses host CPU features (with KVM)
  • -M accel=kvm:tcg: Tries KVM acceleration, falls back to TCG
3

Watch it boot

You should see:
  1. Boot messages: Kernel initialization output
  2. Hardware detection: ACPI, APIC, and HPET initialization
  3. Memory management: PMM and VMM setup
  4. SMP startup: Secondary CPUs coming online
  5. VFS demo: Reading a test file from the initrd
  6. Halt message: The OS will halt with a message about being a work in progress
The OS currently doesn’t have interactive capabilities. It demonstrates initialization, then halts. See kernel/kmain.c:kinit() for the demo task.

​
QEMU Options Explained

The Makefile uses these QEMU flags (from Makefile): 
QEMUFLAGS = -m 128 \
            -no-reboot \
            -no-shutdown \
            -smp 4 \
            -cpu host \
            -M accel=kvm:tcg

Memory

-m 128 allocates 128MB RAM, sufficient for testing

CPU Cores

-smp 4 enables 4 cores to test SMP functionality

No Reboot

-no-reboot prevents automatic restart on triple fault

Acceleration

-M accel=kvm:tcg uses KVM if available, otherwise software emulation

​
Alternative: Run with Serial Output

For debugging or logging purposes, you can redirect serial output: 
qemu-system-x86_64 \
  -cdrom os.iso \
  -m 128 \
  -smp 4 \
  -serial stdio
This sends serial port output (from serial_init()) to your terminal.

​
What You’ll See

When Aeolos boots, it performs these operations:
1

System Initialization

Aeolos x86_64 (alpha)
Built on [date] at [time].
The kernel initializes:
  • Interrupt Descriptor Table (IDT)
  • CPU feature detection
  • Physical memory manager (PMM)
  • Virtual memory manager (VMM)
  • Global Descriptor Table (GDT)
2

I/O Setup

  • Framebuffer initialization for graphical output
  • Serial port (COM1) setup
  • Terminal emulation layer
3

Hardware Discovery

  • ACPI table parsing (RSDP, MADT)
  • HPET timer calibration
  • Local APIC and I/O APIC configuration
  • Virtual filesystem initialization
  • SMP initialization (bringing up secondary cores)
4

First Task

The kinit() function runs as the first kernel task:
void kinit(tid_t tid)
{
    klog_ok("first kernel task started\n");
    
    initrd_init(...);
    
    // Demo: Read a file from VFS
    vfs_handle_t fh = vfs_open("/docs/test.txt", VFS_MODE_READ);
    vfs_read(fh, 4096, buff);
    vfs_close(fh);
    
    vfs_debug();
    pmm_dumpstats();
    
    klog_warn("This OS is a work in progress. The computer will now halt.");
    sched_kill(tid);
}

​
Troubleshooting

If you see KVM-related errors, you might not have virtualization enabled or KVM installed.Solution: Remove the acceleration option:
qemu-system-x86_64 -cdrom os.iso -m 128 -smp 4
This uses TCG (software emulation) which is slower but works everywhere.
The framebuffer might not be initializing correctly.Solution: Try with serial output instead:
qemu-system-x86_64 -cdrom os.iso -m 128 -serial stdio -nographic
GitHub requires authentication to download artifacts.Solution:
  1. Make sure you’re logged into GitHub
  2. Alternatively, build from source instead
This might indicate a triple fault or critical error.Solution: Run with debug options:
qemu-system-x86_64 -cdrom os.iso -m 128 -d int,cpu_reset -no-reboot

​
Next Steps

Build from Source

Compile Aeolos yourself and modify the code

Understanding Aeolos

Learn about the architecture and features
Since Aeolos is in early development, it demonstrates OS concepts rather than providing a functional user environment. Check kernel/kmain.c to modify what the OS does at startup.

Build docs developers (and LLMs) love

Get started for freeTalk to us