# How to Run Linux on Windows Using LiteBox: A Complete Guide

> Run Linux on Windows without virtualization or WSL using LiteBox easily. Execute static Linux ELF binaries directly on Windows x86-64 with our complete guide.

- Repository: [Microsoft/litebox](https://github.com/microsoft/litebox)
- Tags: how-to-guide
- Published: 2026-02-16

---

**TL;DR:** LiteBox provides a Linux-compatible shim that runs on top of a Windows user-mode platform, allowing you to execute static Linux ELF binaries directly on Windows x86-64 without virtualization or WSL by using the `litebox_runner_linux_on_windows_userland` binary.

The `microsoft/litebox` repository implements a lightweight, user-mode sandbox that bridges Linux binaries to Windows host capabilities. By combining a Windows-specific platform implementation with a Linux ABI shim, LiteBox enables you to **run Linux on Windows using LiteBox** without administrative privileges or complex setup.

## Understanding the LiteBox Architecture for Linux on Windows

LiteBox uses a layered architecture to translate Linux system calls into Windows API calls. The system consists of four main components working together to provide seamless execution.

### The Windows Userland Platform

The `WindowsUserland` struct in [`litebox_platform_windows_userland/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_platform_windows_userland/src/lib.rs) implements the `litebox::platform::Provider` trait for Windows. It handles memory allocation via `VirtualAlloc`, raw mutexes, time queries, and critical FS-base management for the Linux ABI.

When initialized via `WindowsUserland::new()`, the platform registers a vectored exception handler using `AddVectoredExceptionHandler` to restore the FS-base register when Windows clears it during context switches. It also caches system information through `GetSystemInfo` to determine valid memory ranges.

### The Linux Shim Layer

The Linux shim in [`litebox_shim_linux/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_shim_linux/src/lib.rs) provides a complete Linux ABI implementation on top of the generic LiteBox platform. The `LinuxShimBuilder::new()` function fetches the global platform from `litebox_platform_multiplex::platform()` and constructs the shim environment.

This layer intercepts Linux system calls, translates them into platform-agnostic requests, and manages the guest's register state through `PtRegs` structures.

### The Multiplex Platform and Runner

The multiplex platform in [`litebox_platform_multiplex/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_platform_multiplex/src/lib.rs) selects the concrete `WindowsUserland` implementation at runtime and forwards platform-specific requests from the shim. This abstraction allows the same Linux shim to run on different host platforms.

The runner crate in [`litebox_runner_linux_on_windows_userland/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_runner_linux_on_windows_userland/src/lib.rs) orchestrates the entire process. Its `run()` function (starting at line 47) creates the platform instance, builds the Linux shim, translates Windows paths to Unix-style using `windows_path_to_unix`, constructs an in-memory file system, loads the ELF into the shim, and finally hands execution to the shim's thread loop via `run_thread`.

## Prerequisites for Running Linux Binaries on Windows

Before you can **run Linux on Windows using LiteBox**, ensure your environment meets these requirements:

- **Rust toolchain**: Install Rust via `rustup` and ensure `stable` channel is active (2024 edition)
- **Windows 10 or 11 (x86-64)**: The platform crate specifically targets `target_os = "windows"` and `target_arch = "x86_64"`
- **Static Linux ELF binary**: Compile your Linux program with static linking (e.g., `gcc -static`) to ensure all dependencies are embedded in the binary

## Step-by-Step Guide to Run Linux on Windows Using LiteBox

### Building the LiteBox Runner

Clone the repository and build the Windows-specific runner binary:

```bash
git clone https://github.com/microsoft/litebox
cd litebox

# Build the Windows-on-Linux runner (Windows-only crate)

cargo build -p litebox_runner_linux_on_windows_userland --release

```

The compiled binary appears at `target\release\litebox_runner_linux_on_windows_userland.exe`.

### Preparing Your Linux Binary

Create a static Linux binary on any Linux host:

```c
/* hello.c */
#include <stdio.h>
int main(void) {
    puts("Hello from Linux on Windows!");
    return 42;
}

```

Compile with static linking:

```bash
gcc -static -Os hello.c -o hello

```

Copy the resulting `hello` binary to your Windows machine (e.g., `C:\tmp\hello`).

### Executing the Binary on Windows

Run the Linux ELF directly through LiteBox:

```powershell
C:\> litebox_runner_linux_on_windows_userland.exe C:\tmp\hello
Hello from Linux on Windows!

```

Verify the exit code propagation:

```powershell
C:\> echo %ERRORLEVEL%
42

```

The runner automatically handles path translation via `windows_path_to_unix`, constructs the in-memory file system, and manages the syscall translation layer without requiring a virtual machine or WSL installation.

## How LiteBox Handles System Calls on Windows

When the Linux binary executes a `syscall` instruction, control transfers to the shim's `syscall_callback` assembly routine in `WindowsUserland`. The shim decodes the `SyscallRequest` and dispatches to the appropriate handler:

```rust
match request {
    SyscallRequest::Read { fd, buf, count } => {
        self.sys_read(fd, &mut kernel_buf, None)
    }
    SyscallRequest::Mmap { addr, length, prot, flags, fd, offset } => {
        self.sys_mmap(addr, length, prot, flags, fd, offset)
            .map(|ptr| ptr.as_usize())
    }
    _ => {
        log_unsupported!("{request:?}");
        Err(Errno::ENOSYS)
    }
}

```

Each syscall implementation runs in pure Rust within the LiteBox subsystems (`fs`, `network`, `futex`), ensuring memory safety while providing Linux-compatible behavior on the Windows host.

## Summary

- LiteBox enables you to **run Linux on Windows using LiteBox** without virtualization by providing a user-mode Linux ABI shim on top of a Windows platform implementation.
- The `litebox_runner_linux_on_windows_userland` binary orchestrates the process by creating a `WindowsUserland` platform, building a `LinuxShim`, translating paths via `windows_path_to_unix`, and loading the ELF into memory.
- All Linux system calls are intercepted and handled in safe Rust code within the shim, mapping to Windows APIs for memory, file system, and threading operations.
- You only need static Linux ELF binaries (compiled with `gcc -static`) and the Rust toolchain to get started—no administrator privileges or WSL installation required.

## Frequently Asked Questions

### Do I need administrator privileges to run LiteBox?

No. LiteBox operates entirely in user mode using standard Windows APIs such as `VirtualAlloc` and `AddVectoredExceptionHandler`. The `WindowsUserland` platform implementation in [`litebox_platform_windows_userland/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_platform_windows_userland/src/lib.rs) does not require kernel drivers or elevated permissions, making it safe to run in restricted environments.

### Can LiteBox run dynamically linked Linux binaries?

No, LiteBox currently only supports static Linux ELF binaries. You must compile your Linux programs with static linking (e.g., `gcc -static`) to ensure all dependencies are embedded in the binary. Dynamically linked binaries require a full Linux loader and shared library environment, which LiteBox does not provide in its current implementation.

### How does LiteBox performance compare to WSL?

LiteBox runs directly on the host CPU without virtualization overhead, so compute-bound workloads often perform faster than WSL2 (which runs in a lightweight VM). However, I/O operations go through LiteBox's abstraction layers and may be slower than native Windows sockets or WSL's optimized 9P file system bridge. The `litebox_runner_linux_on_windows_userland` binary handles all translations without hypervisor context switches.

### Can I embed LiteBox in my own Rust application?

Yes. The crates are designed to be embedded in larger projects. You can create a `WindowsUserland` instance, build a `LinuxShim` using `LinuxShimBuilder::new()`, load an ELF with `LinuxShim::load_program()`, and execute it via `run_thread`. All components are `no_std` capable where appropriate, allowing integration into specialized Rust environments without requiring the standalone runner binary.