axeberg Documentation
A mini operating system written in Rust, compiled to WebAssembly.
Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ Browser │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ axeberg OS │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Shell $ cat file | grep pattern | wc -l │ │ │
│ │ └─────────────────────────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ WASM Loader /bin/cat.wasm → /bin/grep.wasm → /bin/wc.wasm│ │ │
│ │ └─────────────────────────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Kernel │ │ │
│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │
│ │ │ │ Syscalls │ │ Processes │ │ VFS │ │ Memory │ │ │ │
│ │ │ │ (300+) │ │ + Signals │ │ MemoryFs │ │ COW/mmap │ │ │ │
│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │
│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │
│ │ │ │ Executor │ │ IPC │ │ Timers │ │ Users │ │ │ │
│ │ │ │ Async/WS │ │ pipe/shm │ │ Async │ │ + Caps │ │ │ │
│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Compositor (WebGPU) / Terminal │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Design Principles
| Principle | Description |
|---|---|
| Tractable | Entire system comprehensible by one person |
| Immediate | Changes take effect instantly |
| Personal | Your computing environment, under your control |
Documentation
Kernel
| Document | Description |
|---|---|
| Overview | High-level architecture |
| Syscalls | System call API reference |
| Processes | Process model, states, sessions |
| Memory | Allocation, COW, mmap |
| Executor | Async task execution |
| Work Stealing | Parallel scheduler |
| Users & Groups | Multi-user system, capabilities |
| Signals | Signal system |
| IPC | Inter-process communication |
| Timers | Timer scheduling |
| Objects | Kernel object reference counting |
| WASM Modules | Command format and ABI |
| Tracing | Instrumentation |
Userspace
| Document | Description |
|---|---|
| Shell | Command-line interpreter |
| VFS | Virtual filesystem |
| Layered FS | Union filesystem |
| Standard I/O | Console and pipes |
Development
| Document | Description |
|---|---|
| Building | Build instructions |
| Testing | Test suite |
| Contributing | Development guidelines |
| Invariants | System invariants |
Guides
| Document | Description |
|---|---|
| Custom Commands | Writing shell commands |
| VFS Backends | Implementing filesystems |
| Adding Syscalls | Extending the kernel |
Architecture
| Document | Description |
|---|---|
| Decision Records | Architecture decisions (ADRs) |
| Bare Metal | Future: x86_64 port |
| Compositor | WebGPU window management |
Quick Start
# Build
wasm-pack build --target web
# Run
cargo run --bin serve
# Open http://localhost:8080
# Test
cargo test
Command Execution Flow
User Input: "cat file.txt | grep hello"
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Parser │
│ ├─ Tokenize: ["cat", "file.txt", "|", "grep", "hello"] │
│ └─ Build: Pipeline { commands: [SimpleCommand, SimpleCommand] } │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Executor │
│ ├─ Create pipe for stdout → stdin │
│ ├─ Spawn process for "cat" with redirected stdout │
│ └─ Spawn process for "grep" with redirected stdin │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Kernel │
│ ├─ Process 1: cat reads /file.txt via VFS, writes to pipe │
│ └─ Process 2: grep reads from pipe, writes matches to terminal │
└─────────────────────────────────────────────────────────────────────┘
Key Design Decisions
| Decision | Rationale |
|---|---|
| Monolithic kernel | WASM lacks MMU/privilege levels |
| Async cooperative | Browser event loop integration |
| WASM commands | Isolation, extensibility |
| Reference-counted objects | Simple lifetime management |
| Layered VFS | In-memory with OPFS persistence |
License
MIT