Skip to content
Bare-Metal x86_64 Operating System  ·  UEFI / BIOS Boot

SynapseOS A complete OS built from nothing.

No libc. No POSIX. No runtime dependencies. SynapseOS boots from UEFI firmware and delivers a full graphical desktop, web browser, filesystem, networking stack, and TLS cryptography — all running at ring 0 in a single kernel image.

📄 Read the Docs ⚙ Get SynapseOS 🚀 Get Started
SynapseOS — serial console
══════════════════════ SynapseOS ══════════════════════
✓ Serial initialized.
✓ IDT + PIC installed. Interrupts masked.
✓ Limine revision check passed.
✓ Kernel phys base: 0x0000000001000000   virt: 0xFFFFFFFF80000000
✓ HHDM offset: 0xFFFF800000000000
✓ ACPI RSDP parsed. MADT found.
✓ Framebuffer: 1920×1080 pitch 7680
✓ GUI compositor initialized. Double-buffer ready.
✓ Intel HDA found. Boot sound queued.
✓ STI — interrupts enabled.
✓ FAT32 mounted. VFS populated.
✓ RTL8139 NIC online. MAC: 52:54:00:12:34:56
→ Launching desktop…
Ring 0
Execution Model
192 MB
Kernel Heap
TLS 1.2
Secure Networking
X25519
Key Exchange
FAT32
Filesystem + LFN
32
Max Concurrent Tasks
Graphical Desktop

A full desktop environment,
straight from the kernel.

SynapseOS boots directly into a double-buffered compositor with macOS-style windows, a dock, desktop icons, and a menu bar — rendered entirely in ring 0 with no display server, no GPU driver abstraction, and no intermediate framework.

  • 🖼

    Double-Buffered Compositor

    Back-buffer → physical framebuffer swap eliminates visible tearing at any resolution.

  • 🪟

    Window Manager

    Traffic-light buttons, draggable windows, Z-order focus switching. Up to 16 simultaneous windows.

  • 🎨

    Catppuccin Mocha Theme

    The same palette used by the OS itself — deep navy backgrounds, soft pastels, and smooth gradients.

  • 📐

    EDID-Aware Scaling

    UI scale factor computed from monitor physical dimensions queried via the Limine framebuffer EDID response.

SynapseOS Desktop — 1920×1080
⟨S⟩ File Edit View Window 10:42
📁
Documents
🖼
Pictures
Terminal — /home/alice
alice@synapse : ~ $ ls /
boot  etc  home  EFI
alice@synapse : ~ $ ping 10.0.2.2
ICMP echo-reply from 10.0.2.2 seq=1
🌐
💻
⚙
🎵
📁
SynapseOS Navigator

A browser built
inside the kernel.

Navigator is a fully functional multi-tab web browser running in ring 0. It parses HTML, applies CSS, lays out the DOM, and renders to the framebuffer — with TLS 1.2 HTTPS support powered by a custom X25519 + AES-128 implementation.

  • 🔒

    HTTPS via TLS 1.2

    X25519 key exchange, AES-128-CBC, HMAC-SHA256. Full TLS record layer over TCP sockets.

  • 🌐

    HTTP/1.1 Client

    Persistent connections, chunked transfer encoding, redirect following, status codes.

  • 📄

    HTML + CSS Engine

    Tokenizer, DOM tree, CSS cascade, block/inline layout engine, framebuffer renderer.

  • 🗂

    Multi-Tab Interface

    Tab bar, address bar with editing, back/forward history, status bar with progress indicator.

Navigator
synapseos.io
New Tab
← → ⟳
🔒 https://synapseos.io/docs
SynapseOS Documentation
Bare-Metal x86_64 OS
for modern developers
SynapseOS is a self-contained kernel that boots from UEFI and provides a complete graphical environment...
Read Docs
Dev Guide
Done TLS 1.2 · AES-128-CBC-SHA256
Network Stack

Ethernet to TLS,
zero dependencies.

From the RTL8139 NIC driver at the bottom to the TLS 1.2 client at the top, every networking layer in SynapseOS is hand-written kernel C. No lwIP. No mbedTLS. No external libraries.

  • 🔌

    RTL8139 NIC Driver

    PCI scan, MAC read, ring buffer TX/RX, IRQ handling.

  • 📡

    ARP / IPv4 / ICMP

    ARP cache, echo reply/originate, IPv4 checksum, full packet build/parse.

  • 🔗

    TCP Sockets

    BSD-style sys_socket/connect/send/recv API. Blocking connect with timeout.

  • 🛡

    TLS 1.2 + X25519

    Montgomery ladder over GF(2²⁵⁵−19), constant-time cswap, AES-128-CBC-SHA256 record layer.

