# LiteBox: Microsoft's library OS for sandboxing Linux programs on Windows and elsewhere

> LiteBox is a Rust sandboxing library OS that narrows the interface to the host and splits into a North shim and a South platform. It is aimed at engineers who run untrusted or foreign binaries and want to reason about a small syscall surface, not at anyone who needs a stable API today.

**microsoft/litebox** — A security-focused library OS supporting kernel- and user-mode execution

- Repository: https://github.com/microsoft/litebox
- Stars: 2,694 · Forks: 145
- Language: Rust
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoft-litebox

## What LiteBox solves, and who is meant to use it

Every sandbox is a bet about surface area. The larger the interface a program shares with its host, the more code an attacker can reach. LiteBox takes that bet literally: it is described in the README as a "sandboxing library OS that drastically cuts down the interface to the host, thereby reducing attack surface." Instead of emulating every host call, it presents a narrow, Rust-flavored interface modeled on the nix and rustix crates, and asks the host to satisfy only that.

The intended audience is narrow. The README lists example use cases: running unmodified Linux programs on Windows, sandboxing Linux applications on Linux, running programs on top of SEV SNP, running OP-TEE programs on Linux, and running on LVBS. These are all situations where a binary expects one operating system and is being placed on another, or where a program is untrusted enough that you want a small contract between it and the machine. Someone writing an ordinary Linux daemon has no reason to be here.

The repository layout confirms how seriously the split is taken. There are separate crates for the Linux kernel, Linux userland, Windows userland and LVBS platforms, and separate shims for Linux and OP-TEE. Each combination exists as its own crate rather than as a configuration flag inside one binary, which tells you the maintainers expect the pairings to diverge in behavior, not just in constants.

## North shims, South platforms, and the runners that wire them

The architecture is a two-sided contract. At the bottom sits a Platform, the "South" interface, which is whatever the host can actually do. At the top sits a shim, the "North" interface, which is what the guest program sees. The README describes the North side as a "Rust-y nix/rustix-inspired" interface, which matters because it means the guest-facing API is not a raw syscall table but a Rust abstraction over one.

Because the two sides are independent, the repository contains a matrix rather than a single program. litebox_shim_linux and litebox_shim_optee are the North options visible in the workspace members. litebox_platform_linux_kernel, litebox_platform_linux_userland, litebox_platform_windows_userland and litebox_platform_lvbs are the South options. The README's claim that the interfaces "allow for a wide variety of use-cases, easily allowing for connection between any of the North--South pairs" is the design goal; the runner crates are where specific pairs are actually assembled.

The runners are the entry points a user would touch: litebox_runner_linux_userland, litebox_runner_linux_on_windows_userland, litebox_runner_lvbs, litebox_runner_optee_on_linux_userland and litebox_runner_snp. One workspace detail is worth noting because it explains a build failure you would otherwise hit: the Cargo.toml comment states that litebox_runner_lvbs is excluded from default-members "because it requires a custom target and -Z build-std, which requires a nightly toolchain." Everything else builds with the default set. That is a concrete architectural constraint leaking into the build configuration, and it is the kind of thing you want to know before you start.

Two supporting crates round out the picture. litebox_syscall_rewriter and litebox_packager sit alongside the runners, and litebox_service_heki plus litebox_util_log and litebox_util_log_macros provide services and logging. The presence of a syscall rewriter is the strongest hint about how unmodified Linux binaries are handled: rather than only intercepting at the platform layer, there is tooling that rewrites the binary's syscalls before it runs.

## Building LiteBox from the workspace and running the Linux userland runner

LiteBox is a Cargo workspace, so the first step is the ordinary Rust one. The repository ships a rust-toolchain.toml, which means the pinned toolchain is selected automatically when you run Cargo inside the checkout. There are no published install instructions in the top-level README, so the workspace itself is the source of truth for how the project is built.

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

The default build compiles the default-members list from Cargo.toml. That list deliberately omits litebox_runner_lvbs, so a plain build succeeds without a nightly toolchain. If you want that runner you have to opt in explicitly, and the Cargo.toml comment explains why it needs a custom target and -Z build-std.

```bash
cargo build -p litebox_runner_lvbs
```

For a first real use, the Linux userland runner is the most direct entry point, because it does not require a second operating system or a confidential-computing host. Its crate is litebox_runner_linux_userland, and the workspace member name is the package name you pass to Cargo.

```bash
cargo run -p litebox_runner_linux_userland
```

What you should see depends on the runner's own crate documentation, which the top-level README does not reproduce. The README documents no command-line flags, no configuration file and no environment variables for any runner, so the argument it expects for the program to execute has to come from the crate directory itself. Treat the top-level README as an architecture document, not a usage guide.

## The stability warning is the main limitation, not a footnote

The README opens with a note that the project "is currently actively evolving and improving" and that "some APIs and interfaces may change as the design continues to mature." It then says plainly that if you need long-term stability, "it may be best to wait for a stable release, or be prepared to adapt to updates along the way." That is unusually direct for a project README, and it should be read as the primary adoption constraint rather than boilerplate.

The reason the warning carries weight here is the crate count. A workspace with roughly two dozen members, each a separate published interface between shims and platforms, has a large internal API surface. If the North interface changes, every shim and every runner that depends on it is affected at once. A project with a single crate can churn without breaking users; a project whose value proposition is a stable contract between two halves has more to keep aligned.

