Mewz: a unikernel built to run one WebAssembly application

What a unikernel changes about the deployment

Mewz is described as a unikernel designed specifically for running Wasm applications and compatible with WASI. The README's own framing of why it exists is the clearest statement of the design. There are now various Wasm runtimes, but they operate on general-purpose operating systems such as Linux or Windows. Mewz is instead a specialized kernel designed for running Wasm, and it runs a single Wasm application within the kernel by linking it together during the build process with the Wasm application. A kernel composed in this manner is commonly referred to as a unikernel, and the effect is that Mewz provides the minimal required features and environment for executing Wasm. The primary language is Zig, the licence is GPL-3.0, the default branch is main, and the recent release tags are v0.1.3 from 2025-07-31, v0.1.2 from 2024-12-20 and v0.1.1 from 2024-02-05.

The build pipeline: Wasker first, then Zig, then QEMU

The toolchain has three stages and understanding them explains the repository layout. The first stage is Wasker, a separate project from the same organisation, which compiles a Wasm file into a native object file. The second stage is the Zig build, which links that object file into the kernel and produces a runnable image. The third stage is QEMU, which is what actually boots the result. The examples directory holds programs to try, with entries for hello_world, hello_server, http_client, file_write, static_file_server and an ai_agent example. The quickest path to a running system is the prepared Docker image, which internally runs Wasker, builds Mewz, and runs it on QEMU.

curl -o helloworld.wat https://raw.githubusercontent.com/Mewz-project/Wasker/main/helloworld.wat
docker run -v .:/volume ghcr.io/mewz-project/mewz helloworld.wat

The Dev Container route is the one to use if you want to work on the kernel itself. It runs on GitHub Codespaces or in a local VSCode, and the sequence inside the container is short.

# On the Dev Container
git submodule update --init
curl -o helloworld.wat https://raw.githubusercontent.com/Mewz-project/Wasker/main/helloworld.wat
wasker helloworld.wat
zig build -Dapp-obj=wasm.o run

Building from source is the same idea with the object file path supplied explicitly.

zig build -Dapp-obj=<path to the object file generated by Wasker> run

Filesystems, the directory flag and the QEMU port mapping

To use file systems you specify the directory with -Ddir, and the examples/static_file_server entry shows how. The README attaches a warning to that option: it makes an archive of the directory with tar and attaches it to QEMU. That is a meaningful operational detail, because it means the file system handed to the application is baked into an image at build time rather than mounted live. There is a separate note that QEMU's port 1234 is mapped to localhost:1234, which is how a network example reaches the host. The repository tree supports the picture of a self-contained system: build.zig at the root, src/ for the kernel, submodules/ and a .gitmodules file for the vendored pieces, an lwip-wrapper/ directory for the TCP/IP stack, scripts/ for build helpers such as build-newlib.sh and build-lwip.sh, and a Dockerfile that pulls the Wasker image as its base.

Debugging Mewz with GDB on port 12345

The kernel is debuggable, and the mechanism is a QEMU GDB stub. The README says that when you run Mewz with QEMU, it listens on port 12345 for GDB, and that you can connect by running GDB at the root of the repository because a .gdbinit is already configured. The repository tree confirms that, with .gdbinit at the top level.

zig build -Dapp-obj=<path to the object file generated by Wasker> run
# In another terminal
gdb

There is a separate debug target for the awkward cases. The zig build debug command prevents Mewz from booting up until GDB connects, which the README says is useful when you want to debug the boot process itself, and it takes the same app-obj option.

zig build -Dapp-obj=<path to the object file generated by Wasker> debug
# In another terminal
gdb

The integration tests have their own invocation, listed in the README as zig bulid -Dtest=true run, with the misspelling of build as it appears in the document.

The status table: what works and what does not

The Current Status table in the README is the most honest section of the documentation, and it should drive any adoption decision. WASI Preview 1 is In Progress with a partial implementation, with a pointer to issue 1 for detail. Socket support is marked as done and, importantly, is described as WasmEdge compatible. The Component Model is Not yet. The file system has two modes, an in-memory file system that is read-only, and Virtio-FS which is read and write but partial. Network support is marked as done. So the honest summary is that the networking layer is the strongest part of the implementation, the POSIX-like surface that WASI programs expect is still incomplete, and the newer Component Model work has not started. This is a 0.1.x project with a working skeleton rather than a finished system.

The limits, and what a Wasm runtime already does for you

Three constraints deserve naming. The first is that a unikernel serves one application, so any requirement to run two services on one host, or to run a workload you did not compile in, means going back to a general-purpose operating system. The second is that the toolchain is not a single command. Wasker has to run first, the object file has to be threaded through a Zig build, and the result boots under QEMU, which is a meaningful pipeline to put in front of every build. The third is that the POSIX surface is partial, and a Wasm module written against a full WASI implementation may assume behaviour that Mewz does not yet provide. The alternative to weigh is running the same module on an existing Wasm runtime on Linux, where the module is unchanged and the host is boring. The difference in approach is the whole argument of the project: Mewz removes the operating system layer and the runtime layer from the deployment, at the cost of a bespoke build pipeline and a compatibility surface that is not finished.

How the Docker image is assembled, and where the pieces come from

The Dockerfile shows the whole build in one file, which is the clearest summary of the project. It starts from the Wasker image, ghcr.io/mewz-project/wasker:latest, so the Wasm tool is already present, and it pins a Zig version through a build argument, zig-x86_64-linux-0.16.0-dev.2979+e93834410, which is a development build rather than a release. That version is downloaded from the Zig build service, unpacked and moved into /usr/bin/zig. The image then installs the system dependencies in one layer, including curl, xz-utils, qemu-system, qemu-system-common, qemu-utils, git, cmake, libstdc++6 and build-essential, and runs the two repository scripts that build the C library and the network stack, ./scripts/build-newlib.sh and ./scripts/build-lwip.sh. The entrypoint is the run script, and the whole context is copied in. The repository is not archived, and the last push was on 2026-10-18, so the kernel is still being worked on even though the newest tagged release is from 2025.

Editorial conclusion

Adopt Mewz if you are deploying a single WebAssembly workload and want it to run without a general-purpose operating system underneath, since linking the application into the kernel removes the Linux layer entirely. Do not adopt it as a general WASI runtime today, because the README lists WASI Preview 1 as a partial implementation and the Component Model as not yet started. Before you rely on it, read the current status table, confirm that the file system mode you need is available, since the in-memory file system is read-only and Virtio-FS is only partially read and write, and check that the Wasker toolchain step is acceptable in your build.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. mewz-project/mewz on GitHub
4. README
5. Releases