Main Tools Provided by Nydus: nydusd, nydus-image, nydusify, and More

The main tools provided by Nydus are nydusd (the FUSE/Virtio-FS daemon), nydus-image (the RAFS builder), nydusify (the conversion orchestrator), nydusctl (the daemon client), and nydus-overlayfs (the containerd mount helper).

The dragonflyoss/nydus repository ships a comprehensive toolkit that enables high-performance, content-addressable container images. These main tools provided by Nydus work together to build, serve, and manage RAFS (Registry Acceleration File System) images across development and production environments.

Nydus Runtime Daemon (nydusd)

Core Responsibilities

nydusd runs as a user-space daemon that exposes a FUSE or Virtio-FS mountpoint to serve RAFS filesystems. It implements the RAFS server that reads chunked, deduplicated blobs from configured storage backends—including local filesystems, OSS, S3, or OCI registries. The daemon handles caching, prefetch strategies, and optional writable overlay support for container workloads.

Source Implementation

The daemon’s entry point is located at src/bin/nydusd/main.rs in the Nydus source tree. This binary initializes the FUSE session, parses the bootstrap file, and starts the API server that nydusctl connects to.

Practical Usage

Run nydusd with a local filesystem backend:

sudo nydusd \
  --config /etc/nydus/nydusd-config.localfs.json \
  --mountpoint /mnt/nydus \
  --bootstrap /var/lib/nydus/blobs/bootstrap \
  --log-level info

This command mounts the RAFS image at /mnt/nydus using FUSE.

Nydus Image Builder (nydus-image)

Building RAFS Filesystems

nydus-image is the low-level tool that generates RAFS filesystems—creating the bootstrap metadata and data blobs from a tarball or directory. It supports advanced features like chunk-dictionary generation for cross-layer deduplication, configurable compression algorithms, layer merging, and integrity verification.

Source Entry Point

The CLI driver resides at src/bin/nydus-image/main.rs. This binary handles subcommands such as create, check, unpack, and inspect, providing granular control over image construction.

Image Creation Example

Build a Nydus image from a local directory:

nydus-image create -t dir-rafs \
  -D /var/lib/nydus/blobs \
  /my/app/rootfs/

This outputs the bootstrap and blob files to /var/lib/nydus/blobs, ready for distribution.

Nydus Conversion Orchestrator (nydusify)

High-Level Workflows

nydusify provides a user-friendly CLI that orchestrates the entire conversion pipeline. It drives nydus-image internally, then pushes the resulting blobs to various backends (OSS, S3, localfs, or OCI registries). It offers subcommands for convert, pack, mount, copy, check, and optimize, abstracting the complexity of the lower-level tools.

OCI Conversion Example

Convert a Docker Hub image to Nydus format and push to a private registry:

nydusify convert \
  --source docker.io/library/ubuntu:20.04 \
  --target myregistry.example.com/ubuntu:20.04-nydus

nydusify handles the build, blob upload, and manifest generation automatically.

Daemon Management Client (nydusctl)

Runtime Inspection

nydusctl is the administrative client that communicates with nydusd over its Unix-domain socket (--apisock). It queries daemon status, retrieves metrics (cache hit ratios, blob access patterns), and can reconfigure runtime parameters such as cache size limits without restarting the service.

Source Location

The client implementation is located at src/bin/nydusctl/main.rs. It uses the daemon’s HTTP API over the Unix socket to perform operations.

Monitoring Example

Check daemon health and statistics:

nydusctl info

This displays cached blob counts, cache hit ratios, and current FUSE session information, aiding in performance tuning.

Containerd Integration Helper (nydus-overlayfs)

Snapshotter Compatibility

nydus-overlayfs acts as a mount helper that translates the extra mount options emitted by the Nydus snapshotter into standard overlayfs-compatible calls. This enables containerd to treat Nydus-backed layers identically to regular overlayfs layers, ensuring seamless integration with Kubernetes and other container orchestrators.

Configuration Example

Enable the helper in containerd’s configuration:

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

Containerd automatically invokes nydus-overlayfs when mounting Nydus-backed containers.

Summary

• nydusd serves RAFS images via FUSE or Virtio-FS from src/bin/nydusd/main.rs, handling runtime access and caching.
• nydus-image builds and manipulates RAFS filesystems from src/bin/nydus-image/main.rs, supporting chunking and compression.
• nydusify orchestrates OCI-to-Nydus conversions and registry pushes, providing a high-level workflow interface.
• nydusctl manages running daemons via the API socket defined in src/bin/nydusctl/main.rs, exposing metrics and runtime config.
• nydus-overlayfs bridges Nydus layers with containerd’s overlayfs snapshotter for Kubernetes integration.

Frequently Asked Questions

What is the difference between nydus-image and nydusify?

nydus-image is the low-level builder that creates RAFS bootstrap and blob files from directories or tarballs, residing at src/bin/nydus-image/main.rs. nydusify is a high-level orchestrator that wraps nydus-image to convert existing OCI images, push to registries, and manage complete workflows. Use nydus-image for manual image construction; use nydusify for automated CI/CD pipelines.

How does nydusd serve images to containers?

nydusd runs as a user-space daemon from src/bin/nydusd/main.rs, exposing a FUSE mountpoint or Virtio-FS socket. It reads the RAFS bootstrap to understand the filesystem layout, then fetches compressed chunks from storage backends (registry, S3, OSS) on demand. Container runtimes mount this FUSE filesystem as the container rootfs, allowing lazy-loading of image data without downloading the entire image upfront.

Where is the nydusctl source code located?

The nydusctl client source code is located at src/bin/nydusctl/main.rs in the Nydus repository. This binary implements the HTTP client that communicates with nydusd over its Unix-domain API socket (--apisock), handling commands like info for metrics and set for runtime configuration changes.

Can I use Nydus tools without containerd?

Yes, the Nydus toolchain operates independently of containerd. You can use nydus-image to build RAFS images and nydusd to mount them via FUSE on any Linux host for direct access or testing. nydusify can convert and push images to registries without requiring a container runtime. The nydus-overlayfs helper and snapshotter integration are only needed when using containerd or Kubernetes.

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