System Overview
CLEANOS CORE ARCHITECTURE
CleanOS is a modern, distributed, and highly secure microkernel operating system. Unlike traditional monolithic kernels (such as Linux or the NT kernel), all hardware drivers, network stacks, and filesystems run outside kernel space. Each subsystem is isolated in its own privileged thread in Ring 3 (user space).
Communication between components is handled via a high-performance, asynchronous, and lock-free IPC layer managed in Ring 0 by the GLOBAL_ROUTER. This prevents thread blocking and minimizes IPC overhead.
Core Kernel Services
Microkernel & Isolation
MEMORY SCHEDULING AND SLAB LIMITS
The kernel is written in `no_std` Rust and manages only CPU scheduling, interrupt handling (APIC), and the physical page allocator. Memory protection is twofold to rule out resource exhaustion and malware escalation:
Hard Page Frame Quotas
Each Ring 3 process is limited to a maximum of 512 frames (2 MB) and EPT micro-VMs to a maximum of 2048 frames (8 MB). The allocator verifies quotas via can_alloc and charges them atomically. This prevents a process from ever exhausting system memory, keeping the kernel free of Out-Of-Memory (OOM) panics.
No-Execute (NX) Config Storage
Drivers store their hardware configuration and status registers in specific memory pages under /etc/drivers/config/. These pages are marked as strictly No-Execute (NX) in the EPT by the kernel. Code injection attacks in these buffers fail immediately with a Hardware Protection Fault.
Driver Crash Recovery
FAULT REDIRECTION & SYSTEM V ABI WATCHDOGS
Ring 3 drivers are executed via the driver_thread! macro and run under the supervision of a kernel watchdog thread. When a driver crashes (due to a Page Fault or General Protection Fault), our recovery protocol is activated:
1. ABI-Compliant Stack Redirection (Interrupt Interception)
The CPU triggers an interrupt vector (e.g., `#PF` via Vector 14). The kernel interrupt handler intercepts this, inspects the InterruptStackFrame, and modifies the instruction register (RIP) to jump to driver_fault_resume. In the `catch_driver_fault_asm` trampoline, all callee-saved registers of the System V AMD64 ABI (rbx, rsp, rbp, r12, r13, r14, r15) are saved and restored, which rules out memory corruption in the scheduler.
2. Watchdog Registry & Thread Replacement
A watchdog daemon ticks every 200 ms. If the driver does not respond within 500 ms (last_poll_tick expires), the watchdog marks the thread ID as stale and immediately spawns a fresh thread. As soon as the old hanging thread eventually wakes up, it verifies via is_current_thread(name, tid) if its thread ID is still registered. If not, the thread terminates itself immediately (zombie prevention).
3. Anti-Crash Loop Limiters
The watchdog registers crash timestamps per driver. If a driver crashes more than 5 times per second, the watchdog stops the auto-restart process and switches to a safe fallback driver or requests assistance from the AI Daemon.
CleanDrive Object Store
BLAKE3 MERKLE TREES & COPY-ON-WRITE COMMIT SLOTS
CleanDrive discards the concepts of sectors, partitions, and directory trees. Instead, CleanDrive is a fully content-addressed object store based on cryptographic hashes:
- Chunk-level deduplication: Every file is split into blocks. Each unique block is stored physically only once, regardless of filename or location.
- BLAKE3 Content Hashes: File paths are translated into Merkle Tree hashes. Data integrity is continuously validated during every read and write operation.
- Transactional Copy-on-Write: Data is never overwritten in place. Changes create new chunks and update the Merkle root. Only when the transaction is successfully completed, the filesystem commits the new Merkle root to a hardware commit slot. If the system crashes in the meantime, it immediately rolls back to the last known good slot.
AI-Reasoning Layer
CLIENT-SIDE INFERENCE & LAZY FRAME ZEROING
The ai_daemon is a Ring 3 service that monitors system failures locally and directs recovery actions.
Dynamic RAM-Aware 5-Tier Model Selection
At startup, the daemon checks physical memory and selects across five distinct tiers spanning two base models: TinyQ4 (4-4.5 GB, CleanThinker-0.5B-SFT-Q4_K_M.gguf), TinyQ5 (4.5-5.5 GB, CleanThinker-0.5B-SFT-Q5_K_M.gguf), and TinyQ8 (5.5-7 GB, CleanThinker-0.5B-SFT-Q8_0.gguf) powered by the 0.5B base engine (~0.5 GB), as well as Standard (7-16 GB, CleanThinker-3B-SFT-Q5_K_M.gguf, ~2.02 GB) and Pro (> 16 GB, CleanThinker-3B-SFT-Q8_0.gguf, ~3.05 GB) powered by the 3B base engine. Each base size maintains its own cryptographically signed .cmod add-on stacks (3B tier ~54 MB vs. Tiny tier ~15.9 MB).
GGUF Inference & `` Blocks
When a driver crashes, the driver manager sends the register and crash log via IPC to the daemon. The daemon loads the signed few-shot.json rules (signature validated with the embedded public key) and performs a local inference step. The model reasons in a `
Lazy Frame Zeroing
If the AI action is RESET_AND_ZERO, the kernel stops the driver, submits all active frames to the LAZY_ZERO_QUEUE, and restarts the driver. An asynchronous background worker (lazy_zero_worker) overwrites the released physical frames with zeros in batches, ruling out leaks of sensitive driver data (such as network keys or framebuffers).
App Packaging (.capp)
CRYPTOGRAPHIC CAPP CONTAINERS & STAGED UPDATE RINGS
Applications and drivers are distributed as cryptographic containers with the extension .capp. Each file consists of:
- Header & Manifest: Metadata about the app author, version dependencies, and required system permissions.
- Ed25519 Signature: A cryptographic signature placed by the Tech-Bunker build pipeline. The kernel verifies the signature and the BLAKE3 hash against the central trust database (
/api/v1/verify/) before allowing execution. - Payload: The compressed executable file and static assets, which are loaded directly into a sandbox micro-VM via CleanDrive.