← Back to Blog

Implementing 456 Linux Syscalls on Bare Metal — Running Linux Binaries Without Linux

Matt Gates · April 2, 2026 · 12 min read

ClaudioOS doesn't have a Linux kernel. It doesn't have a POSIX layer. It's a bare-metal Rust application that manages its own hardware. But it runs unmodified Linux ELF binaries -- including compilers, interpreters, and command-line tools -- through a syscall translation layer that operates entirely in Ring 0.

This is the story of how we implemented 456 Linux syscalls on bare metal, and what "Linux compatible" actually means when you're doing it yourself.

Why Linux Binary Compatibility?

When we built ClaudioOS as a purpose-built environment for AI coding agents, we faced a practical problem: agents need tools. They need git, cargo, python3, gcc, text processing utilities. We could rewrite all of these from scratch (and we did write some -- a Python interpreter, a Rust compiler via Cranelift), but running existing Linux binaries gives us the entire ecosystem for free.

The key insight: Linux binaries don't actually need Linux. They need the syscall interface that Linux provides. If we implement that interface, the binaries don't know the difference.

The ELF Loader

Every Linux binary is an ELF (Executable and Linkable Format) file. Loading one means:

  1. Parsing the ELF header to find program headers
  2. Mapping each PT_LOAD segment into memory at the specified virtual address
  3. Setting up the initial stack with argc, argv, envp, and the auxiliary vector
  4. Handling the dynamic linker (PT_INTERP) for dynamically linked binaries
  5. Jumping to the entry point

The auxiliary vector is the tricky part. The kernel passes information to the program through AT_* entries on the stack: page size, UID, GID, hardware capabilities, the VDSO address. Linux programs expect these to be there. Miss one and glibc will segfault during initialization before main() ever runs.

// Setting up the initial stack for an ELF binary
fn setup_stack(
    stack_top: VirtAddr,
    args: &[&str],
    env: &[&str],
    auxv: &[(u64, u64)],
) -> VirtAddr {
    let mut sp = stack_top;

    // Push strings (argv values, env values)
    let argv_ptrs = args.iter().map(|a| {
        sp -= a.len() as u64 + 1;
        copy_to_user(sp, a.as_bytes());
        write_byte(sp + a.len() as u64, 0); // null terminator
        sp
    }).collect::<Vec<_>>();

    // Align stack to 16 bytes
    sp = sp & !0xF;

    // Push auxiliary vector (AT_NULL terminated)
    push_u64(&mut sp, 0); // AT_NULL
    push_u64(&mut sp, 0);
    for &(key, val) in auxv.iter().rev() {
        push_u64(&mut sp, val);
        push_u64(&mut sp, key);
    }

    // Push envp, argv, argc
    push_u64(&mut sp, 0); // envp terminator
    // ... env pointers ...
    push_u64(&mut sp, 0); // argv terminator
    for ptr in argv_ptrs.iter().rev() {
        push_u64(&mut sp, ptr.as_u64());
    }
    push_u64(&mut sp, args.len() as u64); // argc

    sp
}

The Syscall Dispatcher

On x86_64, Linux syscalls use the SYSCALL instruction. The kernel sets up Model Specific Registers (MSRs) to define where the CPU jumps when SYSCALL executes:

In a normal OS, SYSCALL switches from Ring 3 (user) to Ring 0 (kernel). But ClaudioOS runs everything in Ring 0. There's no mode switch. The SYSCALL instruction still fires, we still catch it, but we skip the entire privilege transition overhead.

// Syscall entry point -- called by the SYSCALL instruction
// rax = syscall number, rdi/rsi/rdx/r10/r8/r9 = args
#[naked]
unsafe extern "C" fn syscall_entry() {
    asm!(
        "swapgs",               // get kernel GS base
        "mov gs:[0x8], rsp",     // save user stack
        "mov rsp, gs:[0x0]",     // load kernel stack
        "push rcx",              // save return address
        "push r11",              // save RFLAGS
        "mov rcx, r10",          // Linux convention: arg4 in r10
        "call {dispatch}",
        "pop r11",
        "pop rcx",
        "mov rsp, gs:[0x8]",     // restore user stack
        "swapgs",
        "sysretq",
        dispatch = sym syscall_dispatch,
        options(noreturn),
    );
}

The Big Ones: What Actually Matters

Of 456 implemented syscalls, about 40 do the heavy lifting. The rest are either trivially stubbed (return 0 or ENOSYS) or rare enough that a basic implementation suffices. Here's what consumed 80% of the effort:

