Windows Virtual File System Architecture: ProjFS, Cloud Filter API, and Driver Limits

The Windows Virtual File System architecture enables applications to project hierarchical file hierarchies dynamically using Windows Projected File System (ProjFS) or Cloud Files API without storing entire file payloads locally. While standard NTFS and ReFS file systems allocate physical storage clusters for every file stream on disk, modern virtualization frameworks intercept I/O requests inside the Windows NT kernel to project synthetic directory hierarchies. In the Win32 API, the standard maximum path length is MAX_PATH, defined as 260 characters, and kernel-mode file virtualization models must navigate this structural boundary while negotiating file hydration with user-mode providers.

A virtual file system decouples the logical directory tree presented to user-mode software from physical block storage. Unlike Unix-like operating systems where a Virtual File System (VFS) switch exists as a native kernel abstraction layer above concrete file systems, the Windows NT architecture relies on the File System Minifilter driver model (FltMgr.sys). In Windows, every file access request generates an I/O Request Packet (IRP) that traverses an ordered stack of minifilter drivers registered at designated altitude bands before reaching the underlying file system driver (ntfs.sys or fastfat.sys).

Historically, creating a virtual file system on Windows required engineering custom kernel-mode minifilter drivers or installing third-party bridging drivers such as Dokan or WinFsp (Windows File System Proxy). To provide standardized, secure, user-mode filesystem projection without requiring third-party kernel extensions, Microsoft developed two distinct native virtualization architectures documented in the Microsoft ProjFS documentation:

1. Windows Projected File System (ProjFS): Introduced in Windows 10 version 1809 and Windows Server 2019, ProjFS allows a user-mode application called a provider to project data into a local directory tree. Backed by the prjflt.sys kernel minifilter, ProjFS is engineered for high-speed local data stores such as massive Git repositories, localized build trees, and synthetic namespace projections.
2. Windows Cloud Filter API (Cloud Files API): Introduced in Windows 10 version 1709 and Windows Server 2016, the Cloud Filter API (cfapi.h and cldapi.dll) is backed by the cldflt.sys kernel minifilter. It is tailored for distributed cloud synchronization engines like Microsoft OneDrive, Box, and Dropbox, offering native Windows Shell integration, progressive hydration, and user-facing status indicators.

The following comparison details the technical differences between native Windows virtualization APIs and third-party user-mode drivers:

Early community implementations such as Phil McCarthy's WinVFS demonstrated how Windows services could wrap Dokan drivers in user-mode .NET code to expose remote web services and databases as virtual drive letters. While functional for specialized development environments, third-party drivers require kernel signing approval, custom installers, and administrative privileges. Microsoft's native ProjFS and Cloud Filter API eliminate third-party kernel driver installation by embedding certified minifilters directly into the Windows operating system.

• Linux Virtual File System (VFS): Architecture, Limits, and Agent Storage MountsThe Linux Virtual File System (VFS) abstracts diverse filesystems behind a unified POSIX interface using four core...
• File System Access API Limits: Browser Quotas, OPFS, and Large File HandlingThe File System Access API allows web applications to read or save changes directly to files and folders on the user's...
• Node.js Virtual File System: In-Memory VFS, Memfs, and Memory LimitsA Node.js virtual file system simulates filesystem calls in memory without writing to persistent disk. While tools like...
• Virtual File System in Python: In-Memory VFS, Limits, and Agent SandboxesA Python virtual file system creates an in-memory or abstracted storage layer within the process runtime, but heap...
• Rust Virtual File System Guide: VFS Crates, WASM Sandboxes, and LimitsA Rust virtual file system abstracts filesystem operations into traits, allowing applications to swap physical disk I/O...
• AWS Bedrock File Size Limits: Document Constraints in Knowledge Bases and Converse APIAWS Bedrock Knowledge Bases enforces a 50 MB per-document limit for file ingestion, while the Bedrock Converse API caps...

