A real Linux kernel, compiled to WebAssembly
Try it ยท Performance ยท Features ยท CLI ยท How it works ยท Benchmarks ยท JavaScript SDK
unkernel is Linux 7.x built as a single wasm module with a real MMU. The kernel (syscalls, scheduler, memory management, ext4, TCP/IP) is compiled code, not emulated, so programs get Linux's own behavior down to the edge cases.
Only user programs are emulated: unmodified aarch64 (arm64) Linux binaries, so Alpine and Debian packages run as they are.
Open a page and you have a Linux machine with a shell, a package manager, a persistent disk, internet access, and a screen with sound. It runs entirely on your device, with nothing to install and no server, and every layer is open source. How it works explains the design.
Performance
Much of what makes a system feel slow lives in the kernel: starting processes, syscalls, page faults, file and network I/O. In unkernel that path runs at wasm speed.
- Boot: the kernel reaches
/initabout 70 ms after it starts, and the Alpine prompt appears 0.3 s after node launches. The page downloads about 10 MB, and Alpine boots in 48 MiB of guest memory. - Syscalls at close to native cost:
getppidtakes about 170 ns (110 native, 1.7 ยตs under qemu-system), a 64-bytereadabout 170 ns (160 native). forkat native speed:fork+exit+waittakes about 60 ยตs, against about 70 ยตs natively and 1.2 ms under qemu-system.- A JIT for user code: hot aarch64 code, including the AES, PMULL and SHA instructions OpenSSL uses, is compiled to wasm while it runs. With it a shell loop runs 1.6 times and
sort2.3 times as fast as on the interpreter alone, and OpenSSL in the guest does AES-128-GCM at about 100 MB/s and SHA-256 at about 160 MB/s.
The syscall and fork numbers were measured on 2026-11-14 (with the riscv64 user space the project started with; the path through the kernel is the same), the JIT numbers on 2026-11-18. CPU-heavy programs are well behind native: apk search over the main index takes about 0.8 s, apk add python3 about 3.4 s. Benchmarks has the full numbers.
Features
Anything a program relies on, from /proc and epoll to cgroups and overlayfs, behaves as it does on a server, because it runs the same code.
A real MMU (
arch/wasmwith Sv39 page tables):fork,mmap, copy-on-write, shared memory, threads and signals behave as they do on hardware. This is not a NOMMU port where programs are limited tovfork.Linux's own file systems: ext4, overlayfs, tmpfs, loop devices, FUSE, and 9p, which mounts file systems your program serves from the host. The root file system is an overlay: a read-only distro image under your changes, which go to a persistent ext4 disk, so everything you change survives a reload, and a safe mode recovers a system you broke.
Linux's own TCP/IP stack, with DHCP and DNS, reaching the internet through your host's sockets or a Wisp proxy (Add a network).
cgroups, namespaces, userfaultfd, fanotify and TUN: enough for systemd to boot Ubuntu 26.10 to
multi-user.target.Devices: a framebuffer (
/dev/fb0), evdev keyboard, mouse and touch, sound through ALSA and/dev/dsp,AF_VSOCK, and shared memory with the host.aarch64 user space: ARMv8.0-A with FP and AdvSIMD plus the AES, PMULL, SHA1, SHA2, SHA512, SHA3, CRC32 and LSE atomics extensions, so distribution binaries and OpenSSL's hardware AES, GHASH and SHA paths run unchanged. aarch64 is a first-class port of every distribution, so their full, current package archives are available. Known limits lists what is still missing.
Carry a Linux shell anywhere. Alpine Linux 3.24 runs in Chrome, Edge, Firefox and Safari, including on phones. Install anything with
apk addfrom Alpine's regular mirrors. Type a command that isn't installed, such ashtop, and its package is installed for you.apkstarts with only themainrepository, because it is about 4x faster that way;communityis added the first time a command needs it.Run real runtimes and tools: Node and npm, Python, OpenSSL,
curlandwget, straight from the distribution. Debian 13 boots the same way as Alpine (--distro debian), withapt.Write graphics and sound programs against
/dev/fb0, evdev and ALSA. Tryglimmer, a tiny game with sound.Embed Linux in your app with a zero-dependency TypeScript SDK, published as
unkernel. The same kernel file runs in Node and in every supported browser, optionally in a worker. Disks can be local ext4 images, http(s) images fetched by range, or a persistent disk in IndexedDB. The SDK is MIT-licensed, and there is no closed engine or license key behind it, so you can ship it in your product and host it wherever you like.Talk to the guest through terminal sessions, each with its own pty and shell, host directories and in-memory file systems mounted in the guest, vsock byte streams and zero-copy shared memory, with no network in between.
Script and test: the CLI types input on a schedule, stops on a timeout, and reports how the guest ended in its exit code.
Open unkernel.dev. A shell appears after a download of about 10 MB. Your changes are saved in the browser, and the status icon opens options, diagnostics, and export or reset for your disk.
Ctrl-A n (or โA n on a Mac) or + on the status line opens another terminal window with its own shell, up to 9; Ctrl-A and a digit switches.
The page takes a few URL parameters:
| Parameter | Does |
|---|---|
?mem=512 |
Guest memory in MiB |
?append=... |
Extra kernel command line |
?net=0 |
Boot without a network |
?wisp=wss://... |
Use your own Wisp proxy |
?jit=0 |
Interpreter only |
?data=0 |
No persistent disk, a fresh system every time |
?worker=0 |
Run the kernel on the page's thread (default: in a Web Worker where the page is cross-origin isolated) |
?cpus=2 |
Boot on that many CPUs, each in a Web Worker (default: half the device's threads, up to 4 on desktops and 2 in Firefox, one on phones, in Safari and on iOS, where the page has the SMP kernel and is cross-origin isolated; ?cpus=1 : one CPU) |
Browsers can't open raw TCP sockets, so the page reaches the internet through a Wisp proxy. The default one accepts only known origins, so if you host the page somewhere else, point ?wisp= at your own proxy.
| Browser | Status |
|---|---|
| Chrome / Edge 137+ (desktop and Android) | โ works |
| Firefox 153+ | โ works |
| Safari 27+ on macOS, any browser on iOS/iPadOS 27 | โ works |
| Anything without JSPI | the page tells you what's missing |
CLI
npx unkernel
This boots Alpine, with networking over your host's sockets. Press Ctrl-] to quit. The package holds the kernel and a small base system; the first run downloads the Alpine image (about 4 MB) from the GitHub release of your version and keeps it in ~/.cache/unkernel.
npx unkernel --distro debian # Debian 13 instead (about 57 MB, downloaded once)
npx unkernel --distro none # no distro: the base shell (busybox)
npx unkernel --data my-data.img # changes persist on a /data disk, created on first use
npx unkernel --display --sound # a framebuffer and a sound card
npx unkernel --mem 1024 --no-net # more memory, no network
npx unkernel --mount .:/work # this directory at /work in the guest (:ro for read-only)
npx unkernel --forward 8000:80 # host 127.0.0.1:8000 to port 80 in the guest
npx unkernel --timeout 60 --input '{8}uname -a\n{2}poweroff\n' # scripted: wait, type, wait, type
npx unkernel --help # everything else
Without --data, changes to the root file system are kept in memory and gone at exit; with it, each distro keeps its own in /data/distros//. --distro also takes an image file or an http(s) URL, and UNKERNEL_CACHE_DIR moves the download cache.
Exit codes: 0 power off, 1 halt or boot failure, 2 restart, 124 timeout, 253 kernel panic, 254 wasm trap, 255 fatal error.
The CLI is built on the JavaScript SDK: --mount uses its host mounts and --forward its vm.connect().
How it works
Most "Linux in the browser" projects take one of three approaches:
- Emulate a whole PC, kernel included. This is faithful but slow, because every syscall and page fault goes through emulated hardware.
- Emulate the CPU and reimplement the syscalls. Programs run on an emulated CPU, often with a JIT, and a runtime answers their syscalls, with no Linux kernel at all. This is fast, but it covers only as much of Linux as the runtime implements.
- Compile programs to wasm, and run them on a kernel without an MMU or on a runtime that provides POSIX calls. This is fast, but native programs have to be rebuilt, and fork and anything else that needs an MMU breaks or is approximated.
unkernel keeps the best of each: the real Linux kernel, running at native wasm speed, under unmodified binaries with a real MMU.
| Approach | Kernel | User space | MMU |
|---|---|---|---|
| Whole-machine emulators (v86, JSLinux, container2wasm, QEMU's wasm build) | Linux, emulated | unmodified, emulated | emulated |
| Syscall emulators | none: a runtime reimplements the syscalls | unmodified, emulated | the runtime's own |
| POSIX runtimes for wasm (Wasmer WASIX, WebContainers, BrowserPod) | none: a runtime provides the syscalls | rebuilt for wasm, or JavaScript | none |
| Linux without an MMU (linux-wasm, tombl/linux, WasmLinux (LKL)) | Linux, native wasm | rebuilt for wasm | none |
| unkernel | Linux, native wasm | unmodified aarch64, emulated | real page tables |
The kernel is compiled straight to WebAssembly. User programs run on kwemu, an aarch64 CPU written in Zig and linked into the kernel. kwemu walks the kernel's own page tables, so memory management is done by the real Linux code. When a program makes a syscall, kwemu returns to the kernel, which handles it as native wasm. There is no emulated trap and no emulated kernel mode in between.
Task switches use JSPI (WebAssembly.Suspending), so the kernel gets real stacks that it can suspend and resume. kwemu runs blocks of guest code decoded once into compact ops (what has no op runs through a reference interpreter), and hot user code goes through a second tier: a JIT that compiles those blocks to wasm modules at run time, with output that matches the interpreter bit for bit. Benchmarks shows what each tier costs.
Devices are small paravirtual drivers that talk to the JavaScript host: block (kwblk), network (kwnet, with a user-mode TCP/IP stack in JS), display, input and sound (kwfb, kwinput, kwsnd), vsock (kwvsock) and shared memory (kwshm).
Benchmarks
The design helps most with syscalls. These were measured under Node: In this test (2026-11-14) fork is faster than native. Pure computation is slower. kwemu's decoded-op interpreter runs integer code at about 250-300 million guest instructions per second under Node (2026-11-17), and the JIT makes real Alpine work 1.6 to 2.3 times as fast as that (2026-11-18: an ash loop 2.5 s against 4.0 s, seq 100000 | sort -r 3.1 s against 7.1 s, seq 250000 | gzip | gunzip 3.5 s against 6.5 s), which is still well behind native.
- The SDK and CLI boot one CPU by default; the page boots several where it can (
?cpus=). A snapshot of several CPUs (SMP), and so a session suspended on the page, resumes only on as many. - No IPv6, no UDP beyond DHCP and DNS, no inbound network connections (
vm.connect(),vm.fetch()and--forwardreach guest servers over vsock instead). - No ptrace register sets, so
straceandgdbdon't work. No seccomp. - Code that runs only a few times (a large program's startup, such as
npm's) stays on the interpreter, and FP and AdvSIMD floating point run through it even inside compiled code. Without wasm SIMD in the host engine, OpenSSL's AES and SHA paths run on the interpreter too. - A wasm trap in the kernel ends the session.
JavaScript SDK
npm install unkernel
import { createKernel, fetchDistro } from "unkernel";
const vm = await createKernel({ distro: await fetchDistro("alpine") }); // Alpine, no network
vm.onOutput((bytes) => process.stdout.write(bytes));
vm.write("uname -a; poweroff\n");
const { code, kind } = await vm.exited; // 0, "halt"
Importing unkernel picks the Node or browser entry automatically, and unkernel/node or unkernel/web selects one explicitly. The kernel ships in the package (unkernel/unkernel.wasm) and loads from next to the entry, streamed and compiled while it downloads. It carries a small base system that mounts a distro image read-only under an overlay root and runs its init; createKernel() without distro boots the base shell (busybox and unkernel's tools), which needs no download.
The distro images are not in the package. On Node, fetchDistro("alpine") (or "debian") downloads one once from the GitHub release of the package's version, checks it against the release's distros.json (size and SHA-256), keeps it in ~/.cache/unkernel (UNKERNEL_CACHE_DIR) and returns its path; nothing else in the SDK downloads anything. In the browser, host the image yourself (it is read lazily with range requests) and pass its URL:
const vm = await createKernel({ distro: "/distros/alpine.erofs" });
Changes to the root file system stay in memory, unless a persistent data disk (labelled kwdata) is attached: then each distro keeps them in /data/distros// on it.
import { createKernel, directBackend, wispBackend, DEFAULT_WISP_SERVERS } from "unkernel";
await createKernel({ net: directBackend() }); // Node: host sockets
await createKernel({ net: wispBackend(DEFAULT_WISP_SERVERS) }); // anywhere: a Wisp proxy
Networking is off unless you pass net. Any object with connect and lookup methods can carry the guest's TCP and DNS, so you can write your own backend.
import { createImageFromKwsparse, createKernel, bundledBoot, openDisk } from "unkernel/node";
const vm = await createKernel({ distro, disks: [await openDisk("data.img")], // the data disk, or any ext4 image or https:// URL
});
createImageFromKwsparse(file, template) makes a new data disk from the template the kernel carries (bundledBoot(module).datadisk). In the browser, openHttpDisk(url) keeps your writes in IndexedDB and openDataDisk() gives you the persistent data disk that the page uses.
Anything that impleme
Comments
No comments yet. Start the discussion.