A real Linux kernel, compiled to WebAssembly. It boots to a shell in less than a second.
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, with a JIT: unmodified riscv64 Linux binaries, so Alpine and Ubuntu 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.
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 afternodelaunches. 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). - fork at native speed: fork + exit + wait takes about 60 Β΅s, against about 70 Β΅s natively and 1.2 ms under qemu-system.
- A JIT for user code: hot riscv64 code is compiled to wasm while it runs. A tight loop takes 2.5 ns per iteration (1.8 native, 28 without the JIT), and https downloads in the guest reach 30 MB/s.
CPU-heavy programs are still well behind native. Benchmarks has the full numbers.
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. In the browser the root file system is an overlay on 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 24.04 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. - riscv64 user space: RV64GC plus Zba, Zbb, Zbs, Zbc, Zbkb, Zbkc, Zbkx, Zkne, Zknd, Zicond and the scalar rest of RVA23U64, so distribution binaries and OpenSSL's AES and carry-less multiply paths run unchanged. riscv64 is a modern 64-bit architecture with official ports in Alpine, Debian and Ubuntu, 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. apk starts 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, curl and
wget, straight from the distribution. Ubuntu 24.04 boots from a disk, with apt and, once you install it, systemd. - 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=1 |
Run the kernel in a Web Worker (experimental) |
?smp=2 |
Boot on several CPUs, each in a Web Worker (experimental; only where the page has the SMP kernel and is cross-origin isolated) |
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 |
npx unkernelThis boots Alpine from RAM, with networking over your host's sockets. Press Ctrl-] to quit.
npx unkernel --disk alpine.ext4 # boot from an ext4 image, changes persist
npx unkernel --data my-data.img # a persistent /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 elseExit 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().
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
forkand 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 riscv64, with a JIT | real Sv39 page tables |
The kernel is compiled straight to WebAssembly. User programs run on kwemu, a riscv64 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.
Hot user code goes through a second tier: a JIT that compiles riscv64 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).
The design helps most with syscalls. These were measured under Node:
In this test fork is faster than native. Pure computation is slower. The JIT
runs a tight integer loop at about 3900 MIPS (about 270 interpreted), and
real Alpine work (sort, gzip, sha256sum, awk) runs 1.7 to 4.6 times
faster than without it, which is still well behind native.
- One CPU in the released kernel. Several CPUs (SMP) are experimental, not in a release yet, and cannot be suspended.
- 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. - The JIT leaves atomics and system instructions to the interpreter.
- A wasm trap in the kernel ends the session.
npm install unkernelimport { createKernel } from "unkernel";
const vm = await createKernel(); // bundled Alpine, no network
vm.onOutput((bytes) => process.stdout.write(bytes));
vm.write("uname -a; poweroff\n");
const { code, kind } = await vm.exited; // 0, "halt"The same code runs in the browser. Importing unkernel picks the Node or
browser entry automatically, and unkernel/node or unkernel/web selects
one explicitly. The kernel ships in the package and loads from next to the
entry, streamed and compiled while it downloads.
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 proxyNetworking 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 { createKernel, openDisk } from "unkernel/node";
const vm = await createKernel({
disks: [await openDisk("alpine.ext4")], // or an https:// URL
cmdline: "root=/dev/wda rw",
});In the browser, openHttpDisk(url) keeps your writes in IndexedDB and
openDataDisk() gives you the persistent data disk that
the page uses. Anything that
implements BlockDevice works too.
// vm.output: a ReadableStream, everything since boot and then live
vm.output.pipeTo(new WritableStream({ write: (b) => process.stdout.write(b) }));
vm.write("ls /\n"); // or write to vm.input, a WritableStream
vm.resize(120, 40); // the foreground program gets SIGWINCH
await vm.sync(); // flush the guest's disks
console.log(vm.stats()); // memory, disk, network and JIT counters
const { code, reason, kind } = await vm.exited; // stop() parks it at onceconst { stdout, exitCode } = await vm.exec("uname", ["-a"]);
const { stdout: sum } = await vm.exec("sha256sum", [], { input: "hello" });exec() runs a program on pipes and resolves with { stdout, stderr, exitCode, signal }, also for a non-zero exit. Pass encoding: "buffer"
for bytes, and cwd or env as you would to child_process.
const sh = await vm.spawn(); // a login shell on its own pty
sh.output.pipeTo(new WritableStream({ write: (b) => process.stdout.write(b) }));
await sh.write("cat /etc/alpine-release; exit\n");
console.log(await sh.ended); // { type: "exit", code: 0 }spawn(file, args, { cols, rows }) runs a program on a pty, in the
zigpty / node-pty shape, with resize(), kill(signal) and close() (a
hangup). Run as many as you like. Keep reading output: the guest program
waits while nobody does.
const gz = await vm.spawn("gzip", ["-c"], { pty: false });
gz.stderr.cancel(); // read both outputs, or cancel one
const zipped = new Response(gz.stdout).bytes();
await new Response("hello\n").body.pipeTo(gz.stdin); // then EOF
console.log((await zipped).length);With pty: false the program gets pipes: stdin, stdout and stderr
web streams, byte for byte.
import { createKernel, MemoryFs, nodeFs } from "unkernel";
const mem = new MemoryFs();
mem.onChange((c) => console.log(c.type, c.path)); // what the guest changed
const vm = await createKernel({
mounts: {
"/mnt/host": { "hello.txt": "hi", dir: { "a.bin": bytes }, "now.txt": () => Date() },
"/mnt/mem": mem,
},
});
await vm.exec("cp", ["/etc/os-release", "/mnt/mem/"]);
console.log(mem.readText("/os-release"));
const work = await vm.mount("/work", nodeFs("."), { readOnly: true }); // Node only
await work.unmount();A file system is a plain object tree (a function is a computed file,
evaluated once per open), a MemoryFs you read and write from the host,
nodeFs(dir), or your own Fs: getattr, readdir and open by path,
sync or async, plus whichever change methods you want. Mounts are served
over 9p on vsock. Each guest write reaches the host as it happens, and a
host change shows in the guest within a second.
const listener = vm.vsock.listen(5000); // guest programs connect to CID 2, port 5000
vm.write("echo hello | kwvsock connect 5000\n");
const conn = await listener.accept();
console.log(await new Response(conn.readable).text()); // "hello\n"
conn.close();
const c = await vm.vsock.connect(6000); // a guest program listening on port 6000
await c.writable.getWriter().write("ping");These are byte streams with real flow control and no network in between.
vsock is on unless you pass vsock: false.
const sock = await vm.connect(8000); // TCP to the guest's 127.0.0.1:8000
await new Response("hello\n").body.pipeTo(sock.writable); // then EOF (a half-close)
console.log(await new Response(sock.readable).text());vm.connect(port) reaches a TCP server on the guest's loopback through
the guest's kwtty, over vsock, so it needs no network. It resolves once
the guest has connected (PtyError ECONNREFUSED if nothing listens) with
readable and writable byte streams, half-close included, close() and
closed. The CLI's --forward HOSTPORT:GUESTPORT uses it.
vm.fetch(url, init) sends an HTTP/1.1 request to a server in the guest
and returns a Response whose body streams. It always connects to the
guest's 127.0.0.1 at the URL's port; the host name only goes into the
Host header, so vm.fetch("http://localhost:8000/") reaches a dev server
listening on port 8000. fetchOver(connect, url, init) is the same client
over any byte stream.
const vm = await createKernel({ shm: true });
await vm.exec("sh", ["-c", "printf result > /dev/shm/output"]);
const output = await vm.shm.open("output"); // a file a guest program made
const data = await output.read();
const views = output.views(); // zero-copy, until the kernel runs again
const input = await vm.shm.create("input", 1 << 20); // /dev/shm/input in the guest
await input.write(0, bytes);/dev/shm exists once the guest's init has mounted it, so wait for the
guest before create() (an exec() waits for it). openId(id) opens a
memfd that a guest program exported through /dev/kwshm. views()
exists only when the kernel runs inline.
import { createKernel, domCodeToLinux, pcmToFloat32 } from "unkernel";
const vm = await createKernel({
display: { width: 800, height: 600 }, // the guest gets /dev/fb0
onDisplay: (mode) => console.log(mode), // a program opened it (its mode) or closed it (null)
sound: { onChunk: ({ data, format }) => play(pcmToFloat32(data, format)) },
});
const frame = vm.frame(); // RGBA, or null while nothing draws
if (frame) ctx.putImageData(new ImageData(frame.data, frame.width, frame.height), 0, 0);
addEventListener("keydown", (e) => {
const key = domCodeToLinux(e.code);
if (key && vm.evdev.keyboardOpen) vm.evdev.key(key, true);
});evdev also has button(), move(), moveTo() and wheel() for a
mouse or tablet. onInput tells you when a program opens the keyboard
and mouse; until then, send keys to the console. readFrame() waits for
a fresh frame.
const vm = await createKernel({
worker: true,
net: { kind: "net", backend: { kind: "direct" } },
disks: [{ kind: "file", path: "alpine.ext4" }],
});The kernel runs in a worker thread or Web Worker, with the same API. Disks
and the network are given as specs, which the worker builds: { kind: "file", path } on Node, { kind: "http", url } and { kind: "data", template: "bundled" } in browsers. Input and frames go through shared
memory when it is available (vm.transport says). This mode is
experimental.
An SMP kernel (a bundle with the SMP patch) boots on several CPUs with
cpus: 4, each CPU in a thread of its own on one shared memory. In
browsers that needs a cross-origin isolated page and worker: true,
because a CPU blocks while it waits for another, which a page's main
thread may not; webCpuBlocker() says why it cannot, and
vm.stats().cpus how many CPUs the kernel got.
import { checkSupport, ConsoleRouter, createKernel } from "unkernel";
const support = await checkSupport(); // JSPI and the rest, before you boot
if (!support.ok) throw new Error(support.problems.join("\n"));
const vm = await createKernel({
kernel: "./my-kernel.wasm", // a URL, bytes, a Response or a WebAssembly.Module
initrd: "./initramfs.cpio.gz", // null: none
cmdline: "console=hvc0 rdinit=/init",
memoryMiB: 1024,
jit: false, // interpreter only
onProgress: (p) => console.log(p.stage),
});
const router = new ConsoleRouter({ // kernel log lines apart from program output
onKernelLine: (line, { important }) => important && console.warn(line),
onUserOutput: (text) => process.stdout.write(text),
});
vm.onOutput((bytes) => router.write(bytes));The SDK has some limits, on top of the kernel's known
limits. There is no guest agent beyond terminal sessions, so
you drive the guest through a terminal or its console, or over vsock with your
own program. stop() doesn't shut the guest down cleanly, so prefer
poweroff. Only one kernel can run per thread. Types ship as .d.mts and use
the DOM's WebAssembly types, so a Node-only TypeScript project needs "lib": ["dom"] or skipLibCheck.
You need Linux (x86-64 or arm64), Zig 0.16, Node 24, clang 21+ with the
wasm target, and the usual build tools. ./setup.sh --check lists what's
missing. The first build takes about 12 minutes, most of it spent on a
patched wasm-ld, and uses 5 GiB of disk.
./setup.sh # check, then build everything
node js/cli.ts # boot your build
pnpm install && pnpm dev # the web page at http://localhost:8080
zig build test # emulator testskernel/README.md covers the kernel, its devices and the guest image. AGENTS.md and .agents/ hold the contributor notes: invariants, workflows, which tests to run, and the roadmap.
Made with β₯ by Pooya Parsa (pi0), sponsored by β² Vercel.
Thanks to:
- Kernarium, for the idea: a native kernel with emulated user space behind a software MMU.
- linux-wasm by Joel Severin,
for the
arch/wasmport this kernel grew from, the wasm-ld linker-script patches and the Kbuild toolchain wrapper. - iSH and v86, for showing how to build a fast user-mode emulator and a wasm JIT.
- Alpine Linux, wterm, Binaryen and fx (the page's coding agent, libfx, Apache-2.0).
Everything is open source: the kernel patches, the emulator and its JIT,
the patched linker, the SDK and the page. ./setup.sh rebuilds the kernel
file from source.
The project is GPL-2.0-or-later (LICENSE) unless a file says
otherwise. The JavaScript SDK and page (js/, web/, SDK tests) are MIT
(LICENSE-MIT), so you can embed them anywhere.
The npm package ships a Linux kernel (GPL-2.0) with an Alpine userland whose
packages keep their own licenses, so it is MIT AND GPL-2.0-only. The
kernel's source is Linux 7.3.4 plus
kernel/patches/linux (arch/wasm is based on
linux-wasm's). Those patches and
kernel/tools/fake-llvm are GPL-2.0-only, and the patches in
kernel/patches/llvm follow LLVM's license (Apache-2.0 WITH
LLVM-exception).