The composefs project combines several underlying Linux features to provide a very flexible mechanism to support read-only mountable filesystem trees, stacking on top of an underlying "lower" Linux filesystem.
This repository is the primary reference implementation of composefs, written in Rust. It replaces the previous C-based implementation; for background on this transition, see this discussion.
The key technologies composefs uses are:
composefs does not store any persistent data itself.
The underlying metadata and data files must be stored in a valid
"lower" Linux filesystem — usually a traditional writable persistent
filesystem such as ext4, xfs, or btrfs.
The tagline — "The reliability of disk images, the flexibility of files" — captures the core design philosophy. Disk images have desirable properties: they're efficiently kernel-mountable and explicit about layout, and tools like dm-verity provide robust security. But disk images commonly duplicate storage, are difficult to update incrementally, and are generally inflexible.
composefs provides a similarly high level of reliability, security, and Linux kernel integration, but with the flexibility of files for content — avoiding doubled disk usage, partition table management, and similar headaches.
composefs separates metadata (directories, permissions, xattrs) from data (file content). An EROFS image carries only the metadata; data files live in a content-addressed backing store, shared across images and in the Linux page cache. Optional fs-verity provides end-to-end integrity verification of both data and metadata. For design details, see the crate documentation.
composefs improves on the traditional per-layer overlayfs model for OCI container images by storing file content in a content-addressed store, enabling sharing between images and faster pulls via zstd:chunked.
composefs aims to succeed OSTree by replacing hardlink checkouts with directly-mountable images backed by a shared object store. Combined with fs-verity and a digest embedded in the kernel commandline or a UKI, this provides cryptographic verification of the entire filesystem tree. See this tracking issue for background.
composefs: Core library for composefs operations including filesystem trees,
fs-verity support, and repository managementcomposefs-oci: OCI image handling and integration with container registriescomposefs-boot: Boot infrastructure support including UKI (Unified Kernel Image)
and BLS (Boot Loader Specification) integrationcomposefs-http: HTTP support for fetching composefs contentcomposefs-fuse: FUSE filesystem implementationcfsctl: Primary CLI tool for managing composefs repositoriescomposefs-setup-root: Early boot tool for setting up
the root filesystem from a composefs imageThe examples directory contains working demonstrations of building verified OS images:
Images stored in a composefs repository can be mounted using cfsctl:
cfsctl mount <image-name> /mnt
The image can be identified by its fs-verity digest or by a ref/<name> reference.
The C implementation (composefs-c) provides a mount.composefs
helper that supports mount -t composefs syntax directly.
This project is under active development. The repository layout and on-disk formats may still change.
composefs is a Cloud Native Computing Foundation (CNCF) Sandbox project and adheres to the CNCF Community Code of Conduct.
See GOVERNANCE.md for how the project is run, MAINTAINERS.md for the current maintainers, and SECURITY.md for how to report a vulnerability.
The C implementation
provides mkcomposefs and mount.composefs and is still packaged in
many distributions. The Go containers/storage
library also has integration with mkcomposefs. These tools continue to
work, but new feature development is happening here.
See LICENSE for details.
Copyright contributors to composefs, established as composefs a Series of LF Projects, LLC.
921 followers · starred Nov 2024
61 followers · starred Oct 2025
82 followers · starred Nov 2025
81 followers · starred Sep 2026
The composefs project combines several underlying Linux features to provide a very flexible mechanism to support read-only mountable filesystem trees, stacking on top of an underlying "lower" Linux filesystem.
This repository is the primary reference implementation of composefs, written in Rust. It replaces the previous C-based implementation; for background on this transition, see this discussion.
The key technologies composefs uses are:
composefs does not store any persistent data itself.
The underlying metadata and data files must be stored in a valid
"lower" Linux filesystem — usually a traditional writable persistent
filesystem such as ext4, xfs, or btrfs.
The tagline — "The reliability of disk images, the flexibility of files" — captures the core design philosophy. Disk images have desirable properties: they're efficiently kernel-mountable and explicit about layout, and tools like dm-verity provide robust security. But disk images commonly duplicate storage, are difficult to update incrementally, and are generally inflexible.
composefs provides a similarly high level of reliability, security, and Linux kernel integration, but with the flexibility of files for content — avoiding doubled disk usage, partition table management, and similar headaches.
composefs separates metadata (directories, permissions, xattrs) from data (file content). An EROFS image carries only the metadata; data files live in a content-addressed backing store, shared across images and in the Linux page cache. Optional fs-verity provides end-to-end integrity verification of both data and metadata. For design details, see the crate documentation.
composefs improves on the traditional per-layer overlayfs model for OCI container images by storing file content in a content-addressed store, enabling sharing between images and faster pulls via zstd:chunked.
composefs aims to succeed OSTree by replacing hardlink checkouts with directly-mountable images backed by a shared object store. Combined with fs-verity and a digest embedded in the kernel commandline or a UKI, this provides cryptographic verification of the entire filesystem tree. See this tracking issue for background.
composefs: Core library for composefs operations including filesystem trees,
fs-verity support, and repository managementcomposefs-oci: OCI image handling and integration with container registriescomposefs-boot: Boot infrastructure support including UKI (Unified Kernel Image)
and BLS (Boot Loader Specification) integrationcomposefs-http: HTTP support for fetching composefs contentcomposefs-fuse: FUSE filesystem implementationcfsctl: Primary CLI tool for managing composefs repositoriescomposefs-setup-root: Early boot tool for setting up
the root filesystem from a composefs imageThe examples directory contains working demonstrations of building verified OS images:
Images stored in a composefs repository can be mounted using cfsctl:
cfsctl mount <image-name> /mnt
The image can be identified by its fs-verity digest or by a ref/<name> reference.
The C implementation (composefs-c) provides a mount.composefs
helper that supports mount -t composefs syntax directly.
This project is under active development. The repository layout and on-disk formats may still change.
composefs is a Cloud Native Computing Foundation (CNCF) Sandbox project and adheres to the CNCF Community Code of Conduct.
See GOVERNANCE.md for how the project is run, MAINTAINERS.md for the current maintainers, and SECURITY.md for how to report a vulnerability.
The C implementation
provides mkcomposefs and mount.composefs and is still packaged in
many distributions. The Go containers/storage
library also has integration with mkcomposefs. These tools continue to
work, but new feature development is happening here.
See LICENSE for details.
Copyright contributors to composefs, established as composefs a Series of LF Projects, LLC.
921 followers · starred Nov 2024
61 followers · starred Oct 2025
82 followers · starred Nov 2025
81 followers · starred Sep 2026