More on this subject: Agent File and Document Workflows (346 guides)

The Windows Projected File System allows a user-mode application called a provider to project hierarchical data from a backing data store into the file system, making it appear as files and directories in the file system. ProjFS operates as a high-performance broker between standard Win32 file system calls (CreateFileW, ReadFile, FindNextFileW) and the provider process.

Provider Registration and Callback Routing

A ProjFS provider converts an empty NTFS directory into a virtualization root using PrjMarkDirectoryAsPlaceholder. This operation writes a reparse point to the root directory, identifying it with the reparse tag IO_REPARSE_TAG_PROJFS. Once marked, the provider initializes its callback dispatch table (PRJ_CALLBACKS) and invokes PrjStartVirtualizing.

The provider implements callback routines to handle namespace discovery and content streaming:

• PRJ_START_DIR_ENUM_CB: Prepares internal state, creates directory search iterators, and allocates memory buffers when an application begins enumerating a projected directory.
• PRJ_GET_DIR_ENUM_CB: Emits directory entries to ProjFS. The provider formats each child file or folder metadata into a PRJ_FILE_BASIC_INFO struct.
• PRJ_END_DIR_ENUM_CB: Finalizes directory enumeration and releases allocated session memory.
• PRJ_GET_PLACEHOLDER_INFO_CB: Supplies metadata (file attributes, allocation size, creation and write timestamps) when an application requests information about a specific file path.
• PRJ_GET_FILE_DATA_CB: Streams file content. When an application reads a file, ProjFS intercepts the request, pauses the calling thread, and requests byte ranges from the provider via this callback.

The provider can also register for optional notifications through PRJ_NOTIFICATION_CB to track when files are opened, created, overwritten, renamed, or deleted.

The following C++ example demonstrates how a provider registers callbacks and starts virtualizing a designated root path:

#include <windows.h>
#include <projectedfslib.h>
#include <iostream>

PRJ_CALLBACKS callbacks = {};

HRESULT InitializeVirtualizationRoot(PCWSTR rootPath) {
    GUID virtualizationId;
    HRESULT hr = CoCreateGuid(&virtualizationId);
    if (FAILED(hr)) return hr;
    // Designate directory as a ProjFS virtualization root
    hr = PrjMarkDirectoryAsPlaceholder(rootPath, nullptr, nullptr, &virtualizationId);
    if (FAILED(hr)) {
        std::wcerr << L"Failed to mark directory: " << hr << std::endl;
        return hr;
    }
    // Configure core enumeration and data callbacks
    callbacks.StartDirEnumCallback = OnStartDirEnum;
    callbacks.GetDirEnumCallback = OnGetDirEnum;
    callbacks.EndDirEnumCallback = OnEndDirEnum;
    callbacks.GetPlaceholderInfoCallback = OnGetPlaceholderInfo;
    callbacks.GetFileDataCallback = OnGetFileData;
    PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT context;
    hr = PrjStartVirtualizing(rootPath, &callbacks, nullptr, nullptr, &context);
    if (FAILED(hr)) {
        std::wcerr << L"Failed to start virtualizing: " << hr << std::endl;
        return hr;
    }
    std::wcout << L"Virtualization active on: " << rootPath << std::endl;
    return S_OK;
}

The ProjFS File Lifecycle and State Machine

A file managed by ProjFS moves through five distinct lifecycle states on disk:

1. Virtual File: The file exists only in the provider's backing data store. It has zero byte footprint on local storage media. When an application lists directory contents, ProjFS injects the entry dynamically into the enumeration output.
2. Placeholder File: When an application opens a handle to a virtual file or inspects its attributes, ProjFS writes a lightweight placeholder to disk. The placeholder contains file metadata and an NTFS reparse point, but its data payload occupies 0 bytes on disk.
3. Hydrated Placeholder: When an application reads the file's data stream, ProjFS triggers PRJ_GET_FILE_DATA_CB. The provider supplies the file bytes using PrjWriteFileData. The file payload now occupies physical disk blocks, but the NTFS reparse point remains intact.
4. Full File (Dirty/Modified): If a local application writes to, appends, or truncates a placeholder, ProjFS converts it into a full file. The reparse point is stripped or marked dirty, decoupling the file from future provider updates. The file behaves as a standard local NTFS file.
5. Tombstone: If a user or process deletes a virtual file or placeholder locally, ProjFS creates a hidden tombstone entry. The tombstone prevents the item from reappearing in directory enumerations even if it continues to exist in the provider's backing data store.