Network Stack
Browser / HTTP Client
↕
TLS 1.2 (X25519 + AES-128-CBC-SHA256)
↕
TCP Sockets (sys_socket API)
↕
IPv4· ICMP· ARP· UDP
↕
RTL8139 NIC Driver (PCI)
142
RX Packets
87
TX Packets
5
ICMP Replies
Everything Included

Every subsystem, hand-crafted.

From the bootloader protocol layer to the MP3 decoder, every component is written in bare-metal C — no external libraries, no OS abstractions.

🧠

Preemptive Scheduler

Priority-weighted round-robin with PIT-driven context switches. Full GPR save/restore via inline assembly. Up to 32 concurrent tasks.

💾

FAT32 + VFS

Boot-time FAT32 loader with LFN support. RAM-backed VFS with POSIX-style permissions (uid/gid, mode bits, chmod/chown).

🔑

AES · SHA · HMAC

FIPS 197 AES-128, FIPS 180-4 SHA-256 and SHA-1, RFC 2104 HMAC. All in pure integer C — no SSE, no hardware acceleration.

💻

VT100 Terminal

80×24 emulator with full SGR color codes, escape sequences, scrollback, command history, and all built-in shell commands.

🔊

Intel HDA Audio

PCI HDA controller driver with WAV and MP3 playback (minimp3). MIDI synthesis via PC speaker fallback. Boot jingle on startup.

⚙

kmalloc Heap

First-fit doubly-linked free list over a 192 MB static BSS array. Split on alloc, coalesce on free. 16-byte alignment guaranteed.

🖥

Disk Installer

Writes MBR partition table, FAT32-formats the partition, copies kernel ELF and UEFI bootloader blob, writes limine.conf.

🎛

Setup Wizard (OOBE)

7-step first-boot wizard: welcome, keyboard, user/hostname, timezone, theme picker, optional install, summary.

🪄

ACPI + EDID

RSDP→RSDT/XSDT table parsing for MADT. EDID query for physical monitor dimensions to drive adaptive UI scaling.

System Architecture

One address space. All ring 0.

SynapseOS is a monolithic kernel. Every component — drivers, GUI, browser, crypto — executes at CPL 0 in a single virtual address space mapped by Limine at boot.

USER
Desktop Terminal (VT100) Navigator Browser Media Player Setup Wizard
↑↓
KERNEL
VFS + FAT32 Scheduler (RR) User Accounts Network Stack TLS 1.2
↑↓
DRIVERS
PCI ATA USB xHCI/EHCI RTL8139 NIC Intel HDA PS/2 IDT/PIC
↑↓
CRYPTO
AES-128 SHA-256 SHA-1 HMAC X25519
↑↓
MEMORY
kmalloc (192 MB heap) HHDM direct map Kernel @ 0xFFFF…80000000 PAT write-combining
↑↓
BOOT
Limine 8.6.0 (UEFI/BIOS) IDT + 8259 PIC ACPI RSDP parse RDTSC clock Serial COM1
↑
x86_64 Hardware (CPU · RAM · Disk · NIC · Display · USB · Audio)
Component Status

What's implemented.

Every component is kernel C. Statuses reflect the current release.

Limine UEFI Boot
UEFI 2.x + BIOS fallback
Done
GUI Compositor
Double-buffer, macOS-style windows
Done
VT100 Terminal
80×24, 16 colors, history
Done
SynapseOS Navigator
HTTP/HTTPS browser, HTML/CSS
Done
TLS 1.2 Client
X25519 + AES-128-CBC-SHA256
Done
RTL8139 NIC
PCI, ARP, IPv4, ICMP, TCP
Done
FAT32 + VFS
LFN, unix permissions, 256 inodes
Done
Disk Installer
MBR + FAT32 + kernel copy
Done
AES-128 / SHA-256 / HMAC
FIPS-compliant integer C
Done
Intel HDA Audio
WAV + MP3 (minimp3), MIDI
Done
Setup Wizard (OOBE)
7-step first-boot experience
Done
Round-Robin Scheduler
PIT-driven, 32 tasks, priority
Done
USB xHCI / EHCI
HID keyboard report queue
Partial
PS/2 Keyboard
Driver exists; IRQ routing WIP
Partial
Wi-Fi
Stub only — no hardware driver
Stub
Security

