MyOS2026 — VM-First Operating System in Rust

A modern, minimal, secure operating system designed specifically for virtual machines — fast boot, reproducible images, strong security defaults, and a full Unix utility layer. Written entirely in Rust.

---

Project Resources

• Live status & metrics: docs/STATUS.md — test counts, CI gates, success-criteria dashboard (updated on every feature merge)
• Capability inventory: docs/CAPABILITIES.md — kernel subsystems, syscalls, /proc files, userland binaries
• Per-feature history: CHANGELOG.md — what shipped, when, with what trade-offs
• Design rationale: Learnings.MD — what was hard, root causes, non-obvious decisions
• Roadmap: ROADMAP.md — tiered follow-up work
• Validation: VALIDATION.md — proof against the 11 success criteria

---

Why MyOS2026

• Boots in under 2 seconds to an nsh$ prompt on BIOS-headless QEMU, with SSH ready in under 5 seconds.
• Reproducible images (identical SHA-256 across runs) and verified boot (BLAKE2b → ed25519 attestation chain) by default.
• Written entirely in Rust with ~170 LOC of hand-written assembly. KASAN + FASAN catch memory-safety bugs at the corruption site, not the crash site.

---

Use Cases

• OS learning platform — every subsystem fits in your head, written in safe Rust.
• Secure ephemeral VMs — sandbox + verified boot + fast teardown via snapshot/rollback.
• CI/CD throwaway environments — sub-2-second boot, 18 MB image, SSH ready in under 1 second.
• Kernel and systems-programming research — modify the kernel, rebuild, boot in under 2 minutes.

---

Quick Start

# Prerequisites
apt install qemu-system-x86 ovmf sgdisk mtools e2fsprogs qemu-utils nasm python3
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly
rustup target add x86_64-unknown-linux-musl

# Build and boot
RELEASE=1 bash build/scripts/assemble-image.sh myos.qcow2
make qemu

Save your SSD: make tmpfs-setup redirects target/ and dist/ (the only large gitignored output trees) into /tmp/MyOS/<hash>/ so the write-heavy build cycle hits RAM. Reversible, idempotent, opt-in, no-op on CI. See docs/dev-tmpfs.md.

Interactive session

Boot in a graphical window with the kernel framebuffer terminal, and SSH in on port 2222 simultaneously:

make qemu-sdl
ssh -p 2222 -i tests/keys/test_id_ed25519 \
  -o StrictHostKeyChecking=no root@127.0.0.1

For headless and VirtualBox boot recipes, see docs/CAPABILITIES.md and specs/001-vm-optimized-os/quickstart.md.

---

Demo

nsh$ prompt with mybox applets, pipe chains, and standard utilities — captured via make screenshot.

Real nsh session over SSH — uname, /proc/meminfo, /proc/cpuinfo, ps, a base64 pipe, and the colored prompt. Generated via make demo-gif.

---

What's Inside

A complete, self-contained OS stack — kernel, drivers, networking, filesystem, security, and a full Unix userland:

+-------------------------------------------------------+
|  User Space   init | nsh | mybox (99 applets) | mymc  |
|               cloud-init | dropbear | sandbox         |
+-------------------------------------------------------+
|  Security     Per-process syscall allowlist           |
|               Real UID/GID + supplementary groups     |
|               Credential audit ring                   |
|               Verified boot (BLAKE2b → ed25519)       |
+-------------------------------------------------------+
|  System       VFS | Syscall dispatch | Pipes | IPC    |
|               MLFQ scheduler | Linux ELF compat       |
|               epoll(7) | poll(2) | WaitQueue<N>       |
+-------------------------------------------------------+
|  Kernel       MM (demand paging + CoW fork)           |
|               APIC/HPET | smoltcp | DHCP | ext2       |
|               procfs (14 top-level + 6 per-PID files) |
|               KASAN + FASAN + DWARF panic backtraces  |
+-------------------------------------------------------+
|  Drivers      virtio-{blk,net,console,rng,scsi}       |
|               LSI Logic MPT SCSI | Intel E1000        |
+-------------------------------------------------------+
|  Hardware     QEMU q35 (primary) | VirtualBox         |
+-------------------------------------------------------+

For the full enumeration of subsystems, syscalls, and userland binaries, see docs/CAPABILITIES.md.

---

Highlights

mybox — Busybox-in-Rust (99 applets)

A multi-call binary providing 99 Unix applets via symlinks in /bin. Dispatch is purely by argv[0] basename — no runtime overhead per applet. Covers file ops, text processing, filesystem inspection, process control, system info, archives, shell utilities, networking (DNS, HTTP, nc, ping), and strace.

