404OS

404OS is a small x86 operating system with a browser-deployable demo build. It provides paging, interrupts, a simple filesystem, multiterminal shell workflow, basic device drivers, and a compact userspace toolset including a lightweight vim-style editor.

The repository is organized into three main parts:

• kernel/ Kernel-space code for paging, interrupts, scheduling, the filesystem, terminal handling, and low-level devices.
• userspace/ Flat 32-bit user programs such as shell, ls, cat, grep, vim, and supporting syscall wrappers.
• docs/ Static assets for the browser demo, including bootimg, filesys_img, BIOS files, and the hosted v86 frontend.

Run Locally

To launch the browser demo locally, serve the docs/ directory with any static file server and open it in a browser.

Example:

cd docs
python3 -m http.server 8080

Then open:

http://127.0.0.1:8080

Migration From MP3

404OS started as a migration of the original MP3 teaching kernel into a standalone browser-deployable system. The goal of the migration was to keep the working paging, terminal, filesystem, and syscall foundations from MP3, while removing classroom-facing branding and adding a web demo surface.

Source Mapping

The migration kept the same broad split between kernel-space and user-space:

• kernel/ Core kernel sources, paging, interrupts, scheduler, filesystem, terminal, and device code.
• userspace/ Flat 32-bit user programs such as shell, ls, cat, vim, and helpers.
• docs/ Browser deployment bundle for GitHub Pages or any static web host.

The browser bundle is intentionally checked in as ready-to-serve static assets:

• docs/index.html
• docs/bootimg
• docs/filesys_img
• docs/build/*
• docs/bios/*

What Changed From MP3

Compared with the original MP3 layout, 404OS adds several migration layers:

1. Browser boot path
   The OS can boot from a v86 page using multiboot + initrd, instead of only the original local VM/debug workflow.

2. Rebranded shell and boot flow
   User-visible strings such as the shell prompt and startup banner were changed to 404OS.

3. Browser-oriented stabilization
   Early boot checks, exception reporting, cache-busted static assets, and browser-friendly cursor/mouse handling were added so the same image can be run reliably from a static site.

4. Extended userland
   The migrated system now includes a lightweight vim-style editor and other browser-demo improvements beyond the original classroom baseline.

Build Artifacts

The deployed browser experience depends on two generated artifacts:

• kernel/bootimg The kernel image loaded by the multiboot path.
• docs/filesys_img The filesystem image mounted as the initrd/filesystem module.

For deployment, the generated artifacts are copied into docs/ so the site can be served directly by GitHub Pages or a local static server.

Why The MP3 Heritage Still Matters

The migrated system still follows the original MP3 execution model:

• flat user program loading at 0x08048000
• paging-backed user/kernel split
• file operations through the MP3-style syscall table
• terminal-driven shell workflow

That foundation made it practical to evolve the project into 404OS without rewriting the OS from scratch.