VeridianOS is a research operating system written in Rust, focused on correctness, isolation, and explicit architectural invariants. It serves as executable documentation of high-assurance systems design -- exploring how capability-oriented architecture, strong isolation boundaries, and disciplined use of unsafe code produce systems that are auditable, teachable, and resilient to failure.
The system implements a capability-based security model, zero-copy IPC with sub-microsecond latency, and runs on three architectures (x86_64, AArch64, RISC-V). It is self-hosting, ships a Wayland desktop environment, supports containerized and virtualized workloads, and includes formal verification infrastructure -- all while keeping the microkernel under 15K lines of trusted code.
VeridianOS intentionally prioritizes architectural clarity over feature velocity. Native APIs are capability-based; compatibility layers (POSIX, Wayland) are implemented as user-space libraries that translate to native interfaces, never as kernel-level compromises.
- Microkernel architecture -- Minimal trusted computing base with all drivers and services in user space
- Written in Rust -- Memory safety without garbage collection; strict unsafe code policy
- Capability-based security -- 64-bit unforgeable tokens for all resource access with O(1) lookup, hierarchical delegation, and cascading revocation
- Zero-copy IPC -- Synchronous and asynchronous channels with register-based fast path (<1us for messages <=64 bytes)
- Formal verification -- 38 Kani proof harnesses and 6 TLA+ specifications covering boot chain, IPC, memory allocation, and capability invariants
- Multi-architecture -- Full support for x86_64 (UEFI), AArch64, and RISC-V 64 (OpenSBI)
- Self-hosting -- Native GCC 14.2 and Rust compiler toolchain; BusyBox 1.36.1 with 95 applets compiled on-target
- Package management -- DPLL SAT dependency resolver, ports system, reproducible builds, Ed25519 package signing
- Complete C library -- Full stdio/stdlib/string/unistd with POSIX headers, math library, and architecture-specific setjmp/longjmp
- Bash-compatible shell (vsh) -- Pure Rust shell with 153 builtins (power, user, service, network, filesystem, storage, devtools, diagnostics, desktop, cloud/container), job control, readline, scripting, and POSIX word expansion
- Wayland compositor -- Wire protocol, SHM buffers, XDG shell, layer-shell, DMA-BUF, multi-output with HiDPI scaling
- Desktop environment -- 9 desktop apps (terminal, file manager, text editor, calculator, system monitor, settings, image viewer, web browser, PDF viewer), application launcher, Alt-Tab switcher, notifications, 6-item system tray, 8 settings panels, screen lock, virtual workspaces, TrueType fonts, CJK Unicode
- KDE Plasma 6 cross-compilation -- Complete platform backend stack and cross-compiled binaries for KDE Plasma 6 Wayland desktop. Static musl-based toolchain cross-compiles kwin_wayland (158MB), plasmashell (150MB), and dbus-daemon (886KB) from source. 250+ static libraries in sysroot including Qt 6.8.3, KDE Frameworks 6.12.0, Mesa softpipe, Wayland 1.23.1, and full font/input/rendering stacks. 479MB BlockFS rootfs image for QEMU boot. Qt 6 QPA plugin, KF6 backends, KWin DRM/KMS, Breeze theme, display manager, XWayland (314 porting tasks across 11 sprints)
- KDE limitations remediation -- PipeWire audio with PulseAudio compatibility, NetworkManager with Wi-Fi/Ethernet/DNS, BlueZ Bluetooth with HCI bridge, XWayland GLX/DRI3/XIM enhancements, ACPI power management with CPU frequency scaling, KRunner search (6 runners), Baloo file indexer, Activities framework, USB hotplug with udev, V4L2 video, multi-monitor, session save/restore, KSM memory deduplication, D-Bus optimization
- KDE Plasma 6 default desktop --
startguilaunches KDE Plasma 6 as default session with automatic fallback to built-in DE; session config via/etc/veridian/session.conf;startgui builtinforces built-in DE - GPU acceleration -- VirtIO GPU 2D/3D, OpenGL ES 2.0, DRM/KMS, texture atlas compositor with shader pipeline; vendor stubs for i915, amdgpu, and nouveau
- Audio & video -- ALSA-compatible mixer, VirtIO-Sound, WAV/Vorbis/MP3 playback, PNG/JPEG/GIF/TGA/QOI decoders, media player
- Web browser engine -- HTML5 tokenizer, arena-based DOM, CSS layout (block/inline/float/flexbox), JavaScript VM with mark-sweep GC, tabbed browsing with process isolation
- Networking -- TCP/IP dual-stack (IPv4 + IPv6), zero-copy DMA, E1000 NIC driver, TCP Reno/Cubic/SACK, DNS, DHCP, VLAN, bonding, netfilter firewall with conntrack/NAT, RIP/OSPF routing, WiFi 802.11, Bluetooth L2CAP/RFCOMM, VPN tunnels, TLS 1.3, SSH, HTTP, QUIC, WireGuard, mDNS
- Virtualization -- Intel VMX hypervisor with VMCS/EPT, KVM API compatibility, QEMU device model with live migration, VFIO PCI passthrough, SR-IOV, CPU/memory/PCI hotplug
- Containers -- OCI runtime with PID/mount/network/UTS namespaces, cgroup memory+CPU, overlay filesystem, seccomp BPF, veth networking
- Cloud-native -- CRI/CNI/CSI interfaces, service mesh with mTLS and SPIFFE identity, L4/L7 load balancer, cloud-init metadata service
- Enterprise -- LDAP v3, Kerberos v5, NFS v4, SMB2/3, iSCSI initiator, software RAID 0/1/5
- Defense in depth -- KPTI shadow page tables, KASLR, stack canaries, SMEP/SMAP, retpoline, W^X enforcement, guard pages
- Post-quantum cryptography -- ML-DSA-65 (Dilithium) and ML-KEM (Kyber) alongside ChaCha20-Poly1305, Ed25519, X25519
- Hardware security -- TPM 2.0 integration, secure boot verification, IOMMU protection
- Mandatory access control -- Policy parser, RBAC, MLS enforcement, structured audit logging
- Compiler toolchain -- Cross and native GCC 14.2, Rust std platform port (
std::sys::veridian), LLVM 19 bootstrap pipeline - Debugging -- GDB remote serial protocol, kernel debug scripts, QEMU integration on all architectures
- Development environment -- IDE with gap buffer editor and LSP client, CI runner, profiler with flame graph rendering, native git client
- Build system -- Build orchestrator with dependency topological sort, package repository server
All drivers and services run in user space with capability-controlled access to hardware. The microkernel provides only memory management, scheduling, IPC, and the capability system. See Architecture Overview for detailed design documentation and Invariants for the authoritative list of architectural invariants.
Version: v0.25.2 | All development phases complete (0-12) | 83 releases published
| Metric | Value |
|---|---|
| Build | 0 errors, 0 warnings across all 3 architectures |
| Boot tests | 29/29 (Stage 6 BOOTOK on all architectures) |
| Host-target unit tests | 4,095 passing |
| CI pipeline | 11/11 jobs green (GitHub Actions + Codecov) |
| Unsafe code | 7 justified static mut; 99%+ unsafe blocks have SAFETY documentation |
| Architecture | Boot Method | Status |
|---|---|---|
| x86_64 | UEFI via OVMF | 100% functional -- 1280x800 UEFI GOP, Ring 3 entry, native compilation |
| AArch64 | Direct kernel loading | 100% functional -- PL011 UART, signal frames, virtio-MMIO |
| RISC-V 64 | OpenSBI | 100% functional -- Sv48 page tables, full signal delivery |
| Metric | Target | Achieved |
|---|---|---|
| IPC latency | < 1us | < 1us (register-based fast path) |
| Context switch | < 10us | < 10us |
| Memory allocation | < 1us | < 500ns (slab allocator) |
| Capability lookup | O(1) | O(1) (two-level cache) |
| Concurrent processes | 1000+ | 1000+ |
| TLB shootdown | < 5us/CPU | 4.2us/CPU |
kernel/ Trusted computing base (microkernel)
drivers/ Hardware interaction behind explicit privilege boundaries
services/ Capability-mediated system services (CRI, CNI, CSI, mesh, LB)
userland/ User processes, libc, libm, Rust std port, vsh, vpkg, KDE Plasma 6 backends
boot/ Bootloader and early initialization
targets/ Rust target JSON specs (kernel and user-space, all 3 architectures)
scripts/ Build infrastructure (cross-toolchain, sysroot, rootfs)
toolchain/ CRT files, sysroot headers, CMake/Meson cross-compilation configs
ports/ Port definitions for external software (binutils, gcc, make, ninja)
verification/ Kani proofs and TLA+ specifications
docs/ Design documents and guides
- Rust nightly-2025-11-15 or later
- QEMU 9.0+ (10.2+ recommended)
- 8GB RAM (16GB recommended)
- 20GB free disk space
# Clone the repository
git clone https://github.com/doublegate/VeridianOS.git
cd VeridianOS
# Install dependencies (Ubuntu/Debian)
./scripts/install-deps.sh
# Build all architectures
./build-kernel.sh all dev # Development build
./build-kernel.sh all release # Release build
# Build a specific architecture
./build-kernel.sh x86_64 dev
# Run in QEMU (x86_64 - UEFI boot, requires OVMF)
qemu-system-x86_64 -enable-kvm \
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/x64/OVMF.4m.fd \
-drive id=disk0,if=none,format=raw,file=target/x86_64-veridian/debug/veridian-uefi.img \
-device ide-hd,drive=disk0 \
-serial stdio -display none -m 2G
# Run in QEMU (AArch64)
qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M \
-kernel target/aarch64-unknown-none/debug/veridian-kernel \
-serial stdio -display none
# Run in QEMU (RISC-V)
qemu-system-riscv64 -M virt -m 256M -bios default \
-kernel target/riscv64gc-unknown-none-elf/debug/veridian-kernel \
-serial stdio -display none
# Run tests
cargo test# Build cross-compiled BusyBox rootfs
./scripts/build-busybox-rootfs.sh all
# Create a 256MB persistent BlockFS image
./scripts/build-busybox-rootfs.sh blockfs
# Boot with persistent storage (needs 2GB RAM)
./scripts/run-veridian.sh --blockfsFor detailed build instructions, see BUILD-INSTRUCTIONS.md.
| x86_64 | AArch64 | RISC-V 64 | |
|---|---|---|---|
| Boot | UEFI via OVMF | Direct -kernel |
OpenSBI -bios default |
| Display | 1280x800 UEFI GOP | ramfb | ramfb |
| Minimum RAM | 2GB | 256MB | 256MB |
| Native compilation | 1.5GB+ | -- | -- |
Minimum: 64-bit CPU with MMU, 2GB RAM (x86_64) or 256MB RAM (AArch64/RISC-V), 1GB storage. Recommended: Multi-core CPU with virtualization support, 4GB+ RAM, NVMe storage.
- Architecture Overview -- System design and layers
- Development Guide -- Getting started with development
- API Reference -- System call and library APIs
- Testing Strategy -- Testing approach and guidelines
- Troubleshooting -- Common issues and solutions
- Software Porting Guide -- Porting Linux software to VeridianOS
- Compiler Toolchain Guide -- Native compiler integration
- Rust Compiler Porting Guide -- Porting rustc via LLVM 19
- Persistent Storage Guide -- BlockFS filesystem and disk images
- vsh Shell Guide -- Bash-compatible shell usage and internals
- Release History -- Detailed per-release notes
- Invariants -- Architectural invariants (start here)
- Architecture -- System architecture
- Kernel Entry Points -- Where execution begins
- Capability Flow -- How capabilities govern services and drivers
Helpful diagrams:
- Architecture Capability Flow (Mermaid)
- Kernel Entry Points (Mermaid)
Unsafe Rust is permitted only to enforce higher-level invariants and is strictly controlled. Every unsafe block requires a // SAFETY: comment documenting the invariant it upholds. Coverage exceeds 100% (410 comments for 389 unsafe blocks).
See Unsafe Policy for the full policy.
Security is a foundational design principle, not a bolt-on layer:
- Capability-based access control -- Fine-grained, unforgeable permissions for all resources
- Memory safety -- Rust ownership guarantees plus KPTI, KASLR, SMEP/SMAP, W^X, and guard pages
- Post-quantum cryptography -- ML-DSA-65, ML-KEM alongside classical algorithms
- Mandatory access control -- Policy-driven RBAC and MLS enforcement
- Hardware security -- TPM 2.0, secure boot chain, IOMMU isolation
- Formal verification -- Kani proofs for critical kernel invariants; TLA+ specifications for protocol correctness
Contributions are welcome. Please see the Contributing Guide for details on the code of conduct, development workflow, coding standards, and pull request process.
- Discord Server -- Real-time chat
- Issue Tracker -- Bug reports and feature requests
VeridianOS is dual-licensed under:
- MIT License (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
You may choose either license for your use.
VeridianOS builds upon ideas from many excellent operating systems:
- seL4 -- Formal verification and capability systems
- Redox OS -- Rust OS development practices
- Fuchsia -- Component-based architecture
- FreeBSD -- Driver framework inspiration
- Linux -- Hardware support reference
Building the future of operating systems, one commit at a time.