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

> Explore Nydus tools like nydusd, nydus-image, and nydusify. Learn how these components streamline container image management and performance for your cloud-native applications.

- Repository: [dragonflyoss/nydus](https://github.com/dragonflyoss/nydus)
- Tags: getting-started
- Published: 2026-02-28

---

**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`](https://github.com/dragonflyoss/nydus/blob/main/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:

```bash
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`](https://github.com/dragonflyoss/nydus/blob/main/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:

```bash
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:

```bash
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`](https://github.com/dragonflyoss/nydus/blob/main/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:

```bash
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:

```toml
[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`](https://github.com/dragonflyoss/nydus/blob/main/src/bin/nydusd/main.rs), handling runtime access and caching.
- **`nydus-image`** builds and manipulates RAFS filesystems from [`src/bin/nydus-image/main.rs`](https://github.com/dragonflyoss/nydus/blob/main/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`](https://github.com/dragonflyoss/nydus/blob/main/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`](https://github.com/dragonflyoss/nydus/blob/main/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`](https://github.com/dragonflyoss/nydus/blob/main/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`](https://github.com/dragonflyoss/nydus/blob/main/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.