Memory: mmap / mprotect / munmap / brk

mmap is the foundation. Every malloc eventually calls it. Every shared library is loaded through it. Every file can be memory-mapped through it. Our implementation supports MAP_ANONYMOUS, MAP_PRIVATE, MAP_FIXED, and file-backed mappings. We manage a per-process virtual memory area (VMA) list that tracks every mapping.

File I/O: open / read / write / close / stat / lseek

We maintain a virtual filesystem layer that maps paths to backends: our FAT32 partition for persistent storage, a procfs for /proc/self/ queries, a devfs for /dev/null and /dev/urandom, and a tmpfs for scratch space. File descriptors are integers indexing into a per-task table -- just like Linux.

Networking: socket / bind / connect / sendto / recvfrom / epoll

Network syscalls translate directly to our smoltcp stack. A socket(AF_INET, SOCK_STREAM, 0) creates a smoltcp TCP socket. connect() initiates the three-way handshake. epoll maps to our async executor's waker mechanism -- when the NIC interrupt fires and smoltcp processes packets, we wake the corresponding futures.

Threading: clone / futex / set_tid_address

Threading was the most challenging. clone with CLONE_THREAD creates a new async task that shares the memory space. futex is the building block for mutexes, condition variables, and barriers in userspace. Our implementation handles FUTEX_WAIT, FUTEX_WAKE, and FUTEX_WAIT_BITSET -- enough for glibc's pthread implementation.

Category Syscalls Implementation
Memory management 28 Full (mmap, mprotect, munmap, brk, mremap...)
File I/O 67 Full (open, read, write, stat, ioctl, fcntl...)
Networking 22 Full (socket, bind, connect, epoll, select...)
Process/Thread 41 Full (clone, futex, wait4, execve, exit_group...)
Signals 18 Partial (rt_sigaction, rt_sigprocmask, kill)
Time 12 Full (clock_gettime, nanosleep, timer_create...)
Identity/Security 34 Stubbed (getuid returns 0, everything is root)
Misc/Compat 234 Stubbed or minimal (returns 0 or ENOSYS)

What "Linux Compatible" Really Means

Let's be honest about what we do and don't support:

We support: Statically linked ELF binaries. Dynamically linked binaries with a bundled ld-linux.so. Programs that use standard POSIX I/O, networking, threading, and memory management. This covers most command-line tools, compilers, interpreters, and servers.

We don't support: Full signal semantics (signals are best-effort, not preemptive). ptrace (no debugger support). seccomp (no sandboxing -- everything is Ring 0 anyway). Complex ioctl operations on real devices. Anything that assumes a specific Linux kernel version's ABI for obscure interfaces.

We deliberately skip: Process isolation. There's no Ring 3. No page table switching between processes. Every "process" is a task in our async executor sharing one address space. This is a feature, not a bug -- it means zero-cost "syscalls" for the hot path.

Performance: The Ring 0 Advantage

On Linux, every syscall involves:

  1. User code executes SYSCALL
  2. CPU switches to Ring 0, swaps stacks, saves state
  3. Kernel validates arguments, checks permissions
  4. Kernel does the actual work
  5. SYSRET switches back to Ring 3

On ClaudioOS, steps 2 and 5 are nearly free because we're already in Ring 0. Step 3 is simplified because there are no permission boundaries to check. The SYSCALL instruction still fires (we can't avoid that -- it's what the binary uses), but the overhead is a function call, not a privilege transition.

For I/O-heavy workloads (compilers, file processing, network tools), this means measurably less time spent in overhead. The CPU does work instead of switching contexts.

The takeaway: You don't need Linux to run Linux binaries. You need the interface -- the syscall numbers, the register conventions, the data structures. Implement the interface, and the binaries can't tell the difference. They just run faster because you threw away the parts that only exist for isolation you don't need.

What's Next

We're working on execve chaining (running programs that spawn other programs), proper /proc filesystem emulation for tools that introspect the system, and expanding our signal delivery to support SIGCHLD properly. The goal is to run a full cargo build inside ClaudioOS by Q3 2026 -- a Rust compiler compiling Rust, on an OS written in Rust, assisted by an AI that writes Rust.

Matt Gates builds ClaudioOS at Ridge Cell Repair LLC. He thinks syscall tables are underrated reading material.

← Back to Blog · ClaudioOS Home · GitHub