7 Introduction to Wasm containers

This chapter introduces how WebAssembly (Wasm) fits into the modern packaging and deployment landscape by comparing it to traditional containers and explaining its distribution story. Whereas containers bundle an application with a userspace environment that runs atop the host kernel, Wasm packages only application logic and relies on a runtime plus WASI for system access. The result is smaller artifacts, faster startup, and hardware-agnostic portability, with runtime implementers bearing most cross-platform responsibility rather than app developers.

Building on that foundation, the chapter shows how “Wasm containers” work within the container ecosystem. Using containerd and a Wasm-aware shim, a Wasm module can be run much like a containerized process, enabling familiar tooling to orchestrate Wasm workloads. It then extends to distribution via the Open Container Initiative: recent OCI specs support artifact types that let Wasm components and their WIT metadata be pushed to and pulled from registries, inspected for capabilities, and integrated into cloud-native workflows. The hands-on walkthroughs cover building a minimal Wasm container image, importing and running it with containerd, and packaging components as OCI images using standard tooling.

Finally, the chapter explores two complementary paths for higher-level runtimes and migration. For full-featured environments like wasmCloud, the runtime and supporting services (such as NATS and orchestration) are packaged into containers and coordinated with tools like Docker Compose, preserving the platform’s ecosystem and developer experience. In parallel, the chapter demonstrates converting existing Linux containers to Wasm with container2wasm, which embeds CPU emulation to run unmodified workloads. While this approach trades off performance and size, it unlocks strong sandboxing, broad portability, and novel scenarios such as in-browser execution, offline-first apps, and secure ephemeral environments.

The typical architecture of a containerized system, illustrating how applications are packaged with their dependencies and userspace environment, all managed by the Docker engine on top of the host operating system.

A side-by-side comparison of the execution models for containers and Wasm, showing how both systems provide an abstraction layer between applications and the host operating system.

A detailed view inside the Docker engine, showcasing the key components and mechanisms (e.g., containerd, runc, and containerd-shim) responsible for managing and starting container processes.

A closer look inside the Docker engine when executing a Wasm module, showing the key components, including containerd-shim-wasm and the Wasm runtime.

A comparison of two approaches to running Wasm in containers. On the left, Wasm runs directly inside a container using a lightweight shim. On the right, Wasm is packaged within a container alongside supporting infrastructure, as seen in wasmCloud’s approach, which includes components like the NATS server, a local OCI registry, and metrics/tracing tools.

container2wasm encapsulates a CPU emulator to run Linux and Linux applications inside Wasm, enabling execution within either a WASI runtime or a browser environment.

• Containers and Wasm share similarities in providing portability and isolation, but Wasm eliminates the need for a guest OS, resulting in smaller binaries and faster startup times.
• Wasm containers leverage containerization principles to package and distribute Wasm binaries, integrating them into cloud-native ecosystems while maintaining Wasm’s lightweight nature.
• The Open Container Initiative (OCI) now supports Wasm artifacts, enabling standardized distribution of Wasm components via OCI registries like GitHub Container Registry (GHCR).
• Unlike traditional container-based Wasm execution, wasmCloud packages an entire host environment inside a container, facilitating managed orchestration of Wasm components.
• container2wasm enables running Linux applications as Wasm binaries by encapsulating a CPU emulator, expanding Wasm’s use cases to legacy applications and in-browser execution.

FAQ

What is container2wasm and how do I convert and run a Linux container as Wasm?

container2wasm compiles CPU emulators (like QEMU) into Wasm to run Linux-based containers as Wasm binaries with minimal changes. Steps: build your container (e.g., Python+Flask), run c2w , then execute with c2w-net to proxy networking (e.g., map port 8000). Trade-offs: larger binaries and lower performance versus “native” Wasm, but you gain portability and sandboxing, even enabling in-browser scenarios.