Cryptography written from scratch.

Every crypto primitive is implemented in pure integer C — no SSE, no libc, no external dependencies. Verified against FIPS and RFC test vectors.

🔐

AES-128 Block Cipher

FIPS PUB 197 compliant. Column-major state layout. Full key schedule (10 rounds, Rcon-based). SubBytes, ShiftRows, MixColumns, AddRoundKey and all inverses. Used by TLS 1.2 in CBC mode.

FIPS 197AES-128CBC mode
🔍

SHA-256 + SHA-1

FIPS PUB 180-4 compliant SHA-256 and SHA-1. Used for TLS 1.2 PRF, HMAC-SHA256 record MAC, and general-purpose hashing. Integer-only — zero FPU dependency.

FIPS 180-4SHA-256SHA-1
🔗

HMAC (SHA-256 / SHA-1)

RFC 2104 HMAC construction parameterized over both SHA-256 and SHA-1. Used for TLS 1.2 MAC, key derivation PRF, and authentication contexts in the browser.

RFC 2104HMAC-SHA256HMAC-SHA1
🔄

X25519 Key Exchange

Montgomery ladder over GF(2²⁵⁵−19) using 16-limb signed 64-bit arithmetic. Constant-time conditional swap (gfcswap). Used for TLS 1.2 ECDHE — the same algorithm as modern HTTPS.

RFC 7748Curve25519Constant-time
👤

Unix Permission Model

Full uid/gid/mode_t permission bits (rwxrwxrwx). VFS access checks against owner/group/other. chmod and chown APIs. Root bypass (uid 0). Up to 8 user accounts.

UID / GIDmode_tvfs_access()
⚡

TLS 1.2 Handshake

Full TLS 1.2 client: ClientHello, ServerHello, Certificate, ServerHelloDone, ClientKeyExchange, ChangeCipherSpec, Finished. Cipher suite: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xC027).

TLS 1.20xC027ECDHE
Boot Sequence

Zero to desktop in milliseconds.

Every initialization step is logged to serial. If anything fails, the kernel halts with a clear message rather than limping along.

🔌
Step 1
UEFI → Limine
Firmware loads BOOTX64.EFI from the ESP. Limine sets up a 64-bit page table environment, HHDM, and hands off to the kernel entry point with interrupts disabled.
_start() in limine_boot.c
📡
Step 2
Serial + IDT + PIC
COM1 serial port initialized for debug logging. IDT installed with 256 handlers. 8259 PIC remapped so IRQ 0–15 land at vectors 0x20–0x2F, clear of CPU exception range.
init_serial() → idt_init() → pic_init()
🗺
Step 3
Memory Map + HHDM
Kernel physical/virtual base addresses cached. HHDM offset stored — every physical address P is now accessible as P + hhdm_offset without custom page tables.
setup_kernel_base() → setup_hhdm()
⚙
Step 4
ACPI + Framebuffer + GUI
ACPI RSDP parsed for MADT. Monitor EDID queried for physical dimensions. Framebuffer initialized, font loaded, compositor double-buffer allocated. The display is now live.
acpi_boot_init() → setup_gui()
🔊
Step 5
STI + Audio + Boot Sound
Interrupts enabled (STI). Intel HDA probed via PCI scan. Boot jingle played. Control handed to the GUI main loop — which never returns.
enable_interrupts() → gui_main_loop()
🖥
Step 6
Desktop Environment
Splash screen → boot chooser → setup wizard (first boot) or direct to desktop. FAT32 mounted, VFS populated. USB/PS2 polling begins. Network stack brought online.
gui_main_loop() → desktop_init()
Technology

The toolchain behind the kernel.

Built with the same tools used for production OS development. Zero abstraction layers.

🔧
Clang / LLVM
-target x86_64-unknown-none-elf · -mcmodel=kernel
🔗
ld.lld
-nostdlib · custom linker.ld · ELF64
🚀
Limine 8.6.0
UEFI + BIOS bootloader · Limine protocol
💿
xorriso
ISO 9660 image creation with UEFI ESP
🖥
QEMU / KVM
Q35 machine · OVMF UEFI · serial stdio
🐛
GDB + DWARF
Remote debug via QEMU GDB stub · -g flag
🐍
Python 3 Tools
bin2c.py · wav2c.py · media embedding
📦
minimp3
Header-only MP3 decoder · integer-only
Build & Run

