Skip to main content
MongoDBVFS turns MongoDB databases into a read-only tree: every collection and view is a folder holding its sampled schema and its documents as JSON lines. Set up the connection URI as in MongoDB setup.

Install

Configure

databases limits the tree to those databases. elideFields: { 'sample_mflix.movies': ['plot_embedding'] } drops heavy fields, such as embeddings, from what an agent reads.

Fields

number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
required
secret
MongoDB connection URI in Node; in the browser, the URL of a backend route that holds the connection URI.
string[]
default:"null"
Databases to mount; others are hidden. Unset or empty mounts every database except admin, config and local.
number
default:"5000"
Most documents one tail -n read of documents.jsonl fetches; a larger count on a collection that holds more is refused (File too large).
object
default:"{}"
Fields dropped from documents.jsonl, keyed by <database>.<collection> (a view’s name works too); a dotted path such as nested.path drops a nested field.
Fields marked secret are redacted in snapshots.

Authentication

The user in the URI needs to read the databases the mount shows: the built-in Only read any database role on Atlas, or read on each database.

Layout

The tree mirrors MongoDB’s cluster, database, collection and view. The database folder always appears, even when databases names one database. Listings show databases, collections, views and their fixed files, never one entry per document.
  • database.json: the collection and view names, without counts.
  • schema.json: field paths and the BSON types seen in the first 100 documents in _id order, the indexes and the $jsonSchema validator if one is set. Views have no indexes. Unchanged data reads as identical bytes.
  • documents.jsonl: one document per line in Relaxed Extended JSON, in _id order:

Behavior

  • Read-only: the mount only reads; no command changes the database.
  • Streaming: cat, grep, jq and head read documents in batches, and head stops after its count. Commands that need the whole input, such as sort or jq -s, still buffer it, so read a large collection in bounded slices.
  • Read limit: tail -n with a count past maxDocLimit on a collection that long fails with File too large rather than printing fewer lines.
  • Elided fields: fields under elideFields are dropped from documents.jsonl, for cat and tail -f alike, and keep their type in schema.json. Nested paths use dots, such as metadata.embedding.
  • File size: documents.jsonl is rendered on demand, so stat and ls -l show - for its size and du counts 0. wc -c measures the bytes and wc -l counts the documents; both may scan the collection. A nonempty ls -l prints total ?.
  • Following inserts: tail -f prints the last lines, then follows new inserts through a change stream. That needs a replica set on MongoDB 5.0 or later, which Atlas is; on a standalone server, and on a view, it polls.

Browser

The browser MongoDBVFS from @struktoai/mirage-browser sends HTTP requests to a backend route, which keeps the connection URI on the server. Its uri is that route.
  • The repository’s Vite middleware serves the database listing for local development. It does not yet serve document streams or schema reads.

Integration

MongoDB answers these commands through its own API, so fewer documents are read. See Integration.
  • grep and rg on one file: a filter on the server sends only the documents that may match. grep -r on a folder does the same for each documents.jsonl under it.
  • tail -n N: the last N documents by _id, sorted on the server.
  • wc -l: countDocuments() on the server.
  • tail -f: a change stream yields each new insert.
For one plain text, the filter matches it in any case against every key and string of a document, eight levels deep, in the _id order a plain read takes. A document nested deeper, or holding a value the filter cannot look into (binary, a regex, code), is always sent. MongoDB still scans the collection, but only those documents are sent. The file is read as usual when the text holds anything but ASCII letters and spaces, or could match an Extended JSON key ($oid, $date, $numberLong), a JSON literal (true, null) or an id (a word of hex letters only, such as ada). schema.json and database.json are always read, and -m stops the cursor early.

VFS.md

The VFS.md an agent reads with MongoDB mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • Read database.json first, and schema.json before a large documents.jsonl.
  • Sizes show as -; wc -c and wc -l count on demand and may scan the collection.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.