There is also a scope limitation baked into the description. LiteBox is a library OS, not a virtual machine and not a container runtime. It does not give you a full Linux kernel; it gives you a narrow interface and expects the guest to work through it. The README's example list is the honest boundary: Linux programs on Windows, Linux programs sandboxed on Linux, OP-TEE programs on Linux, SEV SNP, LVBS. If your workload needs a syscall or a device that no shim covers, the narrow interface that is the point of the project is exactly what blocks you. Nothing in the README describes a fallback path for unsupported syscalls, and the presence of litebox_syscall_rewriter suggests the answer is to rewrite the binary rather than to widen the interface.

## How LiteBox differs from gVisor and from plain containers

The closest well-known comparison is gVisor, which also interposes on a guest's system calls to shrink the host interface. The difference is where the boundary sits. gVisor implements a Linux-compatible kernel in user space and runs ordinary containers on top of it, so the guest is a normal OCI workload. LiteBox instead exposes a Rust interface inspired by nix and rustix, which means the North side is a Rust API rather than a Linux ABI. That makes LiteBox a better fit for code that can be compiled against it, and a worse fit for a container image you want to run untouched.

Containers themselves take the opposite approach. They share the host kernel and rely on namespaces, cgroups and seccomp to restrict what the process can reach. The host interface stays large; the filtering happens at the edges. LiteBox's argument is that a smaller interface is easier to reason about than a large one with filters, which is a defensible position and also a much heavier engineering commitment.

A third point of comparison is the confidential-computing angle. The README lists running on top of SEV SNP and on LVBS as use cases, with litebox_runner_snp and litebox_platform_lvbs as the corresponding crates. A container runtime does not target those environments directly; LiteBox treats them as just another South platform behind the same North interface. That is the clearest illustration of why the two-sided design exists: a new host environment means a new platform crate, not a new guest-facing API.

## Maintenance, licence and what a version bump costs you

The repository is not archived, and the last push was on 2026-09-24, which is recent. The README's own note that the project is "actively evolving and improving" is consistent with that. There are no retrieved releases, so there is no tagged version to pin against and no changelog to read before upgrading. In practice that means tracking the main branch, and the cost of an upgrade is the cost of whatever changed in the North interface times the number of crates you depend on.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. It contains no patent grant clause and no copyleft obligation, which is a difference from Apache-2.0 that matters to some legal reviewers. There is also a NOTICE.txt at the root, and the README carries a trademark section stating that use of Microsoft trademarks must follow Microsoft's Trademark & Brand Guidelines and that modified versions must not imply Microsoft sponsorship. If you fork and redistribute, that section is the one to read, not the MIT text.

One practical upgrade note from the workspace configuration: because litebox_runner_lvbs is excluded from default-members and needs a custom target with -Z build-std on nightly, it will not be exercised by a plain cargo build. If your deployment depends on it, your CI has to build it explicitly or you will not find out that it broke until you try.

## Conclusion

LiteBox fits engineers who need to run Linux or OP-TEE programs against a reduced host interface and are comfortable reading a Cargo workspace that is still changing, since the README states some APIs and interfaces may change before a stable release. It does not fit anyone who needs a frozen ABI, since the README itself suggests waiting for a stable release if long-term stability matters. Before adopting it, verify which North-South pair matches your target, and read the per-crate README in litebox_runner_linux_on_windows_userland, litebox_runner_linux_userland or litebox_runner_optee_on_linux_userland rather than the top-level file, which documents none of the runners.

## FAQ

### What is LiteBox from Microsoft?

It is a security-focused library OS written in Rust that the README describes as a sandboxing library OS which drastically cuts down the interface to the host to reduce attack surface. It is designed for both kernel and non-kernel scenarios and exposes a nix/rustix-inspired North interface over a South Platform interface.

### How is LiteBox different from C Lite?

The README does not describe a project called C Lite, so no comparison can be made from it. What the repository does show is that LiteBox is a Rust Cargo workspace whose North interface is modeled on the nix and rustix crates.

### How do I build LiteBox?

Clone the repository and run cargo build inside the checkout; the pinned rust-toolchain.toml selects the toolchain automatically. A plain build compiles the default-members list from Cargo.toml, which excludes litebox_runner_lvbs because that crate needs a custom target and -Z build-std on a nightly toolchain.

### Which LiteBox runner should I start with?

The Linux userland runner, litebox_runner_linux_userland, is the one that does not require a second operating system or a confidential-computing host. The other runners target Linux on Windows userland, LVBS, OP-TEE on Linux userland and SEV SNP.

### Is the LiteBox API stable enough for production?

The README states that some APIs and interfaces may change as the design matures, and advises waiting for a stable release if you need long-term stability. There are no retrieved releases, so there is no tagged version to pin.

### What licence does LiteBox use?

The README states the MIT License, with the full text in the LICENSE file at the repository root. The README also has a trademark section requiring modified versions to avoid implying Microsoft sponsorship.

## Sources

- [Issues](https://github.com/microsoft/litebox/issues)
- [License: MIT](https://github.com/microsoft/litebox/blob/main/LICENSE)
- [microsoft/litebox on GitHub](https://github.com/microsoft/litebox)
- [README](https://github.com/microsoft/litebox/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-litebox