> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GridFS

> Mount a MongoDB GridFS bucket as a MIRAGE filesystem from Node.

`GridFSResource` 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 `find` pushes `-name`/`-type`/`-size` filters into the `fs.files` query server-side.

Setup steps for the connection URI live at [GridFS Credentials](/home/setup/gridfs).

## Node

```bash theme={null}
pnpm add @struktoai/mirage-node mongodb
```

```ts theme={null}
import { GridFSResource, MountMode, Workspace } from '@struktoai/mirage-node'

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

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

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

## Scoping to a key prefix

```ts theme={null}
const scoped = new GridFSResource({
  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 `GridFSResource` ships in `@struktoai/mirage-node` only. Browser workspaces can reach GridFS content through a Node-side MIRAGE server instead.