# Nydus OCI Compatibility: How Dragonfly Extends Open Container Initiative Standards > Discover Nydus OCI compatibility. Dragonfly extends Open Container Initiative standards, ensuring seamless integration with registries and runtimes. - Repository: [dragonflyoss/nydus](https://github.com/dragonflyoss/nydus) - Tags: deep-dive - Published: 2026-02-28 --- **Nydus maintains full compatibility with OCI image and distribution specifications while extending them with additional manifest fields for RAFS bootstrap and data blobs, enabling seamless integration with standard container registries and runtimes.** Nydus, developed under the Dragonfly project (`dragonflyoss/nydus`), is a container image acceleration solution designed to work within the existing container ecosystem. The project achieves complete **Nydus OCI compatibility** by adhering to the Open Container Initiative (OCI) image and distribution specifications, allowing images to be stored in standard registries and executed by OCI-compliant runtimes without requiring infrastructure changes. ## OCI Image Manifest Extensions Nydus extends the OCI image manifest specification rather than replacing it. In [`docs/nydus-design.md`](https://github.com/dragonflyoss/nydus/blob/main/docs/nydus-design.md), the architecture defines how Nydus images maintain OCI compatibility while adding performance optimizations. ### Extended Manifest Structure with RAFS Bootstrap According to the design documentation at `docs/nydus-design.md#L9-L11`, Nydus introduces an additional manifest file that stores pointers to the RAFS (Registry Acceleration File System) bootstrap and data blobs. This manifest sits alongside the standard OCI image manifest, ensuring that: - Standard OCI tools can parse the image structure - The RAFS metadata remains accessible to Nydus-aware runtimes - Layer deduplication and chunk-level sharing remain intact ### Artifact Type Identification Nydus identifies its manifest format using the `artifactType` field specified in `docs/nydus-design.md#L25-L32`. The manifest declares: ``` application/vnd.nydus.image.manifest.v1+json ``` This MIME type allows OCI-aware tools to recognize Nydus images while still processing them as standard OCI artifacts. Container registries that support OCI image indexes can store and serve Nydus content without modification. ## OCI Distribution Spec Compliance Nydus maintains strict compliance with the OCI Distribution Specification, enabling seamless integration with existing container infrastructure. ### Standard Registry Support As documented in `service/README.md#L22-L23`, Nydus stores blobs in any OCI-compatible registry, including: - Docker Hub - Harbor - GitHub Container Registry (GHCR) - Amazon ECR - Google Container Registry Additionally, Nydus supports alternative storage backends that implement OCI distribution APIs, including object storage services (OSS, S3), network-attached storage (NAS), and local HTTP directories configured to mimic OCI registry endpoints. ## Converting OCI Images to Nydus Format The Nydus ecosystem provides tools that consume standard OCI images and produce Nydus-optimized versions while maintaining OCI compatibility. ### Using nydusify for Registry Conversion The `nydusify` tool, documented in `docs/nydusify.md#L5-L9`, accepts OCI images from remote registries or local OCI layouts and converts them to Nydus format: ```bash # Convert an OCI image to Nydus and push to registry nydusify \ --source docker.io/library/alpine:3.18 \ --target my-registry.example.com/alpine:nydus \ --output-type tar ``` This process preserves the original OCI image layers while generating additional RAFS bootstrap and data blobs that enable lazy loading and chunk deduplication. ### Using nydus-image for Local Conversion For local image manipulation, `nydus-image` provides detailed control over the conversion process, as described in `docs/nydus-image.md#L58-L66`: ```bash # Create a Nydus image from an OCI tarball nydus-image create \ --bootstrap /path/to/output/bootstrap \ --blob-dir /path/to/blobs \ /path/to/oci-layout.tar ``` This command generates the RAFS bootstrap and data blobs required for Nydus acceleration while maintaining compatibility with OCI distribution protocols. ## Runtime Compatibility with OCI-Compliant Engines Nydus images execute on standard container runtimes without requiring modifications to the underlying infrastructure, as confirmed in `README.md#L41-L44`. ### Supported Runtimes Nydus maintains compatibility with: - **containerd** – With the nydus-snapshotter plugin for lazy pulling - **Docker** – Via the nydus-snapshotter integration - **Kubernetes** – Through CRI-compliant container runtime interfaces - **CRI-O** – With snapshotter support enabled These runtimes process Nydus images as standard OCI artifacts because the manifest structure satisfies OCI schema requirements. The Nydus daemon provides additional benefits such as on-demand chunk fetching, chunk-level deduplication, and faster container start-up without breaking OCI compliance. ## Summary - Nydus extends rather than replaces OCI specifications, maintaining full backward compatibility with existing container infrastructure. - The `application/vnd.nydus.image.manifest.v1+json` artifact type allows OCI-aware tools to identify Nydus images while processing them as standard OCI artifacts. - Nydus images store in any OCI-compatible registry (Docker Hub, Harbor, GHCR, S3, OSS) without requiring registry modifications. - Conversion tools `nydusify` and `nydus-image` consume standard OCI images and produce Nydus-optimized versions that remain OCI-compliant. - Container runtimes including containerd, Docker, Kubernetes, and CRI-O execute Nydus images without infrastructure changes, leveraging the nydus-snapshotter for lazy loading capabilities. ## Frequently Asked Questions ### Is Nydus a replacement for OCI images? No, Nydus is not a replacement for OCI images. According to the source code in [`docs/nydus-design.md`](https://github.com/dragonflyoss/nydus/blob/main/docs/nydus-design.md), Nydus **augments** OCI specifications by adding an extra manifest file that stores RAFS bootstrap and data blob pointers while maintaining the overall OCI Image Spec structure. Standard OCI tools can still parse, distribute, and verify Nydus images because the manifest satisfies OCI schema requirements. ### Can Nydus images run on standard containerd without plugins? Standard containerd requires the **nydus-snapshotter** plugin to leverage Nydus-specific features like lazy pulling and chunk-level deduplication. However, as noted in `README.md#L41-L44`, the images themselves remain OCI-compliant and can be processed by standard containerd in a fallback mode, though without the performance benefits. For full Nydus acceleration, the snapshotter must be installed and configured. ### How does Nydus maintain OCI compatibility while adding deduplication? Nydus maintains OCI compatibility by storing deduplication metadata in separate RAFS bootstrap and data blobs that are referenced through an extended manifest, as described in `docs/nydus-design.md#L9-L11`. The manifest uses the `artifactType` field with value `application/vnd.nydus.image.manifest.v1+json` to identify the format while keeping the overall structure compliant with OCI Image Spec. This allows registries to store Nydus blobs alongside standard OCI layers without modification. ### Which registries support storing Nydus images? According to `service/README.md#L22-L23`, Nydus images can be stored in any **OCI-compatible registry**, including Docker Hub, Harbor, GitHub Container Registry (GHCR), Amazon ECR, and Google Container Registry. Additionally, Nydus supports object storage services like OSS and S3, NAS, and local HTTP directories configured to mimic OCI distribution APIs. No registry modifications are required because Nydus conforms to standard OCI Distribution Spec protocols.