nsh$ /bin/grep -i root /etc/passwd
root:x:0:0:root:/root:/bin/sh
nsh$ /bin/ls -la /bin/ls
lrwxrwxrwx        10 ls -> /bin/mybox
nsh$ mybox --list | wc -l
99

Linux ELF binary compatibility

Statically-linked musl ELF binaries compiled on Linux run directly on MyOS2026 without modification:

# On a Linux host:
musl-gcc -static -o hello hello.c

# Copy to MyOS2026 and run:
nsh$ /bin/hello
Hello, World!

Full System V AMD64 ABI initial stack with correct AT_PHDR (vaddr-not-file-offset) and AT_SECURE on suid exec. All musl startup syscalls supported. Invalid accesses deliver SIGSEGV; stack overflows are caught at the guard. See docs/CAPABILITIES.md.

Per-process syscall sandbox

nsh$ sandbox --allow=read,write,exit /usr/bin/exploit-test
BLOCKED (errno=1)      ← mount(2) blocked by kernel allowlist

The kernel enforces a deny-by-default syscall filter per process, installed via SYS_SANDBOX_ENTER. Filters survive execve and are independent across processes.

Verified boot

Every RELEASE build embeds a BLAKE2b hash chain:

UEFI → Limine (config hash enrolled) → kernel.elf (BLAKE2b verified)
     → kernel_main ([vboot] ACTIVE  pubkey: be5f7844108bcdd1)

Any binary tampering before a single kernel instruction executes causes an immediate boot abort.

Reproducible builds

Two independent builds from identical source produce byte-identical QCOW2. Achieved via SOURCE_DATE_EPOCH, pinned GPT/FAT UUIDs, and build/scripts/fix-ext2-timestamps.py.

---

Architecture

Design principles

Principle	Choice
Kernel type	Minimal monolithic (Rust, no_std)
Bootloader	Limine v8.x (BIOS + UEFI, single config)
I/O model	virtio-only (blk / net / console / rng / scsi)
Network	smoltcp 0.11 (pure Rust, no_std)
Filesystem	ext2 (custom pure-Rust read/write driver)
SSH	Dropbear (userspace, cross-compiled for musl)
Userland	Rust + statically linked musl
Assembly	~170 LOC total (entry stub, ISR trampoline, context-switch)

Repository layout

kernel/          Rust kernel (no_std)
userland/        Userspace crates (musl-static): init, nsh, mybox, mymc, ...
bootloader/      Limine config + vendored binaries
build/           Makefile, image assembly scripts, CI helpers
tests/           Boot, SSH, shell, sandbox, syscall, scheduler integration tests
specs/           Per-feature specs (NNN-name/{spec,plan,tasks,quickstart}.md)
docs/            STATUS.md, CAPABILITIES.md, dev-tmpfs.md, syscall-diff.md

For the full layout, see docs/CAPABILITIES.md.

---

How It's Built

• Per-feature spec-kit workflow — every feature has specs/NNN-name/{spec,plan,research,tasks}.md and a quickstart. Implementation follows tests-before-code per the project constitution.
• CI gate on every PR — clippy (-D warnings), unit tests in parallel + sequential modes, boot integration under smp ∈ {1, 2}, SSH login, sandbox, KASAN, ABI-drift, and docs-gate (per the constituent jobs listed in docs/STATUS.md).
• Run the pipeline locally before pushing:

  make ci-local       # ~15 min; same step order and timeouts as remote CI

• In-kernel diagnostics: dmesg ring (/proc/dmesg), per-PID syscall trace (/proc/<pid>/trace), symbolized panic backtraces with DWARF line numbers, kassert! with PCB context, KASAN + FASAN memory-safety sanitizers.

---

Contributing

All changes go through a feature branch and pull request — direct commits to master are prohibited.

1. Fork the repository.
2. Create a feature branch: git checkout -b NNN-short-description origin/master.
3. Read the constitution at .specify/memory/constitution.md and the existing specs in specs/.
4. Use the spec-kit workflow: /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement.
5. Run make ci-local before pushing.
6. Open a PR targeting master. Every feature PR must update Learnings.MD, CHANGELOG.md, and docs/STATUS.md (enforced by the docs-gate CI step; bypass with [no-docs] in any commit message for docs-only or infra-only PRs).

For project conventions, MANDATORY workflows, and operational guides (in-kernel dmesg + GDB, KASAN, syscall-diff harness, tmpfs build redirection), see CLAUDE.md.

Good first issues:

• POSIX lstat() that does not follow the final symlink component
• Dynamic ELF loader (PT_INTERP support) — enables glibc-linked binaries
• GPG signing pipeline for release artifacts

See the issue tracker for follow-up work tagged good-first-issue and follow-up.

---

License

Mozilla Public License 2.0