While ProjFS assumes high-speed local data retrieval, the Windows Cloud Filter API (cfapi.h and cldapi.dll) is designed specifically for remote cloud storage synchronization. Cloud sync engines must handle high network latency, intermittent offline status, and partial data downloads while presenting a cohesive interface inside Windows File Explorer.

Sync Root Registration and Policies

A cloud storage provider establishes its presence on Windows by calling CfRegisterSyncRoot. This function registers an absolute directory path as a synchronization root and binds it to a CF_SYNC_REGISTRATION structure containing provider credentials and version data.

The provider defines operational rules through CF_SYNC_POLICIES:

• Hydration Policies (CF_HYDRATION_POLICY): Controls how file payloads transfer from cloud storage to local disk.
  • CF_HYDRATION_POLICY_PARTIAL: Permits applications to read specific byte ranges without downloading the entire file payload.
  • CF_HYDRATION_POLICY_PROGRESSIVE: Streams data sequentially while providing real-time percentage progress to the Windows shell.
  • CF_HYDRATION_POLICY_FULL: Enforces complete file payload download upon the first read handle request.
  • CF_HYDRATION_POLICY_ALWAYS_FULL: Ensures that once a file is hydrated, it cannot be automatically dehydrated by background storage optimization routines.
• Population Policies (CF_POPULATION_POLICY): Dictates directory tree discovery.
  • CF_POPULATION_POLICY_PARTIAL: Child placeholders generate on demand as users expand folders in File Explorer.
  • CF_POPULATION_POLICY_FULL: The complete directory hierarchy is populated locally before opening the folder to user operations.

Data Hydration via Opportunistic Locks and Callbacks

The Cloud Filter API uses Windows opportunistic locks (oplocks) to arbitrate access between user-mode applications, the Windows Cache Manager, and the cloud sync engine. When an unhydrated placeholder file is opened with read intent, the cldflt.sys driver breaks the placeholder oplock, halts the calling thread, and issues a CF_CALLBACK_TYPE_FETCH_DATA notification to the provider's message loop.

The provider downloads the required byte range from the cloud and satisfies the driver request using CfExecute:

#include <windows.h>
#include <cfapi.h>

void HandleFetchDataCallback(
    const CF_CALLBACK_INFO* callbackInfo,
    const CF_CALLBACK_PARAMETERS* callbackParameters
) {
    CF_OPERATION_INFO opInfo = {};
    opInfo.StructSize = sizeof(CF_OPERATION_INFO);
    opInfo.Type = CF_OPERATION_TYPE_TRANSFER_DATA;
    opInfo.ConnectionKey = callbackInfo->ConnectionKey;
    opInfo.TransferKey = callbackInfo->TransferKey;
    CF_OPERATION_PARAMETERS opParams = {};
    opParams.ParamSize = sizeof(CF_OPERATION_PARAMETERS);
    opParams.TransferData.Flags = CF_OPERATION_TRANSFER_DATA_FLAG_NONE;
    opParams.TransferData.CompletionStatus = STATUS_SUCCESS;
    opParams.TransferData.Buffer = downloadedDataBuffer;
    opParams.TransferData.Offset = callbackParameters->FetchData.RequiredFileOffset;
    opParams.TransferData.Length = callbackParameters->FetchData.RequiredLength;
    HRESULT hr = CfExecute(&opInfo, &opParams);
}

