A Virtual Filesystem Layer for cloud storages for the free desktop
  • C++ 90.7%
  • CMake 9.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-09 14:01:57 +01:00
.github CI: Sync with opencloud desktop 2026-11-09 14:01:57 +01:00
cmake Use standard repo layout 2026-03-03 09:45:53 +01:00
src Use enum class for HydJobState and some cleanups 2026-10-21 09:31:34 +02:00
.clang-format Apply clang format 2025-12-11 11:11:57 +01:00
.craft.ini CI: Sync with opencloud desktop 2026-11-09 14:01:57 +01:00
.craft.shelf CI: Sync with opencloud desktop 2026-11-09 14:01:57 +01:00
.gitignore Make compile on mac 2026-01-26 15:57:35 +01:00
CMakeLists.txt More modern implementation of join(), bump to C++ 23 standard 2026-09-29 09:40:37 +02:00
fod.drawio Improved README and added a bit more detailed documentation 2026-06-08 09:51:27 +02:00
fod.png Improved README and added a bit more detailed documentation 2026-06-08 09:51:27 +02:00
INTEGRATION.md Bound the hydration wait and close the open() registration race 2026-10-21 09:31:34 +02:00
LICENSE Apply the correct license 2026-03-03 09:54:51 +01:00
openvfs_overview.drawio Improved README and added a bit more detailed documentation 2026-06-08 09:51:27 +02:00
README.md Fix links in README 2026-07-07 11:54:08 +02:00

openVFS - Virtual File System for Cloud Storage

openVFS is a framework that provides files on demand for the free desktop. It is based on the FUSE filesystem layer.

Files on demand is a feature for files residing on a cloud storage system such as OpenCloud or Nextcloud. Rather than syncing all remote files locally, the files on demand system defers downloading file content until it is explicitly requested — for example, when a user opens a file. Until then, files are visible in the filesystem but their content is not present locally. Because most files occupy zero bytes on disk until accessed, the system is significantly more resource-efficient than a full sync.

The openVFS layer is based on Linux FUSE and is designed to work in conjunction with the cloud sync client.

It exposes a POSIX interface to user-space applications, proxying filesystem calls such as open() and readdir() and returning metadata that accurately represents the remote files.

To track synchronization state, openVFS uses the so-called pin state, which is stored in extended file attributes (xattrs) on each file.

When an application issues an open() call for a file whose content has not yet been downloaded, the FUSE layer initiates a download via the desktop client and blocks the call until the transfer completes. Download is delegated to the desktop client because the client holds all credentials required to authenticate against the server.


Note: This is experimental code. It builds on the work of Rémi Flament (remipouak at gmail.com), whose LoggedFS filesystem monitoring tool served as the initial foundation.

Contributions and discussion are welcome — feel free to open issues or pull requests.

Architecture

Architecture Overview of Files on Demand

Usage

In production, the openvfs FUSE layer is managed automatically by the desktop client, which handles mounting and unmounting without user intervention.

For debugging and investigation, the layer can be started manually, provided a desktop client is running and syncing the target directory.

A typical invocation:

openvfs -d -i <config-file> -o <owner-string> -s <socket-file> /path/to/synced/dir

To inspect the mount state, use mount | grep -e '^openvfs'. To unmount, use fusermount -d <mounted-dir>. Root access is not required.

Installation from source

Ensure that FUSE3 is installed on the system, including the development headers.

openVFS uses CMake as its build system. Refer to the CMake documentation for build instructions.

Integration

Details on integrating openVFS into a sync client are described in the integration document.

Contribute

The files on demand system was initially proposed by OpenCloud in April 2025 and is under consideration by the open-source cloud storage project Nextcloud.

Feedback is welcome. Start a discussion or open an issue on GitHub for bug reports and feature requests.