containerd/runwasi: Running WebAssembly Through containerd

Why runwasi sits between containerd and WASI

runwasi addresses a specific gap between two execution models. containerd expects workloads to be represented as container images and managed through its task, runtime, and shim model, while a WebAssembly application needs a WebAssembly runtime that can execute WASI components or modules. The project connects those layers rather than attempting to replace containerd with a general-purpose WASI command-line runtime.

Its intended users are developers who want to integrate a WebAssembly host with container infrastructure. The README names two management paths: direct use through `ctr`, and operation directed by Kubelet through the containerd CRI plugin. That makes the project relevant to teams experimenting with WebAssembly inside familiar container workflows, particularly where pulling, creating, and running images through containerd is already part of their operational model.

There is an important maturity qualifier. The repository describes its included plain WASI host as a proof of concept, with no extra host functions beyond those needed to support WASI system calls. That boundary matters. A workload requiring custom host APIs, arbitrary operating-system facilities, or a particular runtime extension may not fit the documented model. runwasi addresses workload integration, not every possible WebAssembly compatibility requirement.

The shim architecture behind runwasi workloads

Based on the workspace layout, runwasi separates a common WebAssembly shim crate from runtime-specific implementations. The workspace includes `crates/containerd-shim-wasm`, `crates/containerd-shimkit`, and dedicated crates for Wasmtime, Wasmer, WasmEdge, and WAMR. Shared supporting crates include a test-module package, an OCI tar builder, and a stress-test package.

That structure indicates a shim-based architecture. containerd delegates execution to a named runtime shim, while the runtime-specific crate handles the WebAssembly engine and the included common crate provides integration pieces shared by those implementations. The workspace also defines `containerd-shim` and `oci-spec` dependencies, which connect the shim side to containerd conventions and OCI image specifications. The Makefile exposes runtime-related variables for `wasmedge`, `wasmtime`, `wasmer`, and `wamr`, matching the set of runtime crates in the workspace.

The documented execution path remains concise. An image is pulled into containerd, and `ctr run` selects `io.containerd.wasmtime.v1` with the `--runtime` option. The README does not expose the complete internal request sequence or plugin configuration, so a reader should not infer every lifecycle detail from the crate names. What can be confirmed is that runtime selection is explicit at launch and that containerd remains the manager.

Building and installing the Rust shim set

The README gives a short local installation path through the repository's Makefile. The build uses `cargo` for a native target and selects `cross` when the target differs from the host. With `CARGO=cross`, the Makefile defaults the target to a `musl` target and writes build output under `./target/build/<target>/`, a detail intended to make a static shim easier to distribute across Linux distributions.

From a source checkout, build the project and install it with the documented commands:

make build
sudo make install

The installation uses `PREFIX ?= /usr/local` by default, so the repository's default installation destination is `/usr/local`. The Makefile also exposes controls such as `INSTALL`, `CARGO`, `TARGET`, and `OPT_PROFILE`, although the quick start does not require them. Detailed installation guidance is hosted on runwasi.dev rather than reproduced in the README. Readers operating an existing containerd installation should follow that guide because the two commands do not themselves establish every runtime configuration requirement.

The workspace uses Rust edition 2024. Its manifest also contains runtime dependencies and engine-specific configuration, so a successful local build is better understood as preparation for installing shims than as a complete deployment of a WASI execution stack.

Running the Wasmtime demo through ctr

The first documented use is a plain WASI demonstration image. First, pull `ghcr.io/containerd/runwasi/wasi-demo-app:latest` into containerd:

sudo ctr images pull ghcr.io/containerd/runwasi/wasi-demo-app:latest

After the pull completes, start the image with the Wasmtime runtime identifier:

sudo ctr run --rm --runtime=io.containerd.wasmtime.v1 ghcr.io/containerd/runwasi/wasi-demo-app:latest testwasm

The `--rm` option requests cleanup after the task exits, while `--runtime=io.containerd.wasmtime.v1` selects the Wasmtime shim rather than leaving runtime dispatch implicit. The final argument, `testwasm`, is the command passed to the demo workload.

This example is useful because it exercises the central claim: containerd can pull an OCI image and start a WebAssembly workload through a runwasi runtime shim. It is not a broader Kubernetes tutorial. The README says workloads may also be directed by Kubelet through the CRI plugin, but it does not provide a node configuration, runtime registration command, image configuration, or Kubernetes manifest in its quick start. Those details must come from the installation guide or demos site.

Runtime choice changes the integration surface

runwasi is not tied to one WebAssembly engine. The workspace lists separate shim crates for Wasmtime, Wasmer, WasmEdge, and WAMR, and recent releases include versioned artifacts for several of these integrations. The Makefile's `RUNTIMES` variable includes the same four names. This offers a concrete choice for a host team, but the repository does not claim that their capabilities, extension APIs, or compatibility are identical.

Wasmtime is the engine named in the quick start, which makes it the documented default path for evaluation even though the Makefile does not declare it as the only runtime. Other engines may be relevant when an application or host organization already depends on that runtime. Selecting one requires checking its own WebAssembly and WASI support separately; runwasi supplies the containerd-facing shim, not a guarantee of uniform application compatibility.

The project is therefore best described as a family of containerd shim integrations with a shared Rust foundation. A team should not choose among the engines solely because they appear in the workspace. The repository does not publish a comparison matrix in the README, and it does not document migration between runtimes. It also does not state that the proof-of-concept host exposes custom host functions beyond WASI system calls.

Operational limits and maintenance cost

The clearest limitation is scope. The included plain WASI host is explicitly a proof of concept, so applications that depend on richer host interfaces should be treated as outside what is established by the README. The same limitation applies to assumptions about networking, filesystems, custom devices, or other facilities not covered by the documented WASI call model.

The Kubernetes path introduces another verification item. Although the README says Kubelet can direct workloads through the CRI plugin, it does not identify the required containerd configuration in the quick start. Engineers cannot turn that sentence into a deployment plan without consulting the installation guide. Likewise, the quick start does not document logging, monitoring, rollback, image conversion, or production scheduling behavior for the runtime shims. Those omissions should not be filled with assumptions about containerd defaults.

Maintenance has recent repository activity. The last push was on 2026-10-15, and the repository is not archived. Recent releases include `containerd-shimkit/v0.1.2` on 2026-06-12, plus `containerd-shim-wasmtime/v0.6.1` and `containerd-shim-wasmer/v0.6.1` on the same date. Multiple runtime crates must be considered when upgrading the broader stack, although the README does not describe package compatibility in detail.

The project is licensed under `Apache-2.0`. That identifier permits use and modification under the license's terms, but organizations still need to review the actual `LICENSE`, `NOTICE`, dependency licenses, and their own distribution obligations. This is a compliance check, not legal advice.

Editorial conclusion

runwasi suits container platform engineers and Kubernetes integrators who already operate containerd and need WebAssembly workloads to participate in that lifecycle. It is a weaker fit for a developer who only wants a standalone WASI runtime or needs a production Kubernetes workflow immediately, because the repository describes a proof of concept and delegates detailed deployment guidance to external documentation. Before adoption, verify that the target workload needs only documented WASI system calls, confirm which runtime shim matches its requirements, and review the installation guide for the target containerd deployment. On the evidence available here, the basic `ctr` path is the clearest adoption gate.

Frequently asked questions

Official sources

1. containerd/runwasi on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases