Virtual Filesystems for LLM Agents

A virtual filesystem for LLM agents is a layer that exposes a database (or any structured data store) through a familiar UNIX filesystem interface — ls, cat, grep, find, cd. The agent issues shell commands; the virtual filesystem translates them into database queries. No actual files exist on disk.

This pattern emerged as a response to two problems with giving agents access to real filesystems:

1. Performance. Cloning repos or mounting real storage is slow and expensive. Mintlify saw ~46-second session creation times with sandboxed repos, dropping to ~100ms with their virtual filesystem (ChromaFs).

2. Safety. Real filesystems are mutable and hard to permission correctly. A virtual filesystem can be made read-only by default (returning EROFS on writes), and access control becomes a metadata filter applied before the agent sees the file tree — unauthorized paths simply don't exist from the agent's perspective.

The pattern also enables optimizations that are awkward with real files. Grep can use database-level filtering (e.g., Chroma's $contains operator) as a coarse first pass before running regex in memory. File content can be lazily loaded — large files appear in directory listings but only fetch on access. Caching is straightforward since the data is read-only.

The tradeoff is fidelity. A virtual filesystem only supports the commands its authors implemented. Complex shell pipelines, file watching, symlinks, or anything beyond the supported command set won't work. For documentation browsing this is fine; for general-purpose code execution it would be too limiting.

This approach is related to the broader problem of RAG limitations — it's one answer to the question of how agents should access large document collections when chunk-based retrieval isn't enough.