JerichoOS 🛡️

A capability-based microkernel with WebAssembly sandboxing

Features • Quick Start • Architecture • Benchmarks • Docs

---

Overview

JerichoOS is a research microkernel built in Rust (no_std) exploring capability-based security and WebAssembly isolation in bare-metal environments. It runs untrusted WASM modules with fine-grained access control, demonstrating how modern sandboxing can work at the kernel level.

Why JerichoOS?

• Capability Security: Fine-grained access control for kernel services
• Memory Safe: Rust with unsafe contained to narrow, audited boundaries
• WASM Runtime: Run untrusted code safely using wasmi interpreter
• Dual Architecture: Unified codebase for x86-64 and ARM64
• Research-Focused: Designed for learning and experimentation

---

Features

Security Capability-based IPC WASM sandbox isolation Memory-safe kernel core Protected syscall interface

Runtime Preemptive scheduler Inter-process messaging Host function bridging Stack overflow protection

Portability x86-64 support (QEMU) ARM64/AArch64 (Cortex-A57) Exception level transitions Platform abstraction layer

---

Current Status

Component	x86-64	ARM64	Notes
Kernel Boot	✅	✅	QEMU virt machine
WASM Runtime	✅	✅	wasmi 0.31
Demo Suite	✅	✅	5 demos passing
Capability System	✅	✅	IPC enforcement working
Scheduler	✅	✅	Preemptive multitasking
CI/CD	✅	✅	GitHub Actions

Latest Verification: October 19, 2026 ... both demo suites pass on QEMU 8.2.2

---

Quick Start

Prerequisites

# Install Rust nightly toolchain
rustup toolchain install nightly
rustup component add rust-src llvm-tools-preview

# Install QEMU
# Ubuntu/Debian:
sudo apt install qemu-system-x86 qemu-system-arm

# macOS:
brew install qemu

Run Demos

x86-64

./demo_x86.sh

ARM64

./demo_arm64.sh

Expected Output:

✓ Demo 1: Pure Computation        PASS
✓ Demo 2: Host Function Calls     PASS
✓ Demo 3: Syscall & Capability    PASS
✓ Demo 4: MQTT Broker Pub/Sub     PASS
✓ Demo 5: Security & Isolation    PASS

RESULT: PASS

---

Architecture

┌────────────────────────────────────────────┐
│      WASM Modules (Sandboxed)              │
│  ┌───────────┐  ┌──────────┐  ┌──────────┐ │
│  │ mqtt.wasm │  │ app.wasm │  │ test.wasm│ │
│  └───────────┘  └──────────┘  └──────────┘ │
└─────────────┬──────────────────────────────┘
              │
    ┌─────────▼──────────┐
    │  wasmi Interpreter │
    │  (Host Bridge)     │
    └─────────┬──────────┘
              │
    ┌─────────▼────────────┐
    │  Capability Checker  │
    │  (Access Control)    │
    └─────────┬────────────┘
              │
    ┌─────────▼────────────┐
    │  Syscall Layer       │
    │  IPC • Print • MQTT  │
    └─────────┬────────────┘
              │
    ┌─────────▼────────────┐
    │  Scheduler Core      │
    │  Memory • Interrupts │
    └─────────┬────────────┘
              │
    ┌─────────▼───────────┐
    │  Architecture Layer │
    │  x86-64 │ ARM64     │
    └─────────────────────┘

Key Components

• WASM Runtime: Sandboxed execution environment with wasmi interpreter
• Capability System: Token-based access control for kernel resources
• IPC Layer: Message passing between isolated modules
• Scheduler: Cooperative/preemptive task switching
• Architecture Abstraction: Shared kernel logic across x86-64 and ARM64

---

Demo Suite

The kernel includes five demonstration programs showcasing core features:

