← back to projects

Framnir

Framnir is a hobby x86 operating system written from scratch. It's a monolithic, higher-half kernel that runs entirely in ring 0, no privilege separation, no hidden layers, just code that trusts the person who wrote it. It was designed for the old Intel Atom-powered netbooks, tested on QEMU, and runs comfortably in 16 MB of RAM while providing a full graphical interface, TCP/IP networking, USB support, and a growing collection of applications.

I started Framnir because I wanted to understand what happens when a machine wakes up. Not in the abstract, but in the particular: the bootloader handing off to the kernel, the page tables being laid down, the first interrupt firing, the first window being drawn. Every subsystem, memory management, task scheduling, the VFS, the network stack, was built decision by decision, with no framework to hide behind. That's the point. Framnir isn't trying to replace Linux or become the next big thing. It's a workshop. A place where the bones of the machine are visible and every component can be understood by one person.

The kernel comes with a full window manager, a widget toolkit, and a suite of applications: a text editor, file manager, terminal emulator, system monitor, IRC client, web browser, even a port of Doom and a voxel engine that looks very similar to Minecraft. There's a shell with around fifty built-in commands, an ELF loader that can run userspace programs compiled with the Tiny C Compiler from inside the OS itself, and an AppleTalk stack alongside standard TCP/IP because old protocols deserve to live somewhere.

Framnir doesn't promise to be useful. It promises to be interesting. That's enough.

Features

  • Monolithic kernel running in ring 0, with full access to hardware and kernel structures
  • Higher-half design with a 3GB/1GB virtual address space split
  • Round-robin task scheduler with multiple suspension types and cooperative preemption
  • Virtual memory with demand-allocation, copy-on-write, and MMIO support
  • Slab allocator for fast small-object allocation alongside a page-based kernel heap
  • Virtual File System with support for tmpfs (root), Ext2, and FAT32
  • Full TCP/IP stack: Ethernet, ARP, IP, ICMP, UDP, TCP, DHCP, DNS, NTP, HTTP, FTP, SMTP, POP3, and more
  • AppleTalk stack: DDP, ATP, NBP, PAP for classic Macintosh networking compatibility
  • Window manager with occlusion-aware rendering, dirty rectangle tracking, Z-ordering, and modal dialogs
  • Widget toolkit with buttons, text inputs, list views, table views, tab pickers, scroll bars, menus, and more
  • PS/2 keyboard and mouse drivers
  • UHCI, EHCI and xHCI USB drivers with device enumeration and control transfers
  • USB Mass Storage, FTDI and Network support, so USB cards can be hotplugged into the hardware, and correctly detected
  • IDE/ATA driver with PIO-mode read/write and per-drive locking
  • PCI subsystem with device enumeration and configuration space access
  • AC'97 audio driver with 16-bit stereo PCM playback
  • UART driver for 16550-compatible serial ports with hardware loopback detection
  • ELF loader for userspace applications with symbol table loading and stack trace support
  • Shell with command history, ~50 built-in commands, and automatic ELF execution
  • Kernel applets: taskbar, device manager, file explorer, system monitor, text editor, terminal, IRC client, web browser, mail client, and more
  • Doom port, Chess, Minesweeper, Snake, 2048, Memory, Lights Out and other games running as userspace ELF applications
  • Tiny C Compiler integration for compiling and running C code at runtime within the OS
  • SMBus/I2C driver for system management devices and SPD EEPROM dumping

License

This project was written by främling and is licensed under the GNU General Public License version 3 (or any later version).

See the LICENSE file for details.

Downloads

  • Latest release:
    • none available yet.

Requirements

Framnir is built for 32-bit x86 systems. It uses the Limine bootloader and requires a multiboot-compatible environment.

  • QEMU - The primary development and testing target. Any recent version with -M q35 support will work.
  • Intel Atom netbook - The original hardware target. 1-2GB RAM (Framnir requires just 16MB of RAM), Atom Z530, PS/2 keyboard and touchpad, IDE storage.
  • Limine bootloader - Required for both BIOS and UEFI boot. Included in the build process.
  • GCC cross-compiler - An i686-elf toolchain for compiling the kernel and applications.
  • GNU Make - Build orchestration across kernel, libraries, and applications.
  • 16 MB RAM minimum - The kernel runs comfortably in a tiny footprint. More RAM supports larger applications.

Running

When booted, Framnir starts in graphical mode by default, launching the window manager and taskbar, but it can be "convinced" to start in text mode instead.

The shell provides access to all built-in commands. Type a command name to run it, or type the name of an ELF application to launch it. The "win" command starts the window manager from text mode.

Some useful shell commands:

