> ## 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

> Virtualize a MongoDB GridFS bucket from Node.

`GridFSVFS` mounts a MongoDB GridFS bucket: every file in the bucket becomes a
file and every `/` in a filename a folder. Metadata lives in the
`<bucket>.files` collection and content in `<bucket>.chunks`. Set up the connection URI as in [GridFS setup](https://docs.mirage.strukto.ai/home/setup/gridfs.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node mongodb
```

## Configure

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

const gridfs = new GridFSVFS({
  uri: process.env.MONGODB_URI!,
  database: 'app',
})
const ws = new Workspace({ '/gridfs': gridfs }, { mode: MountMode.WRITE })

const result = await ws.shell("echo hello > /gridfs/notes/a.txt && find /gridfs -name '*.txt'")
console.log(result.stdoutText)
await ws.close()
```

The `mongodb` peer package loads only when a `GridFSVFS` is built. `bucket`
names a bucket other than `fs`, `keyPrefix` scopes the mount to part of it, and
`keepRevisions` bounds the history each file keeps. A mount takes
`MountMode.READ`, `WRITE` or `EXEC`.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

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** `string` *required*

MongoDB connection URI.

**database** `string` *required*

Database that holds the GridFS bucket.

**bucket** `string` (default: 'fs')

GridFS bucket name; its collections are `<bucket>.files` and `<bucket>.chunks`.

**keyPrefix** `string`

Filename prefix the mount treats as its root; files outside it are not listed.

**chunkSizeBytes** `number`

Chunk size in bytes for files the mount writes; unset uses the driver's default, 255 KiB.

**keepRevisions** `number`

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.

## Authentication

The user in the URI needs `readWrite` on the database that holds the bucket,
or `read` for a `read` mount. On Atlas, the built-in **Read and write to any
database** role also works.

## Layout

```text theme={null}
/gridfs/
  data/
    config.json
    file.txt
  reports/
    q1.csv
```

`/gridfs/data/file.txt` is the GridFS filename `data/file.txt`. Folders come
from the `/` in filenames; `mkdir` stores a zero-byte `data/` marker so an
empty folder stays visible.

## Behavior

* **Key prefix:** `keyPrefix: 'users/42/'` mounts only that part of the bucket,
  so `/gridfs/data/notes.md` is the filename `users/42/data/notes.md`. A
  leading `/` is dropped and a trailing `/` added; an empty prefix means none.
* **Range reads:** `head -c` and `tail -c` seek by chunk, so a large file is
  never downloaded whole. A file smaller than the chunk size is one chunk.
* **Trash:** `rm`, and a file `mv` overwrites, retag every revision to
  `/trash/<filename>`. No mount path reaches the trash, so the name reads as
  gone, and the full original filename stays traceable.

### Revisions

GridFS filenames are not unique: every write uploads a new revision and keeps
the old ones. Reads and listings serve the newest revision per filename, and a
snapshot-pinned read resolves an older revision by its `_id`. `mv` retags every
revision's filename on the server, so history moves with the file.

`keepRevisions` 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
in the trash alike; a snapshot pinned to a pruned revision then fails to read
it. Unset keeps every revision.

## Browser

GridFS needs a direct MongoDB connection, so `GridFSVFS` ships in
`@struktoai/mirage-node` only. A browser workspace reaches GridFS through a
Node-side Mirage server instead.

## Integration

GridFS answers these commands through its own API, so fewer files are read.
See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `find`: one recursive listing.
* `du`: one recursive listing.
* `ls -R` and `tree`: one recursive listing.
* `grep -r`, `rg` and `cp -r`: one `fs.files` query for the whole tree; see
  [Walks](https://docs.mirage.strukto.ai/home/integration/walks.md).

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with GridFS mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **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.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## 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.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.