WebAssembly containers

What it is and why it exists

A WebAssembly module is compact, validated binary code instantiated by a host runtime. It can use its own instructions and memory plus imports supplied by the host; it cannot issue arbitrary system calls like a native Linux process. Core Wasm defines the computation model, but not files, sockets, environment variables, or clocks.

“WebAssembly container” is not another Linux container format. It usually means a Wasm module or component placed in an OCI image or artifact, then executed by an engine such as Wasmtime and a specialized shim connected to containerd. Registries, content digests, Kubernetes Pods, and deployment controllers remain useful, but the execution boundary changes from a native process to a Wasm instance.

WASI, the WebAssembly System Interface , adds standardized host interfaces. A runtime can provide interfaces for filesystems, randomness, clocks, command lines, or HTTP, and it can withhold them. A WASI application starts with no ambient authority and can use only capabilities the host explicitly grants.

This model fits narrowly interfaced workloads with a clear portability need, such as event handlers, plug-ins, edge functions, and policy evaluators. It is not a transparent acceleration switch for an existing container image. Applications that depend on fork, arbitrary dynamic libraries, Linux devices, shell scripts, or unported native extensions should usually stay in ordinary containers or undergo a bounded porting assessment first.

How it works

The delivery chain has three independent contracts. The compile contract determines whether the result is a core module or component and whether it targets wasip1, wasip2, or another host interface. The distribution contract defines how an OCI manifest, config, and layers are stored by digest. The execution contract determines which shim, engine, and configuration supply the imports declared by the module.

A core module encodes dependencies as imports and callable functionality as exports. During instantiation, the host must satisfy every import with a value whose name and type match, or instantiation fails. That linking mechanism explains why host access is absent by default, but complete capability security still depends on how the runtime constructs the WASI context, which directories it preopens, and which network destinations it permits.

The Component Model adds typed interfaces and composition rules over core modules. WIT describes interfaces and a world’s imports and exports; component tools generate language bindings and Canonical ABI adapters. A wasip1 core module and a wasip2 component that imports wasi:http do not have the same execution contract, and the file extension cannot prove they are compatible.

OCI provides content-addressed distribution, not execution. The CNCF Wasm OCI Artifact layout uses an OCI image manifest, an application/vnd.wasm.config.v0+json config, and an application/wasm layer; layer digests in the config must follow manifest order. runwasi also demonstrates a compatibility path that stores the .wasm file inside a conventional OCI filesystem image. Choose between them based on common support across the registry, builder, scanner, containerd version, and shim.

A containerd shim maps containerd’s task lifecycle to a particular Wasm host. After Kubernetes submits a Pod through CRI, a RuntimeClass handler must correspond to CRI runtime configuration on every eligible node. A Pod references the RuntimeClass metadata.name, not the shim binary name directly.

Examples

Instantiate a module with no imports

The first sample contains a real core Wasm module that exports double. The byte array keeps the sample independent of a WAT compiler; production builds should have a language toolchain generate .wasm rather than hand-writing bytecode.

Successful validation proves only that the bytes satisfy core Wasm rules. imports: 0 means the module requires no host functions, so Node 24 can instantiate it directly. It is not yet a WASI application and was not started from an OCI artifact; those three stages need separate checks.

Satisfy a host import explicitly

The second module imports host.audit and calls it from run. The first instantiation supplies no import and produces the observed TypeError in Node 24; only the second gives the module a narrow function.

const bytes = Uint8Array.from([
  0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
  0x01, 0x05, 0x01, 0x60, 0x01, 0x7f, 0x00,
  0x02, 0x0e, 0x01, 0x04, 0x68, 0x6f, 0x73, 0x74,
  0x05, 0x61, 0x75, 0x64, 0x69, 0x74, 0x00, 0x00,
  0x03, 0x02, 0x01, 0x00,
  0x07, 0x07, 0x01, 0x03, 0x72, 0x75, 0x6e, 0x00,
  0x01,
  0x0a, 0x08, 0x01, 0x06, 0x00, 0x20, 0x00, 0x10,
  0x00, 0x0b,
]);

const module = await WebAssembly.compile(bytes);
const required = WebAssembly.Module.imports(module)[0];
console.log(`requires: ${required.module}.${required.name} (${required.kind})`);

try {
  await WebAssembly.instantiate(module, {});
} catch (error) {
  console.log(`without grant: ${error.name}`);
}

const imports = { host: { audit: value => console.log(`audit: ${value}`) } };
const instance = await WebAssembly.instantiate(module, imports);
instance.exports.run(7);

requires: host.audit (function)
without grant: TypeError
audit: 7

This code demonstrates import linking; it does not pretend to implement full WASI. A real runtime must also constrain the import implementation, including paths reachable through directory handles, hosts reachable through an HTTP client, and the time or memory a call may consume. The absence of an import inside the module does not revoke Pod permissions granted elsewhere to the host.

Build a content-addressed OCI layout

The third sample writes the same module into a local OCI image layout. It computes real digests for the module, Wasm config, and manifest, then points index.json at the manifest; the five output files are three blobs, oci-layout, and the index.

import { createHash } from "node:crypto";
import { mkdir, writeFile } from "node:fs/promises";

const root = "double-oci";
const wasm = Buffer.from([
  0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
  0x01, 0x06, 0x01, 0x60, 0x01, 0x7f, 0x01, 0x7f,
  0x03, 0x02, 0x01, 0x00,
  0x07, 0x0a, 0x01, 0x06, 0x64, 0x6f, 0x75, 0x62,
  0x6c, 0x65, 0x00, 0x00,
  0x0a, 0x09, 0x01, 0x07, 0x00, 0x20, 0x00, 0x41,
  0x02, 0x6c, 0x0b,
]);
const encode = value => Buffer.from(JSON.stringify(value));
const digest = data => `sha256:${createHash("sha256").update(data).digest("hex")}`;
const descriptor = (mediaType, data) => ({ mediaType, digest: digest(data), size: data.length });

