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
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.
MongoDB connection URI in Node; in the browser, the URL of a backend route that holds the connection URI.
Databases to mount; others are hidden. Unset or empty mounts every database except
admin, config and local.Most documents one
tail -n read of documents.jsonl fetches; a larger count on a collection that holds more is refused (File too large).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.Authentication
The user in the URI needs to read the databases the mount shows: the built-in Only read any database role on Atlas, orread on each database.
Layout
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_idorder, the indexes and the$jsonSchemavalidator 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_idorder:
Behavior
- Read-only: the mount only reads; no command changes the database.
- Streaming:
cat,grep,jqandheadread documents in batches, andheadstops after its count. Commands that need the whole input, such assortorjq -s, still buffer it, so read a large collection in bounded slices. - Read limit:
tail -nwith a count pastmaxDocLimiton a collection that long fails withFile too largerather than printing fewer lines. - Elided fields: fields under
elideFieldsare dropped fromdocuments.jsonl, forcatandtail -falike, and keep their type inschema.json. Nested paths use dots, such asmetadata.embedding. - File size:
documents.jsonlis rendered on demand, sostatandls -lshow-for its size andducounts0.wc -cmeasures the bytes andwc -lcounts the documents; both may scan the collection. A nonemptyls -lprintstotal ?. - Following inserts:
tail -fprints 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 browserMongoDBVFS 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.grepandrgon one file: a filter on the server sends only the documents that may match.grep -ron a folder does the same for eachdocuments.jsonlunder 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.
_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>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Read
database.jsonfirst, andschema.jsonbefore a largedocuments.jsonl. - Sizes show as
-;wc -candwc -lcount on demand and may scan the collection.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.