containerd-shim-edgelet

containerd-shim-edgelet-wasm-v2 is a containerd shim v2 runtime for generic WASM/WASI workloads.

Stable integration identifiers:

• runtime type: io.containerd.edgelet.wasm.v2
• CRI handlers: wasm, wasm-local
• shim binary: containerd-shim-edgelet-wasm-v2

Containerd 2.x CRI config contract (v3)

Use containerd 2.x with plugin path io.containerd.cri.v1.runtime.

version = 3

[plugins.'io.containerd.cri.v1.runtime'.containerd]
  default_runtime_name = "wasm"

[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.wasm]
  runtime_type = "io.containerd.edgelet.wasm.v2"
  runtime_path = "/usr/local/bin/containerd-shim-edgelet-wasm-v2"

[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.wasm-local]
  runtime_type = "io.containerd.edgelet.wasm.v2"
  runtime_path = "/usr/local/bin/containerd-shim-edgelet-wasm-v2"

After updating config:

1. Ensure containerd-shim-edgelet-wasm-v2 is on PATH for containerd. For ctr --runtime=io.containerd.edgelet.wasm.v2, also ensure containerd-shim-wasm-v2 resolves to the same binary (symlink is acceptable).
2. Restart containerd.
3. Confirm runtime config load via containerd config dump.

ctr smoke path (containerd 2.x)

Script:

• scripts/smoke-ctr-containerd-v2.sh

Default smoke image:

• ghcr.io/containerd/runwasi/wasi-demo-app:latest

Dry-run (CI/local validation of command shape)

make smoke-ctr-dry

Live smoke run (Linux host, root/sudo, running containerd)

bash scripts/smoke-ctr-containerd-v2.sh

Expected outcome:

• ctr successfully pulls the image.
• ctr run --runtime io.containerd.edgelet.wasm.v2 completes with exit code 0.
• Demo workload emits its expected stdout (depends on image).

Troubleshooting

• missing required command: containerd-shim-edgelet-wasm-v2
  • Install/copy the shim binary and ensure it is in PATH.
• containerd daemon is not running
  • Start containerd and retry.
• ctr run fails with runtime not found
  • Check runtime_type = "io.containerd.edgelet.wasm.v2" and runtime_path = "/usr/local/bin/containerd-shim-edgelet-wasm-v2" in config, then restart containerd.
  • Ensure containerd-shim-wasm-v2 points to containerd-shim-edgelet-wasm-v2.
• handler mismatch in CRI flows
  • Ensure both handlers wasm and wasm-local are configured under io.containerd.cri.v1.runtime.

Release artifact contract

Tagged releases publish six Linux archives (GNU + MUSL), each containing only containerd-shim-edgelet-wasm-v2 and a matching SHA256 checksum file:

• containerd-shim-edgelet-wasm-v2-x86_64-linux-musl.tar.gz
• containerd-shim-edgelet-wasm-v2-aarch64-linux-musl.tar.gz
• containerd-shim-edgelet-wasm-v2-riscv64gc-linux-musl.tar.gz
• containerd-shim-edgelet-wasm-v2-x86_64-linux-gnu.tar.gz
• containerd-shim-edgelet-wasm-v2-aarch64-linux-gnu.tar.gz
• containerd-shim-edgelet-wasm-v2-riscv64gc-linux-gnu.tar.gz

Developer command surface

Make targets added for release and runtime operations:

• Build:
  • make build
  • make build-cross-x86_64-unknown-linux-musl (or other target triple)
  • make build-all-targets
• Test:
  • make test
  • make test-unit
  • make test-feature-matrix
  • make test-integration-containerd
• Smoke:
  • make smoke-dry
  • make smoke-local
• Dist/release checks:
  • make dist
  • make release-check
  • make clean-dist
• Lima helpers:
  • make setup-lima
  • make lima-smoke
  • make lima-clean

Linux setup and Lima workflow

Linux host bootstrap:

bash scripts/setup-linux.sh

Lima workflow for macOS/Linux (dedicated instance edgelet-shim by default):

bash scripts/lima-up.sh
bash scripts/lima-smoke.sh
bash scripts/lima-down.sh

lima-smoke.sh enforces the required runwasi demo gate.

Official runwasi demo gate (required)

Runtime integration must pass this canonical case:

sudo ctr images pull ghcr.io/containerd/runwasi/wasi-demo-app:latest
sudo ctr run --rm --runtime=io.containerd.edgelet.wasm.v2 ghcr.io/containerd/runwasi/wasi-demo-app:latest testwasm

This same gate is used in:

• local integration script: scripts/test-containerd-integration.sh
• CI runtime integration job in .github/workflows/ci.yml

WASI-NN v1 behavior (wasi-nn-stub)

Current v1 behavior is a deterministic stub only:

• No ONNX/OpenVINO/CUDA/cuDNN/GGML runtime backends are linked.
• wasi-nn is not available for real model inference yet.
• Probe path is explicit and deterministic for operator visibility.

Probe behavior:

EDGELET_WASI_NN_PROBE=1 containerd-shim-edgelet-wasm-v2 ...

Expected result:

• If wasi-nn-stub is enabled (default): error reports that wasi-nn is stubbed and no backend is configured.
• If wasi-nn-stub is disabled at compile time: error reports feature is disabled.