await mkdir(`${root}/blobs/sha256`, { recursive: true });
const put = async data => writeFile(`${root}/blobs/sha256/${digest(data).slice(7)}`, data);
const layer = descriptor("application/wasm", wasm);
const configBytes = encode({ architecture: "wasm", os: "wasip1", layerDigests: [layer.digest] });
const config = descriptor("application/vnd.wasm.config.v0+json", configBytes);
const manifestBytes = encode({
  schemaVersion: 2,
  mediaType: "application/vnd.oci.image.manifest.v1+json",
  config,
  layers: [layer],
});
const manifest = descriptor("application/vnd.oci.image.manifest.v1+json", manifestBytes);
manifest.annotations = { "org.opencontainers.image.ref.name": "double:v1" };

await Promise.all([put(wasm), put(configBytes), put(manifestBytes)]);
await writeFile(`${root}/oci-layout`, encode({ imageLayoutVersion: "1.0.0" }));
await writeFile(`${root}/index.json`, encode({ schemaVersion: 2, manifests: [manifest] }));

console.log(`layer: ${layer.digest} (${layer.size} bytes)`);
console.log(`config: ${config.mediaType}`);
console.log(`manifest: ${manifest.digest}`);
console.log("files: 5");

layer: sha256:45eb05dbe0a0a2df47788f382ba1d87adab365e30c522c7bc86e0d0e705b1395 (43 bytes)
config: application/vnd.wasm.config.v0+json
manifest: sha256:8572cf38f180477993582dc7bd712ea50f8382e201d4799e417af28952c78725
files: 5

Here wasip1 denotes a plain core module under the artifact specification; the sample has no WASI imports. A component needs wasip2 and component metadata containing its actual imports, exports, and optional target. Do not copy these example digests to another module or change a blob after writing the manifest; any content change requires recalculating that descriptor and every parent manifest digest.

Check the RuntimeClass mapping

The last sample checks three names that are easy to confuse: the Pod selects a RuntimeClass name, the RuntimeClass points to a CRI handler, and a custom node label narrows scheduling. The node label states that the host has the runtime installed; it does not misrepresent the host CPU architecture as wasm32.

const runtimeClass = {
  apiVersion: "node.k8s.io/v1",
  kind: "RuntimeClass",
  metadata: { name: "wasm-wasmtime" },
  handler: "wasmtime",
  scheduling: {
    nodeSelector: { "runtime.codewiki.dev/wasmtime": "true" },
  },
};

const pod = {
  metadata: { name: "receipt-worker" },
  spec: {
    runtimeClassName: "wasm-wasmtime",
    containers: [{ name: "worker", image: "registry.example/receipt:v1" }],
  },
};

const configuredHandlers = new Set(["runc", "wasmtime"]);
const eligibleNodes = [
  { name: "worker-a", labels: { "runtime.codewiki.dev/wasmtime": "true" } },
  { name: "worker-b", labels: {} },
].filter(node =>
  Object.entries(runtimeClass.scheduling.nodeSelector)
    .every(([key, value]) => node.labels[key] === value),
);

console.log(`class selected: ${pod.spec.runtimeClassName === runtimeClass.metadata.name}`);
console.log(`handler configured: ${configuredHandlers.has(runtimeClass.handler)}`);
console.log(`eligible nodes: ${eligibleNodes.map(node => node.name).join(", ")}`);

class selected: true
handler configured: true
eligible nodes: worker-a

This local check cannot prove that a cluster installed the shim. Before deployment, inspect containerd’s CRI configuration, the shim binary, runtime version, and image-format support on every node class, then create a real Pod. If the cluster uses another handler name, change the RuntimeClass and node configuration; business manifests should not guess binary paths.

Pitfalls

Treating Wasm as an ordinary Linux image

Fix: determine whether the shim accepts a conventional filesystem image containing .wasm or a Wasm OCI artifact. Validate probes, command overrides, and debugging procedures against that runtime. When you need sidecar tooling, deploy it as a separate Linux container instead of assuming it can enter the Wasm instance’s filesystem.

Treating an import declaration as a grant

Fix: grant preopened directories, network destinations, environment variables, and secrets individually in runtime configuration, then test that unauthorized access fails. Review the Kubernetes ServiceAccount, volumes, Pod network, and node permissions too, because the Wasm sandbox sits inside those outer permissions.

Mixing WASI generations and component worlds

Fix: record the target, component world, and WIT dependency versions in build output, then inspect imports on the target runtime. Do not infer format from the extension. When the compiler, binding generator, or runtime changes, rerun compatibility tests on the same artifact instead of checking only that source code compiles.

Faking a node architecture or handler

Fix: preserve the CPU labels reported by kubelet and add a separately managed runtime-capability label. Have the platform team create RuntimeClasses centrally and verify each handler in CRI configuration on all matching nodes. Deployment tests must cover scheduling failure, image-pull failure, and shim startup failure, not merely YAML validation.

Equating a sandbox with supply-chain trust

Fix: pin and update the shim and engine, deploy signed artifacts by digest under admission checks, and do not accept untrusted native precompiled cache entries from image layers. Keep outer container isolation, read-only mounts, network policy, and a minimal ServiceAccount even when the inner module is constrained by Wasm.

Further reading

• WebAssembly Core Specification
• Node.js 24 WebAssembly API
• WebAssembly Component Model
• OCI Image Format Specification
• CNCF Wasm OCI Artifact layout
• runwasi demos and artifact formats