MongoDB

MongoDBVFS exposes databases containing collections/ and views/ directories. Each collection or view contains schema.json and documents.jsonl. Setup steps for the connection URI live at MongoDB Credentials.

Node

pnpm add @struktoai/mirage-node mongodb

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

const mongo = new MongoDBVFS({
  uri: process.env.MONGODB_URI!,
  databases: ['app', 'analytics'],
})

const ws = new Workspace({ '/mongo': mongo }, { mode: MountMode.READ })
try {
  const result = await ws.shell('ls /mongo/app/collections/users/')
  console.log(result.stdoutText)
} finally {
  await ws.close()
}

Browser

pnpm add @struktoai/mirage-browser

The browser VFS sends HTTP requests to a backend route, which keeps the MongoDB connection URI on the server. This example expects /api/mongo on the same origin. The repository’s Vite middleware supports the database listing below for local development.

import { MongoDBVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const mongo = new MongoDBVFS({ uri: '/api/mongo' })
const ws = new Workspace({ '/mongo': mongo }, { mode: MountMode.READ })

try {
  const result = await ws.shell('ls /mongo/')
  console.log(result.stdoutText)
} finally {
  await ws.close()
}

The development proxy does not yet support document streaming or schema reads.

Config

Field	Description
`timeout` 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` required, secret	MongoDB connection URI in Node; in the browser, the URL of a backend route that holds the connection URI.
`databases`	Databases to mount; others are hidden. Unset or empty mounts every database except `admin`, `config` and `local`.
`maxDocLimit` default `5000`	Most documents one `tail -n` read of `documents.jsonl` fetches; a larger count on a collection that holds more is refused (`File too large`).
`elideFields` default `{}`	Fields dropped from `documents.jsonl`, keyed by `<database>.<collection>` (a view’s name works too); a dotted path such as `nested.path` drops a nested field.

Fields marked secret are redacted in snapshots.

Mount mode

read. For the database/collection/document layout see the Python MongoDB docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`mongodb`, read

VFS Layout

`/<path>`

/<path>
  <database>/
    database.json              # collection and view names
    collections/<collection>/
      schema.json              # sampled field types, validator, indexes
      documents.jsonl          # streamed BSON Extended JSON documents
    views/<view>/
      schema.json
      documents.jsonl

Read database.json first to discover entities, and schema.json before reading a large document stream.
head, tail, wc, grep, rg and jq understand documents.jsonl; grep and rg fetch only the documents that may match.
An unknown size displays as -; wc -c measures bytes and wc -l counts documents on demand. These counts may scan the collection.

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>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `mongodb` for the matching lines. `tail` and `wc -l` ask `mongodb` instead of reading a file.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `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>` | `mongodb`, read |

## VFS Layout

### `/<path>`

```text
/<path>
  <database>/
    database.json              # collection and view names
    collections/<collection>/
      schema.json              # sampled field types, validator, indexes
      documents.jsonl          # streamed BSON Extended JSON documents
    views/<view>/
      schema.json
      documents.jsonl
```

- Read `database.json` first to discover entities, and `schema.json`
  before reading a large document stream.
- `head`, `tail`, `wc`, `grep`, `rg` and `jq` understand
  `documents.jsonl`; `grep` and `rg` fetch only the documents that may
  match.
- An unknown size displays as `-`; `wc -c` measures bytes and `wc -l`
  counts documents on demand. These counts may scan the collection.

## 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>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `mongodb` for the matching lines. `tail` and `wc -l` ask `mongodb` instead of reading a file. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `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.

Integration

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

Command	On MongoDB
`grep`, `rg` on one file	A filter on the server sends only the documents that may match
`tail -n N`	The last N documents by `_id`
`wc -l`	`countDocuments()` on the server
`tail -f`	A change stream yields each new insert

The Python MongoDB docs list when each search answers and what it can miss.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration