Skip to main content

​
Quick Start Guide

Get Aurora OS running instantly in your browser or build a native bootable ISO for real hardware.

​
Browser Runtime (Instant)

The fastest way to experience Aurora OS — no installation required.
1

Open the Runtime

Open wasm-runtime/pwa/index.html in any modern browser:
cd wasm-runtime/pwa
python3 -m http.server 8000
# Open http://localhost:8000 in your browser
Or simply open the file directly:
open wasm-runtime/pwa/index.html  # macOS
xdg-open wasm-runtime/pwa/index.html  # Linux
start wasm-runtime/pwa/index.html  # Windows
2

Watch the Boot Sequence

You’ll see a real boot sequence:
  1. BIOS POST — Hardware initialization
  2. Bootloader — Loading kernel into memory
  3. Kernel Init — Subsystem initialization:
    • GDT, IDT, PIC setup
    • Physical memory allocator
    • Paging and heap
    • VFS and tmpfs mount
    • Process scheduler
  4. Login Screen — User authentication
The BPE/U (Browser Processing Engine/Unit) emulates a complete virtual CPU, giving you a genuine OS experience.
3

Create Your Account

First-time users see the OOBE (Out-of-Box Experience):
  • Choose a username (2-16 characters)
  • Set a password (8+ characters)
  • Accounts persist using OPFS (Origin Private File System) + WebCrypto
Your data is stored locally in your browser. Clearing browser data will require creating a new account.
4

Enhance Your Experience

For the best experience:
  • Press F11 for fullscreen mode
  • Press Shift + ? to see all keyboard shortcuts
  • Explore apps from the dock or press the ▲ AURORA button

​
Keyboard Shortcuts

Master these essentials for efficient navigation:
ShortcutAction
Super + TOpen Terminal
Super + FOpen Files
Super + BOpen Browser
Ctrl + QClose active window
Alt + TabSwitch between windows
Super + DShow Desktop (minimize all)
ShortcutAction
Super + 1Switch to Workspace 1
Super + 2Switch to Workspace 2
Super + 3Switch to Workspace 3
Super + 4Switch to Workspace 4
ShortcutAction
Super + LLock screen
Ctrl + /Show keyboard shortcuts
F11Toggle fullscreen
Ctrl + Alt + TOpen new terminal
Super key is Cmd on macOS or Win on Windows/Linux.

​
Native Build

Build a bootable ISO that runs on real x86_64 or ARM hardware.
1

Install Dependencies

You’ll need a cross-compiler toolchain:
sudo apt update
sudo apt install -y build-essential nasm xorriso qemu-system-x86 \
  mtools grub-pc-bin grub-efi-amd64-bin

# Install cross-compiler
sudo apt install -y gcc-x86-64-elf binutils-x86-64-elf
See docs/dev-setup.md for detailed toolchain setup.
2

Install Rust Toolchain

Aurora uses Rust for capability management:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add x86_64-unknown-none
3

Build the Kernel

make build
This compiles:
  • C sources from kernel/src/ (VFS, scheduler, memory, networking)
  • Assembly from kernel/arch/ (GDT, IDT, syscall entry)
  • Rust crate aurora-caps for capability tokens
  • Links everything into dist/aurora-kernel.elf
Expected output:
[RUST] Building aurora-caps...
[RUST] done → rust/caps/target/x86_64-unknown-none/release/libaurora_caps.a

AURORA OS kernel built → dist/aurora-kernel.elf
4

Create Bootable ISO

make iso
This:
  1. Creates ISO filesystem structure in dist/iso/
  2. Copies kernel ELF to dist/iso/boot/
  3. Adds Limine bootloader config
  4. Generates dist/aurora-os.iso with xorriso
Aurora uses the Limine bootloader for UEFI and legacy BIOS support.
5

Boot in QEMU

Test your build in a virtual machine:
make run
QEMU options used:
  • -cdrom dist/aurora-os.iso — Boot from ISO
  • -m 128M — 128MB RAM
  • -serial stdio — Kernel logs to terminal
  • -display sdl — Graphical output
  • -no-reboot — Halt on panic
You should see:
[Limine] Loading kernel...
AURORA OS v0.1.0
[ OK ] GDT, IDT, PIC
[ OK ] Physical memory (128 MB)
[ OK ] Paging (4-level)
[ OK ] Heap allocator
[ OK ] VFS + tmpfs
[ OK ] Process scheduler
[ OK ] Init process (PID 1)
init: AURORA OS fully operational

​
Build Targets

Available Makefile targets:
​
make build
Target
Compile kernel ELF binary
​
make iso
Target
Create bootable ISO image
​
make run
Target
Boot in QEMU with graphical output
​
make run-ci
Target
Headless boot for CI/CD pipelines
​
make test
Target
Run unit tests and QEMU boot validation
​
make wasm
Target
Build WebAssembly kernel bridge with Emscripten
​
make clean
Target
Remove all build artifacts

​
Testing Your Build

make test
Runs:
  • Unit tests for kernel subsystems
  • ELF structure validation
  • QEMU boot test (headless)
All tests must pass before deploying.

​
What’s Next?

Explore Features

Learn about the BPE/U engine, agentic runtime, and UI/UX polish

Read Architecture

Understand kernel design decisions and subsystems

API Documentation

Browse syscalls, IPC, and development guides

Contributing

Join the community and submit your first PR
Having issues? Check docs/browser-limitations.md for browser-specific quirks.

Build docs developers (and LLMs) love

Get started for freeTalk to us