Up and running in minutes.

One make command downloads Limine, compiles the kernel, and produces a bootable ISO.

Makefile · CFLAGS
# Compiler flags (Clang)
CFLAGS := -target x86_64-unknown-none-elf \
-ffreestanding              \\
-fno-stack-protector     \\
-fno-PIC                \\
-mno-sse -mno-sse2      \\
-mno-red-zone           \\
-mcmodel=kernel         \\
-O2 -g -Wall -Wextra

# Linker flags (lld)
LDFLAGS := -nostdlib -static \\
-z max-page-size=0x1000 \\
-T kernel/linker.ld

# Entry point → kernel virtual base
# 0xFFFFFFFF80000000 (-mcmodel=kernel)
bash · quick start
# Prerequisites (macOS)
brew install llvm lld xorriso qemu

# Build — downloads Limine on first run
make

# Run in QEMU (UEFI mode)
make run

# Flash to USB and boot on real hardware
sudo dd if=uefi-demo.iso of=/dev/sdX \
bs=4M status=progress
  1. 1

    Install prerequisites

    Clang/LLVM, ld.lld, xorriso, and QEMU. The Makefile auto-detects x86_64-elf-gcc as an alternative.

  2. 2

    Run make

    Limine 8.6.0 is downloaded (~2 MB) on first build. Kernel ELF is compiled, linked, and staged into iso_root/.

  3. 3

    ISO is created

    xorriso wraps the kernel and bootloader into a hybrid UEFI + BIOS bootable ISO image at uefi-demo.iso.

  4. 4

    Boot in QEMU or on hardware

    make run launches QEMU with OVMF UEFI. Serial output appears in the terminal. Use -s -S for GDB debugging.

  5. 5

    Flash to USB for real hardware

    Write with dd, disable Secure Boot in firmware, and boot from USB. Legacy/CSM BIOS mode also works.

Platform Support

Where SynapseOS runs.

Primary target is UEFI x86_64. Legacy BIOS and physical USB boot are fully supported.

🖥

QEMU (UEFI)

Q35 machine with OVMF. Full feature set including NIC (RTL8139), USB keyboard, Intel HDA audio, and ATA disk for installer testing.

✓ Primary target
💾

Real Hardware (USB)

Write with dd to any USB drive. Boot in UEFI mode. EDID queries physical display dimensions for adaptive scaling.

✓ Supported
📟

QEMU (BIOS Legacy)

Limine BIOS path via limine-bios.sys. make run-bios. Useful for testing on machines without UEFI or with Secure Boot.

✓ Supported
"From the moment UEFI hands off control, to a TLS-secured HTTPS request in the browser — every byte of code is written in the kernel."
No libc  ·  No POSIX  ·  No runtime dependencies  ·  x86_64 ring 0 only
Memory Management

192 MB heap. HHDM. No page allocator.

SynapseOS uses Limine's Higher Half Direct Map to reach every physical byte without managing page tables, and a first-fit doubly-linked heap for dynamic allocation.

Virtual Address Space Layout

0xFFFFFFFF80000000
·
0xFFFF800000000000
·
0x0000000001000000
Kernel Image (.text / .data / .bss)

kmalloc Heap — 192 MB static BSS array

HHDM — all physical RAM mapped here

MMIO / Framebuffer (via HHDM)

Free / unmapped

HHDM formula: Physical address P → P + hhdm_offset. No custom page tables needed anywhere in the kernel.

Heap Allocator Design

🔍

First-Fit Algorithm

Walk the free list forward; take the first block ≥ requested size. Amortized O(n).

✂️

Block Splitting

If remainder ≥ MIN_BLOCK_SIZE (64B), it's split into a new free node — minimises waste.

🔗

Coalescing on Free

kfree() merges adjacent free blocks left and right — prevents fragmentation.

🛡

Magic Guard Header

Every block carries magic = 0xDEADBEEF. Mismatch on free signals corruption before it spreads.

Scheduler

Preemptive round-robin. Assembly context switch.

The scheduler hooks into PIT IRQ0. On every tick it saves the full GPR set in inline assembly, picks the next READY task, and restores its context — all before the IRET returns.

UNUSED

Slot free

→

READY

Queued to run

→

RUNNING

On CPU now

→

BLOCKED

Waiting on I/O

↘

ZOMBIE

Returned; cleanup pending

Context Switch — Inline Assembly

kernel/drivers/scheduler.c
/* Save callee-saved registers of 'from' task */
__asm__ volatile(
"movq %%rsp, %0\n\t"
"movq %%rbp, %1\n\t"
"movq %%rbx, %2\n\t"
"movq %%r12, %3\n\t"
"movq %%r13, %4\n\t"
"movq %%r14, %5\n\t"
"movq %%r15, %6\n\t"
: "=m"(from->rsp), "=m"(from->rbp),
"=m"(from->rbx), "=m"(from->r12),
"=m"(from->r13), "=m"(from->r14),
"=m"(from->r15)
: : "memory"
);

/* Capture resume RIP: return address already on stack */
uint64_t ret_addr;
__asm__ volatile(
"movq (%%rsp), %0" : "=r"(ret_addr)
);
from->rip = ret_addr;

Priority Time-Slicing

Each task has a priority and a slice counter. On each PIT tick, the slice decrements. When it hits zero, a context switch fires. Higher priority = larger initial slice = longer runtime before yielding.

Priority 1 (normal task)
Priority 2
Priority 3 (high priority)

Task 0 (boot thread) is permanent. A ZOMBIE task is cleaned on the next scheduler tick after it returns from its entry function.

Filesystem

VFS + Unix permissions + FAT32 at boot.

A flat inode table provides a POSIX-style path namespace. FAT32 is loaded into RAM at boot with full Long File Name support and cluster-chain following.

Permission Bits (mode_t)

S_IRUSROwner read (0400)
S_IWUSROwner write (0200)
S_IXUSROwner exec (0100)
S_IRGRPGroup read (0040)
S_IWGRPGroup write (0020)
S_IXGRPGroup exec (0010)
S_IROTHOther read (0004)
S_IWOTHOther write (0002)
S_IXOTHOther exec (0001)
vfs_access() Decision Tree
if (uid == 0) → allow all
elif (uid == inode.uid) → check USR bits
elif (in group inode.gid) → check GRP bits
else → check OTH bits

FAT32 Boot-Load Pipeline

1. ATA PIO Read — LBA 0; detect superfloppy BPB or MBR partition type 0x0B/0x0C.
↓
2. BPB Parse — Cluster size, FAT offset, data LBA, root cluster, sectors-per-FAT.
↓
3. Directory Walk — Recursive enumeration (max depth 8). LFN entries assembled into full filename.
↓
4. Cluster Chain — Follow FAT32 chain (EOC = 0x0FFFFFF8); load up to 6 MB per file into heap.
↓
5. VFS Populate — Inode created per entry. uid=0, gid=0, mode=0644/0755.

VFS Limits

256
Max inodes (MAX_FILES)
32
Max open file descriptors
256 B
Max path length
6 MB
Max file loaded from FAT32
8
Max FAT32 directory depth
255
LFN character support
Audio & Media

Intel HDA. MP3. MIDI. Boot sound.

SynapseOS drives an Intel HDA controller from PCI discovery to sample playback, with a header-only MP3 decoder and PC speaker MIDI fallback.

HDA Playback Pipeline

VFS: read /home/user/Music/track.mp3
↓
minimp3: decode MP3 frames → 16-bit PCM (≈35 MB output)
↓
Intel HDA: write samples to BDL (Buffer Descriptor List)
↓
HDA DMA: stream to DAC → analog output
MIDI Fallback Path

If no HDA controller is found, drivers/midi.c toggles the PC speaker at note frequencies — square-wave MIDI synthesis on any x86 machine.

Media Capabilities

🎵
MP3 Playback
minimp3 header-only decoder. Integer-only, no FPU. Runs entirely in the kernel heap.
🔊
WAV Playback
Direct PCM streaming to HDA BDL. Raw samples go straight to hardware — no conversion overhead.
🎹
MIDI Synthesis
Square-wave note generation via PIT frequency toggling on the PC speaker.
🚀
Boot Jingle
WAV embedded in the kernel image via wav2c.py; plays immediately after STI.
🖼
HD Wallpapers
Three wallpapers (city, landscape, nature) compiled as ARGB pixel arrays via bin2c.py.
Compiler Internals

