MongoDB

The MongoDB VFS exposes MongoDB databases, collections, and documents as a virtual filesystem mounted at some prefix such as /mongodb/. For connection setup, see MongoDB Setup. Install the extra:

pip install "mirage-ai[mongodb]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.mongodb import MongoDBConfig, MongoDBVFS

config = MongoDBConfig(
    uri=os.environ["MONGODB_URI"],
    max_doc_limit=5000,
    elide_fields={"sample_mflix.movies": ["plot_embedding"]},
)
vfs = MongoDBVFS(config=config)
ws = Workspace({"/mongodb": vfs}, mode=MountMode.READ)

Field	Description
`timeout` default `30`	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.
`uri` required, secret	MongoDB connection URI.
`databases`	Databases to mount; others are hidden. Unset or empty mounts every database except `admin`, `config` and `local`.
`max_doc_limit` 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`).
`elide_fields` 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.

VFS.md

The VFS.md an agent reads with MongoDB mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`mongodb`, read

`/<path>` layout

/<path>
  <database>/
    database.json                  collection and view names
    collections/<collection>/
      schema.json                  sampled field types, validator, indexes
      documents.jsonl              streamed BSON Extended JSON documents
    views/<view>/
      schema.json
      documents.jsonl
  Read database.json first to discover entities. Use schema.json before
  reading large document streams; head, tail, wc, grep, rg, and jq understand
  documents.jsonl; grep and rg fetch only the documents that may match.
  Unknown stat sizes display as -; wc -c measures bytes and wc -l counts
  documents on demand. These counts may scan the collection.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `mongodb` for the matching lines. `tail` and `wc -l` ask `mongodb` instead of reading a file.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `mongodb`, read |

## `/<path>` layout

```text
/<path>
  <database>/
    database.json                  collection and view names
    collections/<collection>/
      schema.json                  sampled field types, validator, indexes
      documents.jsonl              streamed BSON Extended JSON documents
    views/<view>/
      schema.json
      documents.jsonl
  Read database.json first to discover entities. Use schema.json before
  reading large document streams; head, tail, wc, grep, rg, and jq understand
  documents.jsonl; grep and rg fetch only the documents that may match.
  Unknown stat sizes display as -; wc -c measures bytes and wc -l counts
  documents on demand. These counts may scan the collection.
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `mongodb` for the matching lines. `tail` and `wc -l` ask `mongodb` instead of reading a file. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

The mount mirrors MongoDB’s cluster → database → collection / view model. The database directory always appears in the path, even when databases filters to a single entry.

/mongodb/
  <database>/
    database.json                  # collection and view names
    collections/
      <collection>/
        schema.json                # sampled types + indexes + validator
        documents.jsonl            # streamed BSON Extended JSON
    views/
      <view>/
        schema.json                # view-aware (no indexes / validator)
        documents.jsonl            # streamed, same format as collections

Example:

/mongodb/
  sample_mflix/
    database.json
    collections/
      movies/
        schema.json
        documents.jsonl
      comments/
        schema.json
        documents.jsonl
    views/
      top_rated_movies/
        schema.json
        documents.jsonl

Discovery lists databases, collections, views, and their fixed file names. It does not enumerate one filesystem entry per document. Schema inspection is separate from bulk document reads, so discovering a collection does not require exporting it. These paths and read contracts are shared by Python and TypeScript.

documents.jsonl

One JSON object per line, encoded with BSON Relaxed Extended JSON. BSON-specific types round-trip through their canonical $ wrappers:

{"_id":{"$oid":"573a1390f29313caabcd4135"},"title":"Casablanca","released":{"$date":"1943-01-23T00:00:00Z"},"runtime":102}

cat / head / tail / grep / jq can read this file through the same streaming interface. The cursor fetches documents in batches; head can stop after a prefix. Commands that need the whole input, such as sort or jq -s, can still buffer it. Use bounded reads when exploring a large collection. Because the file is rendered on demand, stat / ls -l report no size and du returns 0 for it (computing the real size would require rendering the whole collection). Use wc -c documents.jsonl for the actual rendered byte count, or wc -l documents.jsonl for an exact document count (which can scan the collection). stat -c %s prints - for an unknown size and 0 only for a known empty file. Missing dates also display as -. Long directory listings include a total row. GNU ls reports allocated disk blocks there; the VFS does not expose allocation metadata, so Mirage prints total ? for nonempty listings and total 0 for empty listings. This is an intentional divergence from GNU output, not a sum of rendered file sizes. stat checks existence and type without counting documents, sampling fields, or fetching indexes. This keeps ls, find, and opening a stream independent of the collection size. The same unknown-size convention applies to Postgres row exports and other rendered VFS files.

schema.json

Generated from the first 100 documents in _id order. Includes:

