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.

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.
`database` required	Database that holds the GridFS bucket.
`bucket` default `'fs'`	GridFS bucket name; its collections are `<bucket>.files` and `<bucket>.chunks`.
`key_prefix`	Filename prefix the mount treats as its root; files outside it are not listed.
`chunk_size_bytes`	Chunk size in bytes for files the mount writes; unset uses the driver’s default, 255 KiB.
`keep_revisions`	Revisions kept per file, newest first: a write or an `rm` deletes the rest, under the file’s name and in the trash `rm` moves revisions to (`/trash/<filename>`, which no mount path reaches). Unset keeps every revision, so a snapshot pinned to any of them still reads.

Fields marked secret are redacted in snapshots.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`gridfs`, write

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>`	Almost all Unix commands.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	`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>` | `gridfs`, write |

## 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>` | Almost all Unix commands. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `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.

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). rm destroys nothing: it retags every revision of the file into the trash, /trash/<filename>, the same way mv does. A mount key never starts with a slash, so no path on any mount, whatever its key_prefix, can list, stat or read a trashed revision, and the name reads as gone; a snapshot pinned to one of those revisions still stats and reads it by its _id. A file mv overwrites goes to the trash the same way. The trash keeps the whole original filename, so a revision is traceable to the key it was written under. keep_revisions bounds the history. Set it, and a write or an rm deletes the revisions past that count per filename, oldest first, under the file’s name and under its trash name alike; a snapshot pinned to a pruned revision then fails to read it. Unset, the default, keeps every revision.

GridFSConfig(uri=..., database="app", keep_revisions=5)

Walks

GridFS metadata lives in an ordinary MongoDB collection, so a walk (find, du, ls -R, tree, grep -r, rg, cp -r) reads every file under the start directory with one fs.files query and answers each directory below it from that answer. See Walks.

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. A configured index: replaces this lifetime with its own ttl, and the mount’s ttl: caps it.

Integration

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

Command	On GridFS
`find`, `du`, `ls -R`, `tree`	One recursive listing

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

Runtimes

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Revisions

Walks

Cache

Integration

Example

Shell Commands

Scoping a VFS to a key prefix

Use Cases

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Revisions

​Walks

​Cache

​Integration

​Example

​Shell Commands

​Scoping a VFS to a key prefix

​Use Cases

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Revisions

Walks

Cache

Integration

Example

Shell Commands

Scoping a VFS to a key prefix

Use Cases