Zero libc. Every flag has a reason.

The build system uses a precisely chosen set of flags that strip everything the kernel doesn't need — and would break if it had.

-target x86_64-unknown-none-elfFreestanding ELF64 — no OS ABI, no startup files, no default runtime libraries
-ffreestandingDon't assume the standard C library is present; don't link crt0
-fno-stack-protectorNo __stack_chk_guard symbol — it doesn't exist in a freestanding environment
-fno-PICPosition-independent code is incompatible with the kernel code model
-mno-sse / -mno-sse2SSE registers aren't saved on interrupts; using them in IRQ handlers corrupts task FPU state
-mno-mmx / -mno-80387Same reason — no x87 or MMX in interrupt context anywhere in the kernel
-mno-red-zoneThe 128-byte red zone below RSP is clobbered by hardware interrupts in kernel mode
-mcmodel=kernelAll code and static data must fit in the upper 2 GB (0xFFFF800000000000–0xFFFFFFFFFFFFFFFF)
-nostdlibLinker: don't link any standard libraries (no libc, no libgcc startup)
-z max-page-size=0x10004 KB alignment required by UEFI; LLD's default 2 MB breaks Limine's load
-O2 -gOptimise for production; retain DWARF debug info for GDB kernel debugging
✅

No libc

All string ops, memory functions, and snprintf are in kernel/lib/string.c — 100% freestanding C.

🔧

No startup files

No crt0, no _init, no atexit. The Limine entry stub _start is the first code that ever runs.

⚡

No FPU in kernel

Integer-only arithmetic throughout. No float, no double. FPU state is never saved on any interrupt path.

User Experience

From first boot to full desktop.

The OOBE wizard mirrors modern consumer OSes — a polished 7-step flow before the desktop launches.

🌍
Step 1
Welcome
Animated logo with language selection
⌨
Step 2
Keyboard
Layout: US, UK, DE, FR. Applied via ps2_set_keyboard_layout()
👤
Step 3
Account
Username + hostname. Creates non-root user via users_add()
🕐
Step 4
Timezone
Scrollable list. Saved to /etc/synapseos.cfg
🎨
Step 5
Theme
Dark or light theme with live color-swatch preview
💾
Step 6
Install
Optional disk install: MBR + FAT32 + kernel ELF + UEFI loader
🎉
Step 7
Done
Summary + "Start SynapseOS" button → desktop
Terminal Shell Commands
ls [path] — list directory
cat <file> — print file
ping <ip> — ICMP echo
ifconfig — network stats
ps — list tasks
mem — heap usage
play <file> — MP3/WAV
su <user> — switch user
arp — ARP cache
mkdir <path> — create dir
whoami — current user
users — list accounts
Comparison

SynapseOS vs other hobby kernels.

Most hobby OS projects stop at a framebuffer or a shell. SynapseOS goes all the way to TLS, a browser, and a disk installer.

Feature SynapseOS Typical Hello-World OS OSDev Tutorial OS
UEFI boot✓ Limine protocol✗ BIOS only~ Sometimes
Graphical GUI + window manager✓ Full compositor, dock✗ None✗ None
Web browser✓ HTTP/HTTPS, HTML/CSS✗ No✗ No
TLS / cryptography✓ AES, SHA, X25519✗ No✗ No
FAT32 filesystem with LFN✓ Full load + unix perms✗ No~ Read-only sometimes
Network stack✓ ARP / IPv4 / TCP / ICMP✗ No~ Ping only sometimes
Audio / MP3 playback✓ minimp3 + Intel HDA✗ No✗ No
Disk installer✓ MBR + FAT32 + kernel✗ No✗ No
Preemptive scheduler✓ PIT-driven, 32 tasks✗ No~ Cooperative sometimes
First-boot OOBE wizard✓ 7 steps✗ No✗ No
User accounts (uid/gid)✓ Unix permission model✗ No✗ No
libc dependency✓ None — freestanding~ Sometimes newlib~ Sometimes
FAQ

Common developer questions.

Design trade-offs, known limitations, and how things actually work under the hood.