field path → observed BSON type frequencies (nested paths unioned across the sample)
index definitions from listIndexes, without volatile access counters
the $jsonSchema validator if one is registered

Repeated reads of unchanged data produce identical bytes. Schema reads do not include document counts or $indexStats, so reading a schema cannot change its own content. Views skip indexes.

database.json

Lists collection and view names using two catalog listings, without a per-collection count. Useful for cat /mongodb/<db>/database.json to get an overview without recursing into each entity.

Elided fields

Fields listed under elide_fields are dropped entirely from documents.jsonl output. The type stays documented in schema.json, so heavy fields (embeddings, large binary, raw text blobs) can be hidden from agent reads without losing the schema signal:

config = MongoDBConfig(
    uri=os.environ["MONGODB_URI"],
    elide_fields={
        "sample_mflix.movies": ["plot_embedding"],
        "rag.docs": ["metadata.embedding"],
    },
)

Nested paths use dot notation. Elision applies to both cat (one-shot streaming reads) and tail -f (live change-stream follows).

Streaming and Limits

cat, grep, head, and tail -f consume documents lazily through a batched PyMongo async cursor (or change stream); the consumer cancels to stop fetching. Direct output is capped at 2,000 lines by default, with a truncation notice on stderr. Pipes and redirects bypass this output cap. See command output limits to change the bound.

Command	Behavior
`cat`	Streams the collection sorted by `_id`; direct output uses the command limit above
`head -n K`	Streams from `_id` order and stops after K documents
`tail -n K`	Server-side sort + limit; a K past `max_doc_limit` on a collection that long is `File too large`
`tail -f`	Prints the last lines, then opens a change stream and yields each new insert as a JSONL line
`grep` (file level)	Streams from `documents.jsonl`; supports `-m` for short-circuit
`grep -r` (collection/db level)	Every file under the directory; MongoDB sends only the documents that may match
`jq`	Inherits the streaming `cat` source
`wc -l`	Uses `countDocuments()` server-side; zero download
`stat`	Existence and type only; no counts or index queries

Smart Commands

grep and rg

For one plain text in a collection’s or view’s documents.jsonl, grep and rg ask MongoDB for the documents that may hold it, in the _id order a plain read takes, and search their lines instead of the whole collection. The filter matches the text in any case against every key and string of a document, eight levels deep; a document nested deeper, or holding a value it 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.

grep "Godfather" "/mongodb/sample_mflix/collections/movies/documents.jsonl"
grep -r "Godfather" "/mongodb/sample_mflix/"

head / tail / tail -f

tail uses server-side sort + limit. A count past max_doc_limit on a collection that long is refused with File too large rather than printing fewer lines than asked. head streams in _id order and stops after the count. tail -f on a collection reads the last lines at one snapshot, then opens a Mongo change stream of the inserts after it and yields each new document as a JSONL line in the same format as cat; on a view it polls. See Lines:

# First 10 docs (sorted by _id ascending)
head -n 10 "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# Last 10 docs (sorted by _id descending)
tail -n 10 "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# Live-follow new inserts; consumer cancels to stop
tail -f "/mongodb/sample_mflix/collections/movies/documents.jsonl"

tail -f follows inserts on a replica set on MongoDB 5.0 or later, for the snapshot read and the change stream; Atlas already satisfies this. On a server outside a replica set it polls, and so does a view, which has no change stream.

Cache

The MongoDB VFS lists database names, collection names, and document counts. These listings are not cached by default (index_ttl = 0); a workspace or mount index: caches them for its ttl. Document content is not cached. The VFS leaves caches_reads at its default of False, so cat, grep, head, and tail always query the live collection instead of serving a stored snapshot. This keeps reads consistent with a mutable database and ensures tail -f follows the live change stream rather than replaying cached bytes.

Integration

What MongoDB answers through its own API, so fewer files are read. Integration explains each command.

Command	On MongoDB
`grep`, `rg` on one file	A filter on the server sends only the documents that may match
`tail -n N`	The last N documents by `_id`
`wc -l`	`countDocuments()` on the server
`tail -f`	A change stream yields each new insert

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.mongodb import MongoDBConfig, MongoDBVFS

load_dotenv(".env.development")

config = MongoDBConfig(uri=os.environ["MONGODB_URI"])
vfs = MongoDBVFS(config=config)