Demo	Description	Key Features
1. Pure Computation	Arithmetic operations in WASM	Basic execution, stack operations
2. Host Functions	Calling kernel services	Host bridge, print syscalls
3. Syscall & Capability	Protected resource access	Capability checks, syscall dispatcher
4. MQTT Pub/Sub	Message broker simulation	IPC, multi-module coordination
5. Security	Isolation enforcement	Sandbox escapes, unauthorized IPC

---

Benchmarks

Measured in QEMU TCG with a calibrated clock (TSC vs PIT on x86-64, CNTFRQ on ARM64):

	x86-64	ARM64
Capability syscall (derive/revoke)	~210-245 ns	~250-290 ns
IPC send + receive, 64 B	~1.1-1.2 µs	~1.4 µs
Context switch	~260-370 ns	~370-590 ns
Boot (kernel entry to ready)	~16-19 ms	~1 ms

⚠️ Note: QEMU numbers are relative indicators for comparing kernel changes on one host, not hardware performance.

See BENCHMARKS.md for exactly what each line times.

---

Repository Structure

jerichoos/
├── src/
│   ├── main.rs, main_aarch64.rs   # thin entry points, one per architecture
│   ├── kernel.rs         # shared boot sequence, heap, panic handler
│   ├── arch/x86_64/      # GDT/TSS, IDT + PIC + PIT, paging + heap, TSC, context switch
│   ├── arch/aarch64/     # boot.S, vectors, GIC, timer, MMU, context switch
│   ├── scheduler.rs      # round-robin, cooperative + timer preemption
│   ├── sync.rs           # irq-safe spinlock
│   ├── capability.rs     # rights, capabilities, CSpace
│   ├── ipc.rs            # capability-checked endpoints, blocking receive, cap transfer
│   ├── syscall.rs        # 5-call capability syscall dispatcher
│   ├── wasm_runtime.rs   # wasmi + the 7 host functions
│   ├── benchmark.rs      # measured benchmarks (see BENCHMARKS.md)
│   └── demos/            # 5 WASM demos + the kernel tasks
├── demos/wasm/           # WASM modules (.wat sources + vendored .wasm)
├── .github/workflows/    # CI pipelines
├── demo_x86.sh, demo_arm64.sh, bench_x86.sh, bench_arm64.sh
└── docs/                 # project status and known limitations

---

Development

Build from Source

# x86-64 kernel (two passes: build.rs creates boot images once the kernel binary exists)
cargo build --bin jericho_os --release --features bootloader-build
touch build.rs
cargo build --bin jericho_os --release --features bootloader-build

# ARM64 kernel
./build_arm64.sh

Quality Gates

Before committing, ensure all checks pass:

# Build verification
cargo check --bin jericho_os --release
cargo check --bin jericho_os_arm64 --release \
    --target aarch64-jericho.json \
    -Z build-std=core,compiler_builtins,alloc

# Run test suites
./demo_x86.sh && ./demo_arm64.sh

---

Known Limitations

• No user mode: syscalls are function calls from kernel tasks or the WASM bridge; WASM linear memory is the isolation boundary
• Revocation: removes one capability slot; there is no derivation tree, so derived copies survive
• Memory Management: x86-64 extends the bootloader's tables for the heap; ARM64 is an identity map with 2 MB blocks
• MQTT Demos: broker and publisher are vendored prebuilt .wasm example modules; the subscriber is built from .wat in this repo (see demos/wasm/README.md)

See PROJECT_STATUS.md for the full list of limitations.

---

Documentation

• Project Status — Current capabilities and known issues
• Benchmarks — What each benchmark measures and its limits

---

Contributing

JerichoOS is a research/learning project. Contributions are welcome for:

• Bug fixes and stability improvements
• Documentation enhancements
• Performance optimizations
• Architecture-specific improvements

Please ensure all quality gates pass before submitting PRs.

---

License

MIT License - See LICENSE for details.

---

Acknowledgments

Built with:

• Rust — Memory-safe systems programming
• wasmi — WebAssembly interpreter
• QEMU — Hardware emulation

Special thanks to the Rust embedded and OS dev communities.

---

⬆ Back to Top

Made with 🦀 by BashfulHippo