VeridianOS is a research operating system written in Rust, focused on correctness, isolation, and explicit architectural invariants. It is intended as executable documentation of high-assurance systems design, not as a production OS or a general-purpose hobby kernel.
The project explores how capability-oriented design, strong isolation boundaries, and disciplined use of unsafe code can be combined to produce systems that are auditable, teachable, and resilient to failure. VeridianOS features a capability-based security model, zero-copy IPC, and multi-architecture support with an emphasis on reliability and deterministic behavior.
- π‘οΈ Capability-based security β Unforgeable tokens for all resource access
- π Microkernel architecture β Minimal kernel with services in user space
- π¦ Written in Rust β Memory safety without garbage collection
- β‘ High performance β Lock-free algorithms, zero-copy IPC
- π§ Multi-architecture β x86_64, AArch64, and RISC-V support
- π Security focused β Mandatory access control, secure boot, hardware security
- π¦ Modern package management β Source and binary package support
- π₯οΈ Wayland compositor β Modern display server with GPU acceleration
VeridianOS exists to explore and demonstrate:
- Capability-based system design with explicit authority boundaries
- Strong isolation between kernel, drivers, services, and userland
- Memory safety and ownership as architectural properties
- Deterministic, inspectable system behavior
- Long-horizon durability over short-term feature velocity
VeridianOS intentionally does not aim to be:
- A natively POSIX-based operating system (a POSIX compatibility layer is planned for future phases to support software porting, but native APIs remain capability-based)
- A Linux replacement or distribution
- A performance-first microbenchmark platform
- A feature-complete general-purpose OS
These exclusions are deliberate and protect architectural clarity. Where future compatibility layers are mentioned (e.g., POSIX, Wayland), they will be implemented as user-space libraries that translate to native capability-based interfaces, never as kernel-level compromises.
VeridianOS assumes a single-machine environment with a trusted toolchain. It focuses on software isolation failures, authority misuse, and memory safety violations. Physical attacks, malicious firmware, and advanced side-channel attacks are out of scope by design.
The system is defined by explicit invariants governing authority, isolation, memory ownership, and unsafe code usage. These are normative and binding.
See Invariants for the authoritative list.
VeridianOS uses a microkernel architecture with the following key components:
βββββββββββββββββββββββββββββββββββββββββββββββ
β User Applications β
βββββββββββββββββββββββββββββββββββββββββββββββ€
β System Services (VFS, Network, etc.) β
βββββββββββββββββββββββββββββββββββββββββββββββ€
β User-Space Drivers (Block, Network) β
βββββββββββββββββββββββββββββββββββββββββββββββ€
β Microkernel (Memory, Scheduling, IPC) β
βββββββββββββββββββββββββββββββββββββββββββββββ
kernel/ Trusted computing base
drivers/ Hardware interaction behind explicit privilege boundaries
services/ Capability-mediated system services
userland/ Intentionally constrained user processes
boot/ Bootloader and early initialization
docs/ Canonical specifications
experiments/ Non-normative exploratory work
Latest Release: v0.4.8 (February 16, 2026)
| Architecture | Build | Boot | Init Tests | Stage 6 | Stable Idle (30s) | Status |
|---|---|---|---|---|---|---|
| x86_64 | β | β | 29/29 | β | β PASS | 100% Functional -- UEFI boot via OVMF |
| AArch64 | β | β | 29/29 | β | β PASS | 100% Functional -- Direct kernel loading |
| RISC-V 64 | β | β | 29/29 | β | β PASS | 100% Functional -- OpenSBI boot |
| Phase | Description | Status | Version | Date |
|---|---|---|---|---|
| 0 | Foundation and Tooling | Complete | v0.1.0 | Jun 2025 |
| 1 | Microkernel Core | Complete | v0.2.1 | Jun 2025 |
| 2 | User Space Foundation | Complete | v0.3.2 | Feb 2026 |
| 3 | Security Hardening | Complete | v0.3.2 | Feb 2026 |
| 4 | Package Ecosystem | Complete | v0.4.0 | Feb 2026 |
| 5 | Performance Optimization | Planned | -- | -- |
| 6 | Advanced Features and GUI | Planned | -- | -- |
For detailed release notes, see Release History.
Phases 0 through 4 are complete. The kernel provides:
- IPC -- Synchronous/asynchronous channels with zero-copy fast path (<1us)
- Memory Management -- Hybrid bitmap+buddy allocator, NUMA-aware, 4-level page tables
- Process Management -- Full lifecycle with context switching on all architectures
- Scheduler -- CFS with SMP support, load balancing, CPU affinity
- Capability System -- 64-bit unforgeable tokens, two-level O(1) lookup, revocation, interrupt capabilities
- Interrupt Controllers -- x86_64 APIC (Local + I/O), AArch64 GICv2, RISC-V PLIC with unified IRQ abstraction
- VFS -- ramfs, devfs, procfs, blockfs with POSIX-style file operations
- Security -- MAC, secure boot, TPM 2.0, ASLR, W^X, Spectre barriers, KPTI, post-quantum crypto
- Package Manager -- DPLL SAT resolver, ports system, reproducible builds, Ed25519 signing
- Interactive Shell (vsh) -- Bash/Fish-parity serial console shell with pipes, redirections, variable expansion, globbing, tab completion, job control, scripting (if/for/while/case), functions, aliases
- Framebuffer Display -- 1280x800 text console via UEFI framebuffer (x86_64) and ramfb (AArch64/RISC-V), ANSI color support, PS/2 keyboard input via controller polling, glyph cache, pixel ring buffer, write-combining (PAT) on x86_64
- Userland Bridge -- Ring 0 to Ring 3 transitions with SYSCALL/SYSRET on x86_64
- Phase 5: Performance Optimization -- Sub-microsecond IPC, lock-free kernel paths, DPDK networking, NVMe optimization, profiling tools
- Phase 6: Advanced Features -- Wayland compositor, desktop environment, multimedia, virtualization, cloud-native features, POSIX compatibility layer
AArch64 FP/NEON fix: LLVM emits NEON/SIMD instructions (movi v0.2d, str q0) for buffer zeroing on buffers >= 16 bytes. Without CPACR_EL1.FPEN enabled, these instructions trap silently. Fixed by enabling FP/NEON in boot.S before entering Rust code.
UnsafeBumpAllocator on AArch64: AArch64 uses the same lock-free bump allocator as RISC-V, with a simple load-store allocation path (no CAS) and direct atomic initialization with DSB SY/ISB memory barriers.
bare_lock::RwLock: UnsafeCell-based single-threaded RwLock replacement for AArch64 bare metal, used in VFS filesystem modules to avoid spin::RwLock CAS spinlock hangs without proper exclusive monitor configuration.
AArch64 LLVM workaround: AArch64 bypasses a critical LLVM loop-compilation bug by routing print!/println! through DirectUartWriter, which uses uart_write_bytes_asm() -- a pure assembly loop that LLVM cannot miscompile. The kprintln! macro provides an alternative path using direct_print_str() for literal-only output. See README - LLVM Bug for details.
VeridianOS is an active research system. Phases 0 through 4 are architecturally stable; Phase 5 (performance) and Phase 6 (advanced features) are next.
Historical status is recorded in:
RELEASE-HISTORY.md-- Detailed per-release notesPROJECT-STATUS.mdPHASE2-STATUS-SUMMARY.mdBOOTLOADER-UPGRADE-STATUS.md
Normative truth lives in this README and docs/.
- Rust nightly-2025-11-15 or later
- QEMU 8.0+ (for testing)
- 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
./build-kernel.sh aarch64 release
./build-kernel.sh riscv64 dev
# Run in QEMU
just run
# Or build manually (x86_64 requires custom target)
cargo build --target targets/x86_64-veridian.json \
-p veridian-kernel \
-Zbuild-std=core,compiler_builtins,alloc
# Run in QEMU (x86_64 - requires UEFI disk image)
# First build the UEFI image:
./tools/build-bootimage.sh \
target/x86_64-veridian/debug/veridian-kernel \
target/x86_64-veridian/debug
# Then boot with OVMF firmware:
qemu-system-x86_64 \
-bios /usr/share/edk2/x64/OVMF.4m.fd \
-drive format=raw,file=target/x86_64-veridian/debug/veridian-uefi.img \
-serial stdio \
-display none
# Run in QEMU (AArch64)
qemu-system-aarch64 \
-M virt \
-cpu cortex-a57 \
-kernel target/aarch64-unknown-none/debug/veridian-kernel \
-serial stdio \
-display none
# Run in QEMU (RISC-V)
qemu-system-riscv64 \
-M virt \
-kernel target/riscv64gc-unknown-none-elf/debug/veridian-kernel \
-serial stdio \
-display noneFor detailed build instructions, see BUILD-INSTRUCTIONS.md.
- x86_64 β Full support (UEFI boot via bootloader 0.11.15)
- AArch64 β Full support (direct QEMU
-kernelloading) - RISC-V (RV64GC) β Full support (direct QEMU
-kernelloading via OpenSBI)
- 64-bit CPU with MMU
- 256MB RAM
- 1GB storage
- Multi-core CPU with virtualization support
- 4GB+ RAM
- NVMe storage
- π Architecture Overview β System design and architecture
- π οΈ Development Guide β Getting started with development
- π API Reference β System call and library APIs
- π§ͺ Testing Strategy β Testing approach and guidelines
- π Troubleshooting β Common issues and solutions
- πΊοΈ Implementation Roadmap β Detailed development plan
- π Software Porting Guide β Porting Linux software to VeridianOS
- π§ Compiler Toolchain Guide β Native compiler integration strategy
- π Future Development Insights β Analysis and recommendations
The project follows a phased development approach:
- Phase 0: Foundation β Build system and tooling
- Phase 1: Microkernel Core β Core kernel functionality
- Phase 2: User Space Foundation β Essential services
- Phase 3: Security Hardening β Security features
- Phase 4: Package Ecosystem β Package management
- Phase 5: Performance Optimization β Performance tuning
- Phase 6: Advanced Features β GUI and advanced features
See PROJECT-STATUS.md for detailed status information and Master TODO for task tracking.
- Invariants β Architectural invariants (start here)
- Architecture β System architecture
Helpful diagrams:
- Kernel Entry Points β Kernel entry points
- Capability Flow β Capability flow into services and drivers
Unsafe Rust is permitted only to enforce higher-level invariants and is strictly controlled.
See Unsafe Policy.
VeridianOS is not a performance-first system, but targets reasonable latency for a research microkernel:
Phase 1 targets (achieved):
- IPC Latency: < 5ΞΌs
- Context Switch: < 10ΞΌs
- Microkernel Size: < 15,000 lines of code
Phase 5 targets (planned):
- IPC Latency: < 1ΞΌs
- Memory Allocation: < 1ΞΌs
- System Call Overhead: < 100ns
- Support for 1000+ concurrent processes
Design properties that support these targets include lock-free data structures in critical paths, zero-copy IPC, NUMA-aware memory allocation, and sub-microsecond system call paths.
Security is a fundamental design principle:
- Capability-based access control β Fine-grained, unforgeable permissions
- Secure boot β Full chain of trust verification
- Memory safety β Rust's ownership guarantees plus runtime checks
- Mandatory access control β SELinux-style policies
- Hardware security β TPM, HSM, and TEE integration
- Phase 0: Foundation and Tooling (v0.1.0, Jun 2025)
- Phase 1: Microkernel Core (v0.2.1, Jun 2025)
- Phase 2: User Space Foundation (v0.3.2, Feb 2026)
- Phase 3: Security Hardening (v0.3.2, Feb 2026)
- Phase 4: Package Ecosystem and Self-Hosting (v0.4.0, Feb 2026)
- Phase 5: Performance Optimization (5-6 months) -- Sub-microsecond IPC, lock-free kernel paths, DPDK networking, NVMe optimization
- Phase 6: Advanced Features (8-9 months) -- Wayland compositor, desktop environment, multimedia, virtualization, cloud-native, POSIX compatibility layer
See Release History for detailed per-release notes.
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.