OCI Compatibility

OCI Runtime and Tool Compatibility

The generated artifact targets OCI Image Layout 1.0, Linux, SHA-256 descriptors, a gzip tar layer, and amd64 or arm64.

Continuously tested matrix

The full, CI-sourced compatibility matrix (host OS, target image OS/arch, container runtime, Kubernetes, containerd shim, KVM/HVF hypervisor backends, guest kernel, signing interop) is authored at docs/reference/compatibility.md in the repository, next to the workflow files it cites, and mirrored to this wiki at Reference-Compatibility as of 2026-08-05 for offline/wiki-only browsing — the repo copy is still the one to trust if the two ever disagree; re-sync the mirror, don't edit it independently. As of 2026-08-04 that includes Podman (ci-launch.yml matrix [docker, podman]) and Kubernetes via kind (ci-kind-multinode.yml) — both now in the automated matrix, correcting this page's previous "not yet added" note for Podman.

Architecture declaration does not emulate CPU instructions. An amd64 payload needs an amd64 runtime unless the operator intentionally configures emulation; the MicroVM path requires host and guest architecture to match.

Consumer qualification procedure

Before approving a new runtime/version:

1. generate a layout from the release commit;
2. run verify-oci-layout.py;
3. import through the runtime's native OCI-layout/archive path;
4. inspect config user, entrypoint, platform, layer digest, and diff ID;
5. run /healthz with read-only root, all capabilities dropped, no privilege escalation, default seccomp, and no service-account token;
6. record tool/runtime/kernel versions and logs;
7. test malformed/corrupt layout rejection;
8. retain evidence and add the combination to CI if production depends on it.

Known portability boundaries

• Linux only; no Windows image manifest/config.
• amd64 and arm64 only; no multi-platform index in one invocation.
• One gzip layer; no zstd or nondistributable layer media types.
• Numeric UID/GID; no /etc/passwd entry.
• No shell or package manager in the final root filesystem.
• Dynamic payloads work only when every loader/library is explicitly packaged at the expected path and matches the target architecture.
• Runtime policies such as read-only root and no_new_privileges are not OCI image properties and must be supplied by the consumer.