Through integration with the Windows Runtime Windows.Storage.Provider namespace, the Cloud Filter API surfaces native visual glyphs in Windows File Explorer: a blue cloud icon for online-only files, a green check circle for hydrated files, and a solid green badge for pinned files marked with CfSetPinState.

Access Large Document Corpora Without Virtual Filesystem Driver Overhead

Connect your AI agents and engineering workflows directly to persistent Fast.io workspaces via MCP. Index files automatically for semantic search and multi-agent collaboration with a 14-day free trial.

Start 14-Day Trial

Deploying a virtual file system on Windows introduces strict operational limits and kernel-level failure modes that do not exist in conventional local storage. System architects must account for path length restrictions, synchronous thread stalls, and file locking semantics when designing high-throughput automation pipelines.

The Win32 MAX_PATH 260-Character Barrier

Historically, the Win32 file subsystem defines MAX_PATH as 260 characters, as documented in the Microsoft path limitation reference. A standard fully qualified path is structured as a drive letter, a colon, a backslash, component strings separated by backslashes, and a terminating null character:

D:\subfolder\project_directory\target_file.txt<NUL>

When cloud file systems or enterprise repositories project deep directory hierarchies into a local synchronization root, paths routinely exceed 260 characters. When this ceiling is breached, Win32 APIs fail with ERROR_PATH_NOT_FOUND or ERROR_BUFFER_OVERFLOW.

To mitigate this constraint, Windows provides two mechanisms:

1. **The Extended-Length Path Prefix (\\?\):** Prepending \\?\ to an absolute path instructs the Win32 API to bypass path normalization and forward extended paths directly to the filesystem driver. However, this prefix does not resolve path limitations in third-party command line utilities or legacy graphical shells.
2. The LongPathsEnabled Registry Setting: Starting with Windows 10 version 1607 and Windows Server 2016, administrators can enable long path support across the operating system:
   • Registry Path: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
   • Value Name: LongPathsEnabled
   • Data Type: REG_DWORD
   • Enabled Value: 1

Even with LongPathsEnabled configured globally or set via Group Policy (Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths), individual applications must declare long path awareness in their application manifest:

<application xmlns="urn:schemas-microsoft-com:asm.v3">
  <windowsSettings>
    <longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
  </windowsSettings>
</application>

Legacy development tools, non-manifested compilers, and standard Windows shell components that allocate fixed MAX_PATH stack buffers continue to fail when encountering deep virtual file paths.

Kernel-to-User-Mode Latency and Thread Starvation

Both ProjFS (prjflt.sys) and the Cloud Filter API (cldflt.sys) rely on synchronous kernel callbacks into user-mode provider processes. When a local application requests file data, the calling thread is placed into a kernel wait state until the user-mode provider fulfills the read request.

This synchronous coupling introduces severe latency traps:

• Antivirus Interception: When Microsoft Defender or third-party endpoint detection software scans a directory containing virtual placeholders, it opens file handles sequentially. Each open triggers a hydration callback. If the provider relies on remote network transfers, antivirus scanners can trigger concurrent hydration calls, saturating network bandwidth and stalling system I/O.
• Search Indexer Exhaustion: The Windows Search Indexer (SearchIndexer.exe) crawls mounted file directories to index file properties. Without custom exclusion rules, indexers trigger complete file downloads, turning dynamic cloud projections into fully populated local directories.
• Thread Starvation: If the user-mode provider experiences an unhandled exception, network timeout, or memory deadlock, pending I/O requests inside the kernel minifilter remain blocked. Applications attempting to access the virtualization root freeze in a "Not Responding" state, requiring termination of the calling processes.

File Locking Semantics and Multi-Process Conflicts

Windows file systems enforce mandatory file sharing semantics through sharing modes (FILE_SHARE_READ, FILE_SHARE_WRITE, FILE_SHARE_DELETE). When an application opens an exclusive write handle to a hydrated placeholder, other processes attempting to read or inspect the file receive an immediate ERROR_SHARING_VIOLATION.

