GridFS

The GridFS VFS mounts a MongoDB GridFS bucket at some prefix such as /gridfs/. Files are stored inside MongoDB itself: metadata in the <bucket>.files collection, content in 255KB chunks in <bucket>.chunks. Uses pymongo’s native async API. Install the extra:

pip install "mirage-ai[gridfs]"

Config

from mirage import MountMode, Workspace
from mirage.vfs.gridfs import GridFSVFS, GridFSConfig

config = GridFSConfig(
    uri="mongodb://localhost:27017",
    database="app",
    # Optional:
    # bucket="fs",  # GridFS bucket name (default "fs")
    # key_prefix="users/alice",  # scope the mount to a subpath
    # chunk_size_bytes=261120,  # default 255KB
)

vfs = GridFSVFS(config)
ws = Workspace({"/gridfs": vfs}, mode=MountMode.WRITE)

Both READ and WRITE modes are supported. Small files are fine: a file smaller than the chunk size is stored as a single chunk document, so tiny config files and large binaries go through the same path.

Filesystem Layout

GridFS filenames are used as slash-separated keys, exactly like S3 object keys. Directories are prefix-based; mkdir creates a zero-byte key/ marker document so empty directories stay visible.

data/file.txt
data/config.json
reports/q1.csv

mounted at /gridfs/ exposes:

/gridfs/
  data/
    file.txt
    config.json
  reports/
    q1.csv

Revisions

GridFS filenames are not unique: every write uploads a new revision and keeps the old ones. The VFS always reads and lists the newest revision per filename, and snapshot-pinned reads resolve old revisions by their file _id, so time-travel reads work natively. mv retags every revision’s filename server-side (history moves with the file), while rm deletes all revisions of the file.

Server-side find

Unlike object stores that page through every key, GridFS metadata lives in an ordinary MongoDB collection, so a find that can only print files (-type f) pushes its filters into the fs.files query itself:

-name / -iname globs become anchored regexes on the filename
-type f drops the directory markers
-size bounds map to the stored length

find /gridfs/ -type f -name '*.csv' -size +1M narrows inside MongoDB and only matching metadata comes back, so find stays cheap even on large buckets. Without -type f the filters run on the results instead: a directory that exists only because files sit under it has no document of its own, so a narrowed query would lose it. Semantics are identical to every other backend: the shared predicate evaluation still runs on the results.

Cache

The GridFS VFS uses IndexCacheStore with index_ttl = 600 (10 minutes). Directory listings are cached before being refreshed from MongoDB, reducing queries for repeated traversals.

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.gridfs import GridFSVFS, GridFSConfig

config = GridFSConfig(
    uri="mongodb://localhost:27017",
    database="app",
    bucket="assets",
)

vfs = GridFSVFS(config)


async def main() -> None:
    ws = Workspace({"/gridfs/": vfs}, mode=MountMode.WRITE)

    await ws.shell("echo hello | tee /gridfs/notes/a.txt > /dev/null")

    r = await ws.shell("ls /gridfs/")
    print(await r.stdout_str())

    r = await ws.shell("cat /gridfs/notes/a.txt")
    print(await r.stdout_str())

    r = await ws.shell("find /gridfs/ -name '*.txt'")
    print(await r.stdout_str())

    r = await ws.shell("grep hello /gridfs/notes/a.txt")
    print(await r.stdout_str())

    r = await ws.shell("stat /gridfs/notes/a.txt")
    print(await r.stdout_str())


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

Shell Commands

The GridFS VFS supports the same full command surface as the S3 VFS: read commands (cat, head, tail, grep, rg, jq, wc, stat, find, tree, du, checksums), text processing (awk, sed, sort, cut, diff, …), file operations (cp, mv, rm, mkdir, touch, tee, split, …), compression, and encoding. Range reads (head -c, tail -c) seek chunk-wise, so large files are never downloaded whole.

Scoping a VFS to a key prefix

Pass key_prefix to GridFSConfig to transparently scope every operation to a subpath of the bucket, mirroring the S3 key_prefix behavior:

GridFSVFS(GridFSConfig(
    uri="mongodb://localhost:27017",
    database="app",
    bucket="shared",
    key_prefix=f"users/{user_id}/",
))

Agents see clean paths like /data/notes.md; the underlying GridFS filename is users/{user_id}/data/notes.md. Leading slashes are stripped and a trailing slash is added automatically; None and an empty string mean “no prefix.”

Use Cases

Files next to your data: keep agent-visible files in the same MongoDB deployment as the rest of your application state, with one backup story
Revision-aware storage: writes never destroy old content; snapshots can pin reads to the exact revision they saw
Cheap find on big buckets: metadata queries replace full listings
Multi-tenant mounts: one bucket, per-tenant key_prefix scoping

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Config

Filesystem Layout

Revisions

Server-side find

Cache

Example

Shell Commands

Scoping a VFS to a key prefix

Use Cases

​Config

​Filesystem Layout

​Revisions

​Server-side find

​Cache

​Example

​Shell Commands

​Scoping a VFS to a key prefix

​Use Cases

Config

Filesystem Layout

Revisions

Server-side find

Cache

Example

Shell Commands

Scoping a VFS to a key prefix

Use Cases