ls              # List directory contents
cd /Apps        # Change to the applications directory
lspci           # List PCI devices
lsnet           # Show network interfaces
sysinfo         # Display system information
ver             # Print kernel version

Framnir is built slowly, in the margins of evenings and weekends. It doesn't chase modernity. It tries to keep the machine legible. The full architecture documentation, every boot stage, every memory layout decision, every driver protocol, lives in the source tree for anyone who wants to follow the same thread.

Applications and applets

Blockada

A voxel sandbox game built from scratch, Blockada is a Minecraft‑style world with procedurally generated terrain, ray‑cast rendering, a full crafting and inventory system, chests, furnaces, and persistent saves: all running as a native ELF application with no external assets.

  • Procedural world generated in six stages: height‑mapped terrain with island‑ocean coastlines, ore veins (coal, iron, gold, diamond, lapis lazuli), worm‑like cave carvers, underground chambers with loot chests, forests with oak/birch/acacia/cherry trees, and surface decorations (melon/pumpkin patches, sugar cane). Deepslate and voidstone appear at deeper layers.
  • 55+ block types including natural terrain, four wood species with planks and leaves, sandstone, clay, terracotta and dyed variants, polished stone and brick blocks, functional blocks (chest, furnace, iron/gold block, bookcase, barrel), and water.
  • First‑person rendering using DDA ray casting with side‑based lighting, distance fog, and an outline on the targeted block. The sky is a simple gradient; hotbar, mining progress bar, and inventory GUIs are drawn directly into the backbuffer.
  • Full crafting via a 3×3 grid. Recipes include sticks, pickaxes and axes (wood/stone/iron/diamond), planks, stone and sandstone bricks, chests, bookcases, paper, books, and furnaces. Materials are consumed and output is produced with proper stack handling.
  • Inventory and storage: 32‑slot player inventory, 5‑slot hotbar, item stacks up to 64. Chests provide 32 additional slots. Furnaces smelt ores, clay, logs, etc. into refined blocks/dyes/items with a visible progress bar; fuel (coal or wood) is consumed over time. Right‑clicking a chest or furnace opens its interface.
  • Mining and placement: left‑click to mine a block; mining speed depends on the tool used (axes for wood/leaves, pickaxes for stone/ores). A progress bar appears above the hotbar. Right‑click places the selected block; items cannot be placed.
  • Player physics: gravity, jumping, collision detection with solid blocks, and water slowing. Movement is first‑person with mouse‑look and WASD/arrow keys.
  • Save/load: world and player state are saved to /Data/Blockada/ between sessions, including all blocks, chest/furnace contents, and player inventory.
  • Procedural textures for every block and item, generated at startup using noise and pattern algorithms: no image files required.
  • Starter kit on a new world gives the player diamond tools, a furnace, a chest, and a selection of building blocks so they can jump right in.

IRC Client

A full graphical IRC client built directly into the kernel. It connects to standard IRC servers over plain TCP or TLS, handles CTCP queries, and presents conversations in a tabbed interface with channel user lists, private message tabs, and a persistent Status tab for raw server traffic.

  • Tabbed interface with a Status tab, channel tabs (chat log + user list), and private message tabs. Tabs track unread messages and can be closed individually.
  • Rich IRC command set accessible via a command input at the bottom of the window. Supports /connect, /disconnect, /join, /msg, /query, /nick, /close, /op, /deop, /voice, /devoice, /kick, /ban, /whois, /topic, and /quit.
  • Real-time message display with optional timestamps, automatic scrolling, and line limiting to keep memory usage bounded.
  • User list in channel tabs, sorted by rank (ops, voiced, regular users), with double-click to open a private message tab.
  • Privacy mode that suppresses CTCP responses and filters CTCP content from the raw server log.
  • Menu bar with File (Connect, Settings, Quit) and Help (About) menus. The Connect item dynamically toggles to Disconnect when connected.
  • Configuration loaded from the system settings database, with fallback defaults. Supports server, port, SSL, nick, user, real name, timestamps, and a configurable log directory.
  • Logging of all conversations and server events to per-target log files on disk.
  • Polling-based I/O that never blocks the GUI thread, using non-blocking reads for TLS and short timeouts for plain TCP.

Web Browser