In automated pipelines and distributed development environments, local mandatory file locks cause race conditions. If an automated process locks a file for writing while the virtual file system provider attempts to update the placeholder's reparse point or metadata, the synchronization transaction aborts. Resolving these collisions requires complex retry loops and custom backoff algorithms inside user-mode provider code.

As software development shifts toward autonomous AI agents and automated coding pipelines, relying on local virtual file system drivers introduces fundamental architectural bottlenecks. AI agents like Claude Code, Cursor, Codex, and Gemini CLI operate by traversing extensive codebases, parsing thousands of documentation files, and executing automated test suites.

When an autonomous agent interacts with a repository mounted through ProjFS or Cloud Filter API, standard filesystem commands like grep, findstr, or AST parsers touch every file in the directory hierarchy. This triggers cascading hydration calls, downloading unneeded file payloads and exhausting local disk storage. Furthermore, agent platforms enforce strict operational ceilings. In assistant platforms such as Anthropic Claude, individual chats and projects enforce strict context window ceilings and attachment size caps. While small codebases fit into context buffers, enterprise corpora quickly breach context window boundaries.

Attempting to mount enterprise document repositories or shared codebases onto local Windows virtual drives creates brittle dependencies on local kernel drivers, path length configurations, and network-bound hydration queues.

Moving from Driver-Level Virtualization to Intelligent Cloud Workspaces

The modern alternative decouples file storage and indexing from local workstation operating systems. Instead of projecting raw files into local Windows directories, organizations maintain their document collections in intelligent workspaces built for agentic teams.

Fast.io provides a cloud workspace platform that replaces local virtual file system mounting with API and protocol-driven document access:

• Intelligence Mode and Semantic Indexing: When files are uploaded or imported into a Fast.io workspace, Intelligence Mode automatically indexes their contents for hybrid search (combining full-text lexical search and semantic search). Instead of downloading raw files through local filesystem drivers, agents query the workspace by meaning and retrieve precise text excerpts backed by document citations.
• Structured Data Extraction via Metadata Views: For teams managing high volumes of unstructured files, Metadata Views convert documents into queryable, typed databases. Metadata Views use AI to extract custom attributes (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time) across PDFs, Word documents, spreadsheets, and scanned records without requiring manual OCR templates or local file hydration.
• Consolidated Model Context Protocol (MCP) Server: Rather than mounting virtual drive letters, AI assistants connect directly to cloud storage for agents over Streamable HTTP. Assistants connect using https://mcp.fast.io/mcp/tools (for Claude and general AI clients) or https://mcp.fast.io/mcp/code (for coding agents like Claude Code, Cursor, and Gemini CLI). Agents execute semantic searches and file operations directly against the workspace, bypassing local disk constraints and path length limits. Setup instructions are documented in the Fast.io MCP setup guide.
• Multi-Cloud Synchronization: Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a Fast.io workspace, one-way or two-way, on a schedule or on demand. Teams consolidate disparate corporate document stores into a unified intelligence layer without running local sync daemons.
• Advisory File Leases and Version History: Rather than suffering from Windows mandatory lock conflicts (ERROR_SHARING_VIOLATION), Fast.io provides advisory per-file leases via MCP actions (lock-acquire, lock-release, lock-status). If two agents write to the same file concurrently, both writes land safely, and per-file version history preserves every revision for auditability in the detailed activity log.

Monthly Fast.io plans start with a 14-day free trial that requires a credit card. Review pricing options on the Fast.io pricing page. Plans include Starter at $9.99/mo (3 seats, 250 GB storage, 5 workspaces, 100,000 credits), Business at $49.99/mo (10 seats, 5 TB storage, 50 workspaces, 600,000 credits), and Enterprise at $199.99/mo (30 seats included, 25 TB storage, 200 workspaces, 3,000,000 credits). Credits meter AI work, and overage is billed at $10 per 100,000 credits.