What is unkernel?
unkernel is the Linux kernel built as a single WebAssembly module with a real MMU, published in the pithings/unkernel repository; the README credits Pooya Parsa (pi0) as its author, with sponsorship from Vercel's open source program. The kernel, with its syscalls, scheduler, memory management, ext4 and TCP/IP stack, is compiled to wasm and runs as native code. Only user programs are emulated: unmodified aarch64 (arm64) Linux binaries, so Alpine and Debian packages run without being rebuilt.
The source is Linux 7.3.4 plus the project's patch series, with an arch/wasm port derived from linux-wasm that uses Sv39 page tables, so fork, mmap, copy-on-write and shared memory work as on hardware. User code runs on kwemu, an aarch64 CPU written in Zig and linked into the kernel. It walks the kernel's own page tables, returns to the kernel on each syscall without an emulated trap, and compiles hot code to wasm with a JIT. Task switches use JSPI (WebAssembly.Suspending), and paravirtual drivers connect the devices to the JavaScript host. The kernel README describes a wasm64 build that is lowered to the 32-bit-memory module every host runs.
unkernel ships as the page at unkernel.dev, as the npm package unkernel (kernel bundle, base system, TypeScript SDK and the unkernel command) and as GitHub releases with unkernel.wasm, the npm tarball and the Alpine and Debian images. A GitHub Actions workflow tags releases as v<version>-<YYMMDD>-<commit>, often several per day. The latest is v0.2.0-261119-040e142 of November 19, 2026, also the current npm version. Commits from that day add a Docker shim to the Debian image and a default user with passwordless sudo. The repository was created on November 12, 2026.
The repository is GPL-2.0-or-later (LICENSE) unless a file says otherwise. The JavaScript SDK and the page in js/ and web/ are MIT (LICENSE-MIT), the kernel patches are GPL-2.0-only, and the patches to LLVM's linker follow Apache-2.0 WITH LLVM-exception. The npm package is declared as MIT AND GPL-2.0-only because it ships the GPL-2.0 kernel and Alpine's static busybox next to the MIT SDK, and the distro images keep their packages' own licenses.
The README places unkernel next to whole-machine emulators such as v86 and JSLinux, POSIX runtimes for wasm such as WebContainers and Wasmer WASIX, and Linux ports without an MMU: in unkernel the kernel is native wasm, while user space is unmodified, emulated aarch64. Its known limits include no IPv6, no inbound network connections, no seccomp and no ptrace register sets, so strace and gdb do not work. Related listings on iThub include windows95, an Electron app that runs Windows 95 on the v86 emulator, and crate, which runs Linux desktops in virtual machines on iPhone and iPad.
Key capabilities
- Linux in a browser tab Opening unkernel.dev boots a shell after a download the README puts at about 10 MB; distro images are read lazily with HTTP range requests. The page's configuration boots Debian by default, with
?distro=alpineor?distro=none(the busybox base shell) as alternatives. Ctrl-A n opens up to 9 terminal windows, and the status icon opens options, diagnostics, and export or reset of the disk. - Browser requirements The kernel needs JSPI. The README lists Chrome and Edge 137 or newer on desktop and Android, Firefox 153 or newer, and Safari 27 or newer on macOS plus any browser on iOS and iPadOS 27; other browsers get a message naming what is missing. The default kernel is the 32-bit-memory build, so memory64 is only needed for the wasm64 reference kernel. Guest memory defaults to 512 MiB, 256 MiB on phones and less on low-memory devices, and
?mem=overrides it. - Cross-origin isolation and Web Workers Unkernel.dev is served with
Cross-Origin-Opener-Policy: same-originandCross-Origin-Embedder-Policy: require-corp, which gives the page SharedArrayBuffer. Where the page is cross-origin isolated (https or localhost), the kernel runs in a Web Worker by default and console input and frames go through shared memory; a plain-http page on a LAN falls back to messages, and?worker=0keeps the kernel on the page's thread. - Several CPUs With
?cpus=, the page boots an SMP kernel on 2 to 16 CPUs, each in its own Web Worker. The default is half the device's threads, at most 4 on desktops and 2 in Firefox, and one CPU on phones, in Safari and on iOS. The SDK and CLI boot one CPU unless told otherwise, and an SMP guest cannot be suspended. - Persistent disk in IndexedDB The root file system is an overlay: a read-only distro image under the user's changes, which go to an ext4 data disk labelled
kwdataand stored in IndexedDB. According to the browser disk code, every flush is one IndexedDB transaction with strict durability. Only one tab at a time gets the saved disk,?data=0starts a fresh system every time, and a safe mode (?root=initramfs) boots the plain image to recover a broken system. - Internet access through a Wisp proxy Browsers cannot open raw TCP sockets, so the page carries the guest's TCP connections over one WebSocket to a Wisp server. The default is the project's own server at
wss://wisp.pi0.io:6680/, which accepts only known origins;?wisp=sets other servers and?net=0boots without a network. Wisp has no DNS, so the server resolves host names, and the SDK source notes that a third-party Wisp server sees the host names and ports the guest connects to and plain-HTTP content, while the guest's TLS stays end to end. - Package managers and runtimes On Alpine 3.24,
apk addinstalls from Alpine's regular mirrors; apk starts with only themainrepository and addscommunitywhen a command first needs it, and typing a command that is not installed, such ashtop, installs its package. Debian 13 boots the same way with apt. The README lists Node and npm, Python, OpenSSL, curl and wget from the distributions, and systemd booting Ubuntu 26.10 tomulti-user.target. - Screen, input and sound The guest gets a framebuffer (
/dev/fb0, 640x480 on the page), evdev keyboard, mouse and touch, and sound through ALSA (hw:0,0) and/dev/dsp, played with Web Audio. The page shows a canvas over the terminal while a program has the framebuffer open.glimmer, a small game with sound, exercises all three. - Demo launcher Ctrl-Shift-O opens a launcher of demos, among them tmux, htop, Midnight Commander, Neovim, Git, nginx, Node.js, Bun, Python, Go, Rust, PostgreSQL, SQLite and Valkey. Others install software on first use, such as Docker's hello-world container on Debian and the Claude Code and fx coding agents; the Ubuntu demo fetches Ubuntu Base 26.10 from cdimage.ubuntu.com into a chroot, and the Doom demo builds fbDOOM with Freedoom in the guest.
- Command-line tool
npx unkernel(Node.js 24 or newer) boots Alpine with networking over the host's sockets; Ctrl-] quits. The first run downloads the Alpine image (about 4 MB) from the GitHub release matching the package version into~/.cache/unkernel. Flags include--distro debian(about 57 MB, downloaded once),--datafor a persistent disk image,--display --sound,--mem,--no-net,--mount .:/workand--forward 8000:80. - Scripted runs and exit codes
--timeoutand--inputtype input on a schedule and stop the guest after a set time. The exit code reports how the guest ended: 0 power off, 1 halt or boot failure, 2 restart, 124 timeout, 253 kernel panic, 254 wasm trap and 255 fatal error, according to the CLI documentation. - JavaScript SDK
npm install unkerneladds a zero-dependency TypeScript SDK that runs the same kernel file in Node and in every supported browser.createKernel()boots a guest,fetchDistro("alpine")or"debian"downloads an image on Node and checks its size and SHA-256 against the release'sdistros.json, and in browsers the image is hosted by the application and passed as a URL. Importingunkernelpicks the Node or browser entry, andunkernel/nodeorunkernel/webselects one. - Programs, terminals and pipes
vm.exec()runs a program and resolves withstdout,stderr,exitCodeandsignal.vm.spawn()starts a program on its own pty, or on pipes withpty: false. On the distro images programs run asuser(uid 1000) with passwordless sudo, anduser: "root"switches. - Disks and networking in the SDK
openDisk()attaches local ext4 images on Node, http(s) images are read by range,openHttpDisk()keeps writes in IndexedDB andopenDataDisk()returns the page's persistent disk; anyBlockDeviceworks, including as the root. Networking is off unlessnetis passed:directBackend()uses host sockets on Node,wispBackend()a Wisp proxy anywhere, and any object withconnectandlookupmethods can act as a backend. - Host files, vsock and shared memory Mounts are served over 9p on vsock from a plain object tree, a
MemoryFsornodeFs(dir)on Node; guest writes reach the host as they happen, and host changes show in the guest within a second.vm.vsockgives byte streams with flow control,vm.connect(port)andvm.fetch(url)reach TCP and HTTP servers on the guest's loopback without a network, andshm: trueexposes/dev/shmfiles to the host with zero-copy views. - Build from source The build with setup.sh needs Linux on x86-64 or arm64, Zig 0.16, Node 24 and clang 21 or newer with the wasm target. The script checks the toolchain and builds everything; the README gives about 12 minutes and 5 GiB of disk for the first build, most of it for a patched
wasm-ld.pnpm devthen serves the page onlocalhost:8080. - Published benchmarks The project's benchmarks, measured under Node, give
getppidat 172 ns (110 ns native, 1,662 ns under qemu-system) and fork, exit and wait at 57 µs (73 µs native) on November 14, 2026, measured with the riscv64 user space the project started with. On November 18, 2026 the JIT made a shell loop 1.6 times andsort2.3 times as fast as the interpreter alone, and the README notes that CPU-heavy programs remain well behind native.
Where unkernel fits
Opening a Linux shell in a browser tab
The unkernel.dev page boots a Debian shell on desktop and mobile browsers with JSPI, and keeps changes in IndexedDB across reloads. Settings come from the Options panel or URL parameters such as ?mem=, ?distro=, ?cpus=, ?jit=0 and ?data=0, and the status panel exports, imports or resets the data disk. Guest software reaches the internet through the Wisp proxy, by default the project's server, and the README notes that a page hosted elsewhere has to point ?wisp= at its own proxy.
Running a guest from a terminal and in scripts
npx unkernel starts Alpine on Node.js 24 or newer with networking over host sockets, and --distro debian switches to Debian 13. --mount .:/work exposes the current directory in the guest (:ro for read-only), --forward 8000:80 maps a host port to a guest port over vsock, and --data my-data.img keeps changes on a disk image. For automated runs, the README's example combines --timeout 60 with --input that waits, types uname -a and powers off, and the exit code distinguishes power off, timeout, kernel panic and wasm trap.
Embedding Linux in a web or Node.js application
The JavaScript SDK boots a guest with createKernel(), writes to its console and waits on vm.exited. Applications run commands with vm.exec(), open interactive shells with vm.spawn(), mount host data with mounts or vm.mount(), and attach disks and a network backend explicitly; nothing in the SDK downloads anything except fetchDistro() on Node. In browsers the application hosts the distro image and the kernel file itself, and the README states that the MIT-licensed SDK has no closed engine or license key behind it.
Reaching servers that run in the guest
Because the guest accepts no inbound network connections, the project routes host access over vsock. vm.connect(port) opens a TCP stream to the guest's loopback, vm.fetch("http://localhost:8000/") sends an HTTP/1.1 request to a dev server in the guest and streams the response, and the CLI's --forward uses the same path. On the page, the nginx demo shows a guest web server in a preview that a service worker answers under /vm/<id>/<port>/, and open or xdg-open in the guest opens a URL there or in a new tab after a confirmation.
Writing graphics and sound programs
Guest programs draw on /dev/fb0, read evdev input and play audio through ALSA or /dev/dsp, as glimmer and the Doom demo do on the page. In the SDK, the display option creates the framebuffer, vm.frame() returns RGBA frames for a canvas, domCodeToLinux() maps browser key codes to evdev keys, and the sound option delivers PCM chunks that pcmToFloat32() converts for Web Audio.
Hosting the page and the network proxy
The page in web/ is MIT-licensed and builds with the repository: pnpm install && pnpm dev serves it on localhost:8080, and the build output runs as a Node server (node .output/server/index.mjs) or on Vercel. Its route rules set the COOP and COEP headers that SharedArrayBuffer, the Web Worker mode and SMP need. Since the default Wisp server accepts only known origins, a separately hosted page uses ?wisp= or the Options panel to name its own Wisp servers, or ?net=0 for no network.
Install
npx unkernelReviews of unkernel
Be the first to share your experience with unkernel.
Write a review
Loading review form…
Found unkernel useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.