Why no user space / ring-3 processes? ›
SynapseOS runs everything in ring 0 for simplicity — the focus was getting all subsystems working end-to-end first. Adding ring-3 requires per-task page tables, a syscall/sysenter gate with parameter validation at the boundary, stack canaries, and SMEP/SMAP enforcement. That's planned as a future milestone once the current feature set is stable and tested.
Why is keyboard input incomplete? ›
The PS/2 and USB HID drivers exist but IRQ routing between the 8259 PIC and the IDT handlers isn't fully debugged. The USB HID report queue and dispatcher work — the issue is inconsistent interrupt delivery on different QEMU configurations. The fix involves verifying MADT APIC interrupt source override entries and their effect on the PIC cascade.
Why is the heap 192 MB? That seems large for a kernel heap. ›
The minimp3 decoder produces ~35 MB of raw PCM for the embedded medicine.mp3, and we keep a WAV copy for HDA DMA streaming — that's ~70 MB alone. Adding VFS inode buffers, the framebuffer back-buffer, browser DOM tree, CSS working sets, and wallpaper pixel data fills the rest. The 192 MB is a static BSS declaration so it doesn't increase the ISO file size.
Is TLS certificate validation implemented? ›
No. The TLS 1.2 client performs a full handshake (X25519 key exchange, AES-128-CBC-SHA256 record layer) but does not validate the server's certificate chain. HTTPS provides confidentiality and integrity but not server authentication. A production implementation would require an embedded root CA store and ASN.1/X.509 chain parsing — planned for a future release.
Can SynapseOS be ported to ARM64 or RISC-V? ›
Not easily. The codebase contains x86_64-specific inline assembly in the scheduler (context switch), IDT/PIC setup, PIO macros (inb/outb/inl/outl), RDTSC clock calibration, and CPUID-adjacent code. Limine supports ARM64 and RISC-V so the boot protocol layer would transfer, but every driver and the entire scheduler would need architecture-specific rewrites.
Why MBR instead of GPT for the installer? ›
MBR was chosen for simplicity — it's a 512-byte boot record and a 16-byte partition table entry, both trivially writable in C. GPT requires a protective MBR, a primary GPT header with CRC32, 128 partition entries, UUID generation, and a backup header at the end of the disk. Limine boots from both; GPT support is a planned enhancement.
How do I add a new application to the desktop? ›
Create a source file in kernel/gui/, call window_create() to get a window handle, set an on_draw callback, and add the .c file to SOURCES in the Makefile. No dynamic linking or process model exists — your code compiles directly into the kernel image and runs in ring 0. See the Developer Guide section 9.3 for a complete working example with code.
Roadmap

What's coming next.

SynapseOS is actively developed. Priorities are ordered by impact and feasibility.

Soon

Fix Keyboard IRQ Routing

Complete PS/2 and USB HID interrupt delivery. Verify MADT APIC source overrides and PIC cascade wiring for consistent input on all configurations.

Soon

TLS Certificate Validation

Embed a minimal root CA store. Implement ASN.1 DER parsing and X.509 chain verification so HTTPS authenticates the server, not just encrypts the channel.

Soon

GPT Partition Support

Upgrade the disk installer from MBR to GUID Partition Table — required for disks > 2 TB and cleaner UEFI integration without a protective MBR.

Planned

Ring-3 User Space

Per-task page tables, a syscall dispatch gate, and an ELF loader to run user programs in ring 3 with hardware memory isolation from the kernel.

Planned

DHCP Client

Auto-configure IP, gateway, netmask, and DNS from the local network via DHCP DISCOVER/OFFER/REQUEST/ACK over UDP broadcast.

Planned

VirtIO Drivers

VirtIO block and network drivers for better QEMU performance — replacing emulated ATA/IDE and RTL8139 with the para-virtualized VirtIO transport.

Planned

Physical Page Allocator

Buddy system over the Limine memory map to replace the static 192 MB BSS heap with dynamic physical page allocation.

Future

JavaScript Engine

A minimal JS interpreter in the browser — enough for basic DOM manipulation scripts without a full V8/SpiderMonkey port.

Future

Wi-Fi Driver

Intel iwlwifi or Realtek rtw88 driver to enable wireless networking — currently only the Wi-Fi subsystem stub exists with no hardware backend.

Get Started

Build and boot SynapseOS
today.

Full technical documentation, API references, developer guide, and administration manual — all generated from the actual source code.

📄 Read the Docs ⚙ Get SynapseOS 📚 API Reference
Introduction → Boot Process → Kernel → Networking → Security → Administration →