GridFS

GridFSVFS mounts a MongoDB GridFS bucket (file metadata in <bucket>.files, content chunks in <bucket>.chunks) as a read-write filesystem. Files are keyed by slash-separated filenames, writes keep old revisions, and a walk (find, du, ls -R, tree, grep -r) reads the whole subtree with one fs.files query (Walks). Setup steps for the connection URI live at GridFS Credentials.

Node

pnpm add @struktoai/mirage-node mongodb

import { GridFSVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const gridfs = new GridFSVFS({
  uri: process.env.MONGODB_URI!,
  database: 'app',
  bucket: 'assets', // default "fs"
})

const ws = new Workspace({ '/gridfs/': gridfs }, { mode: MountMode.WRITE })
await ws.shell('echo hello | tee /gridfs/notes/a.txt > /dev/null')
const res = await ws.shell("find /gridfs/ -name '*.txt'")
console.log(res.stdoutText)

The mongodb driver is an optional peer dependency; it is only loaded when a GridFSVFS is constructed.

Scoping to a key prefix

const scoped = new GridFSVFS({
  uri: process.env.MONGODB_URI!,
  database: 'app',
  bucket: 'shared',
  keyPrefix: `users/${userId}`,
})

Every operation is transparently scoped to that subpath: agents see /data/notes.md, the stored filename is users/<id>/data/notes.md. YAML configs may spell it key_prefix; both are accepted.

Browser

GridFS requires a direct MongoDB connection, so GridFSVFS ships in @struktoai/mirage-node only. Browser workspaces can reach GridFS content through a Node-side MIRAGE server instead.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Scoping to a key prefix

Browser

​Node

​Scoping to a key prefix

​Browser

Node

Scoping to a key prefix

Browser