WasmLinux: A WebAssembly-Native Linux System#

Breaking Away from Emulation#

Traditional approaches to running Linux in WebAssembly environments include:

• WebVM: Uses x86 emulation
• container2wasm: Supports RISC-V and x86 emulation

WasmLinux takes a fundamentally different approach by eliminating CPU architecture emulation entirely. Both the kernel and userland applications are compiled directly to WebAssembly, creating a native Wasm Linux environment.

Core Architecture#

WasmLinux consists of three main components:

1. Patched NOMMU Linux (LKL): Linux Kernel Library - essentially the Linux kernel implemented as a userland library
2. Lightly patched Linux MUSL libc: A lightweight C library optimized for static linking
3. Lightly patched BusyBox: Provides essential Unix utilities in a single executable

All components are:

• Compiled to WebAssembly
• Processed with Wasm2c
• Recompiled with Emscripten (currently required for setjmp/longjmp support)

The Kernel Implementation#

WasmLinux’s kernel is actually a WebAssembly executable containing LKL (Linux Kernel Library). This means there’s no traditional “kernel mode” - everything runs in userspace from the host’s perspective. The kernel exposes its functionality through Wasm exports that the runtime can call.

Syscall Protocol#

The syscall mechanism in WasmLinux is elegantly simple:

• User code makes syscalls through the standard libc interface
• These are translated into Wasm exports
• The runner (host) calls the kernel through its Wasm exports
• The runner maintains knowledge of syscall argument counts for proper Wasm function calling

Current Capabilities#

Despite being a prototype, WasmLinux already supports impressive functionality:

• Basic file operations
• Process management (with NOMMU limitations)
• Networking (loopback interface)
• Standard Unix utilities via BusyBox
• Text editing with vi
• System monitoring with top
• Network configuration and testing

Signal Handling#

The most significant limitation is the lack of asynchronous signal delivery. This creates several issues:

• Commands require an extra Enter key press to interrupt read(2) operations
• Piping doesn’t work properly (dmesg | less fails)
• Command sequencing is broken (ls; ls doesn’t work)

Memory Management#

As a NOMMU (no Memory Management Unit) system:

• No mmap(2) support
• No fork(2) - only vfork() is available
• No virtual memory or memory protection
• Limited process isolation

Dependencies on Non-Standard Features#

Currently relies on:

• Wasm2c for translation
• Emscripten for setjmp/longjmp support
• These dependencies will be eliminated once native WebAssembly implementations are available

Near-Term Goals#

1. Native Browser Wasm Support: Eliminate wasm2c overhead using browser Wasm implementation with Wasm Exceptions
2. Asynchronous Signal Delivery: Implement proper signal handling (though usermode interruption will remain limited)
3. WebRTC-Based VPN: Enable inter-browser and local system networking using libdatachannel
4. Graphics Support: Implement C-WebGL and EGL/OpenGL ES bridge layers
5. Memory Protection: Static Wasm translation for memory protection without address translation
6. Shared Libraries: Enable dynamic linking support
7. wasm32-linux ABI: Define a standard ABI and provide SDK for application development

Long-Term Vision#

The ultimate goal is to support:

• Full microcontroller toolchain (ARM, etc.)
• CMake build system
• LLDB debugger
• All running directly in the browser

Self-hosting capabilities are considered, though the 32-bit limitation presents practical challenges.

Write Once, Run Anywhere (Finally?)#

WasmLinux addresses a fundamental challenge in cross-platform development. While WASI and WALI require applications to be ported to their specific environments, WasmLinux provides a complete Linux kernel implementation. This means:

• Minimal porting effort for existing Linux applications
• Full filesystem and device driver support
• Standard Linux APIs and behaviors

Solving the Chicken-and-Egg Problem#

Many Linux applications make assumptions that don’t translate well to WebAssembly:

• ELF binary format expectations
• Computed gotos
• __builtin_return_address usage
• Implicit function pointer casts

WasmLinux demonstrates that these challenges can be overcome, potentially driving WebAssembly specification improvements.

Beyond Traditional Virtualization#

By avoiding CPU emulation, WasmLinux achieves:

• Better performance potential
• Smaller binary sizes
• True platform independence
• Direct integration with browser APIs

Build Flow#

The build process involves:

1. Compiling Linux kernel (LKL) to WebAssembly
2. Compiling MUSL libc and BusyBox to WebAssembly
3. Processing with wasm2c for C translation
4. Final compilation with Emscripten for runtime support

Runtime Architecture#

The runtime includes:

• Pseudo inetd: Manages process invocation on incoming connections
• miniio library: Abstracts host I/O operations
• libuv backend: Handles I/O on PC builds
• Browser-specific backends: Localhost-only stub implementation using host pthreads

Communication Layer#

WasmLinux uses:

• BusyBox telnetd for system communication
• Conventional telnet clients on PC builds
• Custom minitelnet implementation for browser environments
• xterm-pty for terminal emulation in the browser

Basic Commands#

Once WasmLinux loads in your browser:

1. Wait for the / # prompt
2. Try basic commands:
   • ls - List files (remember to press Enter twice)
   • vi - Edit text files
   • dmesg - View kernel messages
   • ifconfig lo up - Configure loopback interface
   • ping 127.0.0.1 - Test networking
   • top - Monitor system processes
   • busybox - List all available commands

Working Around Limitations#

Due to current limitations:

• Instead of dmesg | less, use dmesg > out then less out
• Avoid command sequencing with ;
• Be patient with the double-Enter requirement