How to Configure Nydus to Work with Docker Runtime: Complete Setup Guide

Configure Nydus to work with Docker runtime by installing the nydus-snapshotter and nydusd binaries, enabling the containerd-snapshotter feature in Docker, registering Nydus as a containerd proxy plugin, and starting the snapshotter systemd service.

Nydus is a high-performance container image service that accelerates image distribution and startup through lazy-loading technology. To configure Nydus to work with Docker runtime, you must integrate the Nydus snapshotter with containerd, which Docker uses as its underlying image storage backend. This guide walks through the complete setup using the official dragonflyoss/nydus repository configuration files and binaries.

How Nydus Integrates with Docker

When you configure Nydus to work with Docker runtime, the data flow follows this architecture:

1. Docker → containerd – Docker delegates image storage operations to containerd.
2. containerd → snapshotter – containerd loads the Nydus snapshotter as a proxy plugin that implements the snapshotter interface.
3. Nydus snapshotter – The containerd-nydus-grpc service reads the Nydus image manifest, pulls compressed data on demand, and presents a mounted view via FUSE.
4. Docker runtime – Docker sees the mounted view as the container’s root filesystem and starts the container.

This lazy-loading approach eliminates the need to download full image layers before container startup, significantly reducing startup time for large images.

Prerequisites

Before configuring Nydus with Docker, ensure your system meets these requirements:

• FUSE support – The kernel must support FUSE (Filesystem in Userspace). Install the fuse package and load the module with modprobe fuse.
• Docker with containerd integration – Docker must support the containerd-snapshotter feature (available in Docker 23.0+).
• Systemd – For managing the nydus-snapshotter service.

Step-by-Step Configuration

Install Nydus Components

First, install the nydus-snapshotter binary and the nydus image service (nydusd). These components handle the lazy-loading filesystem operations.

# Stop Docker and containerd to prevent conflicts during installation

sudo systemctl stop docker
sudo systemctl stop containerd

# Install nydus-snapshotter (containerd-nydus-grpc)

TAG=$(curl -s https://api.github.com/repos/containerd/nydus-snapshotter/releases/latest \
      | grep tag_name | cut -d'"' -f4)
wget https://github.com/containerd/nydus-snapshotter/releases/download/${TAG}/nydus-snapshotter-${TAG}-linux-amd64.tar.gz
tar -xzvf nydus-snapshotter-${TAG}-linux-amd64.tar.gz
sudo install -D -m 755 bin/containerd-nydus-grpc /usr/local/bin

# Install nydus image service (nydusd)

TAG=$(curl -s https://api.github.com/repos/dragonflyoss/nydus/releases/latest \
      | grep tag_name | cut -d'"' -f4)