A graphical web browser and Gopher client built into the kernel. It handles HTTP, HTTPS, Gemini, Spartan, Gopher, and local file:// pages, rendering HTML through the built-in HtmlStrip engine and presenting Gopher directories as clickable menus. All network requests run in background tasks so the interface stays responsive during page loads.

  • Multi-protocol support: HTTP/HTTPS, Gemini, Spartan, Gopher, and local files, with automatic protocol detection when no scheme is given.
  • Background fetching: pages load in a separate kernel task, keeping the UI free for scrolling and interaction. A 30-second timeout prevents hung connections from locking the window.
  • HTML rendering via HtmlStrip, with clickable link detection and relative URL resolution.
  • Image display: inline rendering of PNG, JPEG, BMP, and other supported formats, with zoom-to-fill and pan controls.
  • Gopher browsing with directory listing, type-specific icons, and selector-based navigation. Raw Gopher responses are parsed into formatted display text with embedded link markers.
  • Navigation history with Back and Forward buttons, plus a Reload and Home button on the toolbar.
  • Bookmarks loaded from a plain-text file, organized into category submenus under the Bookmarks menu.
  • URL bar with Enter-to-navigate and automatic http:// prefixing for bare hostnames.
  • View Source, Show Headers, and Show Cookies modal dialogs for inspecting page data.
  • Cookie storage under /Data/Web/Cookies, with a viewer that lists all stored cookies by domain.
  • Download handling for non-text, non-image responses: files are saved to /Data/Web/Downloads with progress and completion notifications.
  • IRC link delegation: irc:// URLs are passed to the IRC client applet automatically.

Mail Client

A graphical email client integrated into the kernel, supporting POP3 for incoming mail and SMTP for outgoing mail, both with optional TLS. It stores messages as standard .eml files on disk and provides a familiar three-pane interface: folder list, message list, and content view.

  • POP3/SMTP support with configurable servers, ports, and TLS encryption, loaded from the system settings database.
  • Folder navigation with Inbox, Sent, Drafts, and Trash views. Inbox messages are fetched from the POP3 server; sent messages are stored locally in a timestamped directory.
  • Message list displaying sender, subject, and date in a sortable table view, populated by scanning .eml files on disk.
  • Message reading loads the full RFC 822 content on demand and displays the body in a read-only text area below the list.
  • Background sync runs POP3 retrieval in a separate kernel task, so the UI stays responsive. A timeout prevents hung connections from locking the window.
  • Compose window with To, Subject, and multiline body fields. Sending runs in a background SMTP task, with success/failure feedback and automatic saving of sent messages to the Sent folder.
  • Auto-check daemon periodically polls the POP3 server and downloads new messages even when the mail applet is closed, storing them for the next session.

REST API Client

A simple graphical HTTP client for testing REST APIs. Supports GET, POST, PUT, and DELETE methods with custom headers and a request body. Displays response content, request trace, and response headers in separate tabs.

  • Method selector (GET, POST, PUT, DELETE) and URL input bar with a Go button, plus Enter-to-send.
  • Tabbed interface for Request Headers, Request Body, Response, and Headers Info (split view of request/response headers).
  • Custom headers entered as Name: Value pairs in a multiline text area, parsed and sent with the request.
  • Request body editing for POST/PUT methods; for GET/DELETE, the body is URL-encoded and appended to the URL as a query string.
  • Response display in a read-only styled text area, with automatic tab switch to Response on completion.
  • Request/response trace available in the Headers Info tab, showing the raw HTTP request and response headers.
  • Background execution runs the HTTP request in a separate kernel task, with a 30-second timeout.

Deepsy

A chat client for OpenAI-compatible APIs, configured by default for DeepSeek. It maintains a full conversation history and sends user messages to the model in the background, keeping the interface responsive. All interaction happens in a simple two-panel window: a read‑only chat log and a text input.

  • OpenAI‑compatible API with configurable endpoint, API key, and model, read from the [Deepsy] settings section.
  • Conversation history stored in memory and built into each request, allowing multi‑turn chats.
  • Optional advanced parameters Thinking and ReasoningEffort to control model behaviour.
  • Background requests with a 60‑second timeout; the UI remains interactive and shows “Thinking ...” while waiting.
  • Chat log displays messages as You: / Deepsy: pairs, with automatic scrolling.
  • Logging of all messages to disk when a log directory is configured (disabled by default).

Weather

A compact weather applet that fetches current conditions from an API, parses the JSON response, and displays temperature, condition, humidity, pressure, and wind speed alongside a weather icon. It refreshes automatically at a configurable interval.

  • API-driven – reads the endpoint URL, city, API key, and units from the [Weather] section in settings. The URL template supports %s placeholders for city, key, and units.
  • Background fetching – HTTP requests run in a detached task with a 30‑second timeout, keeping the UI responsive.
  • Display – city name, temperature, feels‑like, condition/description, humidity, pressure, and wind. Numeric values show one decimal place.
  • Weather icon – loads a PNG icon from /Data/Weather/Images/ based on the API’s icon field and paints it on the window.
  • Auto‑refresh – automatically re‑fetches at an interval defined by Refresh (in seconds). The window title updates with the city name.

Written by främling on Feb 11, 2026.