async def main():
    ws = Workspace({"/mongodb": vfs}, mode=MountMode.READ)

    # List all databases
    r = await ws.shell("ls /mongodb/")
    print(await r.stdout_str())

    # List the entities under a database (database.json, collections/, views/)
    r = await ws.shell("ls /mongodb/sample_mflix/")
    print(await r.stdout_str())

    # List collections
    r = await ws.shell("ls /mongodb/sample_mflix/collections/")
    print(await r.stdout_str())

    # Read first 5 movies
    r = await ws.shell(
        'head -n 5 "/mongodb/sample_mflix/collections/movies/documents.jsonl"')
    print(await r.stdout_str())

    # Read last 5 movies
    r = await ws.shell(
        'tail -n 5 "/mongodb/sample_mflix/collections/movies/documents.jsonl"')
    print(await r.stdout_str())

    # Inspect the sampled schema and indexes
    r = await ws.shell(
        'cat "/mongodb/sample_mflix/collections/movies/schema.json"')
    print(await r.stdout_str())

    # Extract titles with jq
    r = await ws.shell(
        'jq -r ".title" "/mongodb/sample_mflix/collections/movies/documents.jsonl"'
    )
    print(await r.stdout_str())

    # Search across a database
    r = await ws.shell('grep -r "Godfather" "/mongodb/sample_mflix/"')
    print(await r.stdout_str())

    # Count documents (server-side, no download)
    r = await ws.shell(
        'wc -l "/mongodb/sample_mflix/collections/movies/documents.jsonl"')
    print(await r.stdout_str())

    # View the database overview without recursing
    r = await ws.shell('cat "/mongodb/sample_mflix/database.json"')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

Runnable examples

Three working examples live under examples/python/vfs/mongodb/:

mongodb.py — agent-shell workflow: ls, tree, cat, head, tail, wc, stat, grep/rg at every scope, jq, find, cd + relative paths.
mongodb_vfs.py — in-process VFS: os.listdir and open() walk every readdir level (root, database, collections/, views/, entity) and read database.json, schema.json, documents.jsonl (collection + view).
mongodb_fuse.py — same coverage as the VFS example, but the tree is mounted as a real filesystem so other processes can cat/ls/head the mountpoint directly.

All three default to the mirage_test database seeded by scripts/seed_mongodb_test.py.

Finding IDs

_id is serialized as {"$oid": "..."} under Extended JSON:

# List the first 10 ObjectId values
jq -r '._id["$oid"]' \
  "/mongodb/sample_mflix/collections/movies/documents.jsonl" | head -n 10

# Find a specific document by ID
grep "573a1390f29313caabcd42e8" \
  "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# Extract a few fields together
jq -r '"\(._id["$oid"]) \(.title) \(.year)"' \
  "/mongodb/sample_mflix/collections/movies/documents.jsonl"

Working with Large Collections

Streaming is the default; reach for these patterns when you want to keep the round trip small:

# Document count (server-side, no download)
wc -l "/mongodb/sample_mflix/collections/comments/documents.jsonl"

# Most recent documents (sorted by _id desc)
tail -n 10 "/mongodb/sample_mflix/collections/comments/documents.jsonl"

# MongoDB sends only the comments that may hold the word
grep -r "love" "/mongodb/sample_mflix/collections/comments/"

# Drop heavy fields via elide_fields, then take the slice you want
head -n 20 "/mongodb/sample_mflix/collections/movies/documents.jsonl"

Hide embeddings or large blobs from agent reads with elide_fields; schema.json still documents the original type so the agent can decide when to ask for the raw bytes through a different path.

Shell Commands

Standard commands available on the mounted MongoDB tree:

Command	Notes
`ls`	List databases, collections, views, and per-entity files
`cat`	Stream `documents.jsonl` (or read `schema.json` / `database.json`)
`head` / `tail`	`head` streams and stops early; `tail` sorts and limits server-side, up to `max_doc_limit`
`tail -f`	Live-follow new inserts via Mongo change stream
`grep` / `rg`	A directory operand searches every file under it (documents, schema.json, database.json, views); a file streams
`jq`	Query JSON; runs once per line of a JSONL file (`-s` for all)
`wc`	Smart: `-l` uses `countDocuments()` server-side
`stat`	Existence and type only; no counts or index queries
`find`	List databases/collections/views with `-name`, `-maxdepth`
`tree`	Directory tree view

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

documents.jsonl

schema.json

database.json

Elided fields

Streaming and Limits

Smart Commands

grep and rg

head / tail / tail -f

Cache

Integration

Example

Runnable examples

Finding IDs

Working with Large Collections

Shell Commands

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​documents.jsonl

​schema.json

​database.json

​Elided fields

​Streaming and Limits

​Smart Commands

​grep and rg

​head / tail / tail -f

​Cache

​Integration

​Example

​Runnable examples

​Finding IDs

​Working with Large Collections

​Shell Commands

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

documents.jsonl

schema.json

database.json

Elided fields

Streaming and Limits

Smart Commands

grep and rg

head / tail / tail -f

Cache

Integration

Example

Runnable examples

Finding IDs

Working with Large Collections

Shell Commands