wget https://github.com/dragonflyoss/image-service/releases/download/${TAG}/nydus-static-${TAG}-linux-amd64.tgz
tar -xzvf nydus-static-${TAG}-linux-amd64.tgz
sudo cp -r nydus-static/* /usr/local/bin
sudo chmod -R 755 /usr/local/bin/nydus*

Download Configuration Files

The Nydus snapshotter requires configuration files for the daemon and FUSE device settings. Download the default configurations from the official repository:

# Create configuration directory

sudo mkdir -p /etc/nydus

# Download nydusd configuration for FUSE device

sudo wget -O /etc/nydus/nydusd-config.fusedev.json \
  https://raw.githubusercontent.com/containerd/nydus-snapshotter/main/misc/snapshotter/nydusd-config.fusedev.json

# Download snapshotter configuration

sudo wget -O /etc/nydus/config.toml \
  https://raw.githubusercontent.com/containerd/nydus-snapshotter/main/misc/snapshotter/config.toml

Configure Docker Daemon

Enable the containerd-snapshotter feature and set the storage driver to nydus in Docker's configuration:

cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "features": { "containerd-snapshotter": true },
  "storage-driver": "nydus"
}
EOF

The containerd-snapshotter feature allows Docker to delegate snapshot operations to containerd plugins, while the storage-driver setting specifies that Docker should use the Nydus snapshotter for image layers.

Configure containerd Proxy Plugin

Register the Nydus snapshotter as a proxy plugin in containerd's configuration file:

cat <<EOF | sudo tee /etc/containerd/config.toml
version = 2

[proxy_plugins]
  [proxy_plugins.nydus]
    type = "snapshot"
    address = "/run/containerd-nydus/containerd-nydus-grpc.sock"
EOF

This configuration tells containerd to connect to the Nydus snapshotter via the specified Unix socket. The snapshotter implements the containerd snapshotter interface, allowing it to handle layer extraction and mounting.

Start the Nydus Snapshotter Service

Deploy and start the systemd service for the Nydus snapshotter:

# Download the systemd unit file

sudo wget -O /etc/systemd/system/nydus-snapshotter.service \
  https://raw.githubusercontent.com/containerd/nydus-snapshotter/main/misc/snapshotter/nydus-snapshotter.fusedev.service

# Reload systemd and start the service

sudo systemctl daemon-reload
sudo systemctl enable --now nydus-snapshotter

# Verify the service is running

sudo systemctl status nydus-snapshotter

Restart Docker and containerd

Finally, restart the container runtime components to apply the configuration changes:

# Ensure Docker uses the correct socket type (fix for systemd units)

sudo sed -i 's/fd:/unix:/g' /lib/systemd/system/docker.service

# Reload and restart services

sudo systemctl daemon-reload
sudo systemctl restart containerd
sudo systemctl restart docker

Converting and Running Images

Once the runtime is configured, convert existing Docker images to the Nydus format and run them:

# Start a local registry for testing (optional)

sudo docker run -d --restart=always -p 5000:5000 registry

# Convert an image to Nydus format

sudo nydusify convert --source ubuntu --target localhost:5000/ubuntu-nydus

# Run the Nydus image using standard Docker commands

sudo docker run --rm -it localhost:5000/ubuntu-nydus:latest bash

The nydusify tool handles the conversion of OCI/Docker images into the Nydus format, which uses a content-addressable filesystem with lazy-loading capabilities.

Summary

To configure Nydus to work with Docker runtime, complete these essential steps:

• Install binaries – Deploy containerd-nydus-grpc (snapshotter) and nydusd (image service) to /usr/local/bin.
• Enable containerd-snapshotter – Set "features": { "containerd-snapshotter": true } and "storage-driver": "nydus" in /etc/docker/daemon.json.
• Register proxy plugin – Configure containerd to connect to the Nydus snapshotter via Unix socket in /etc/containerd/config.toml.
• Start services – Enable the nydus-snapshotter systemd service and restart Docker and containerd.
• Convert images – Use nydusify convert to transform standard images into Nydus format for lazy-loading.

Frequently Asked Questions

What is the minimum Docker version required for Nydus integration?

Docker 23.0 or later is required because Nydus integration depends on the containerd-snapshotter feature, which became stable in Docker 23.0. Earlier versions do not support delegating snapshot operations to containerd plugins, which is essential for the Nydus lazy-loading architecture.

Why does Nydus require FUSE on the host system?

Nydus uses FUSE (Filesystem in Userspace) to mount container images without requiring kernel modifications. The nydusd daemon implements a userspace filesystem that intercepts read requests and fetches data lazily from the registry. Without FUSE support loaded via modprobe fuse, the snapshotter cannot create the overlay mounts required for container root filesystems.

How do I verify that Docker is actually using the Nydus snapshotter?

Check the Docker daemon configuration and running processes. First, verify /etc/docker/daemon.json contains "storage-driver": "nydus". Then confirm the containerd-nydus-grpc process is running with sudo systemctl status nydus-snapshotter. Finally, run a container from a Nydus-converted image and check the mount type with mount | grep nydus—you should see FUSE mounts associated with the container ID.

Can I run standard OCI images without converting them to Nydus format?

No, standard OCI/Docker images must be converted to the Nydus format using nydusify convert before they can benefit from lazy-loading. The Nydus snapshotter expects a specific image manifest structure with blob and bootstrap layers. However, after conversion, you can run these images with the standard docker run command just like regular images.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}