Postgres

PostgresVFS connects to Postgres via a DSN and exposes its schemas and tables as a tree. Setup steps for the DSN and required permissions live at Postgres Credentials.

Node

pnpm add @struktoai/mirage-node pg

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

const pg = new PostgresVFS({
  dsn: process.env.DATABASE_URL!,
  schemas: ['public', 'analytics'],
})

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

Browser

pnpm add @struktoai/mirage-browser

The default browser driver uses Neon’s HTTP transport. Replace the connection string below with one for a read-only demo role on Neon. Browser users can inspect this credential. Keep private database credentials in a Node backend.

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

const pg = new PostgresVFS({
  dsn: 'postgresql://mirage_reader:password@your-endpoint.neon.tech/app?sslmode=require',
  schemas: ['public'],
})
const ws = new Workspace({ '/pg': pg }, { mode: MountMode.READ })

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

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.
`dsn` required, secret	Postgres connection string. The default browser driver connects over Neon’s HTTP transport, so a browser mount needs a Neon connection string.
`schemas`	Schemas to show in the tree; others are hidden. Unset shows every schema except `pg_catalog`, `information_schema` and `pg_*`.
`defaultRowLimit` default `1000`	Rows a windowed read returns when it passes an offset but no limit, and the rows one page of a streamed `rows.jsonl` fetches.
`maxReadRows` default `10000`	Most rows one read returns. A whole read past it is refused, and so is a `head -n` / `tail -n` count past it on a table that long (`File too large`); `wc -l` counts past it.
`maxReadBytes` default `10485760` (10 MiB)	Most bytes of `rows.jsonl` one read returns; a whole read past it is refused (`File too large`).

Fields marked secret are redacted in snapshots.

Mount mode

read only. Postgres mounts are read-only at the VFS level.

Snapshot behavior

The DSN is redacted on snapshot. Hand the mount back at load (the third argument of Workspace.load, or a config over the server and CLI).

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<path>
  database.json          # cross-schema graph and sizes
  <schema>/              # a Postgres schema (namespace)
    tables/<table>/
      schema.json        # column types, PK/FK, indexes
      semantic.json      # descriptions, roles, sample values
      rows.jsonl         # data (size-guarded)
    views/<view>/
      schema.json
      semantic.json
      rows.jsonl

Read database.json first to plan joins.
Read semantic.json to learn what a table means: it splits columns into dimensions (group by), time_dimensions and facts (aggregate), and carries COMMENTs, enum domains and example values.
Reading rows.jsonl is refused for a table above the configured row or byte threshold. Use head, tail or wc, which ask SQL for only what they need, or grep, which fetches only the matching rows when SQL can find every match.

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 `postgres` for the matching lines. `head`, `tail` and `wc -l` ask `postgres` 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>` | `postgres`, read |

## VFS Layout

### `/<path>`

```text
/<path>
  database.json          # cross-schema graph and sizes
  <schema>/              # a Postgres schema (namespace)
    tables/<table>/
      schema.json        # column types, PK/FK, indexes
      semantic.json      # descriptions, roles, sample values
      rows.jsonl         # data (size-guarded)
    views/<view>/
      schema.json
      semantic.json
      rows.jsonl
```

- Read `database.json` first to plan joins.
- Read `semantic.json` to learn what a table means: it splits columns
  into dimensions (group by), time_dimensions and facts (aggregate), and
  carries COMMENTs, enum domains and example values.
- Reading `rows.jsonl` is refused for a table above the configured row
  or byte threshold. Use `head`, `tail` or `wc`, which ask SQL for only
  what they need, or `grep`, which fetches only the matching rows when
  SQL can find every match.

## 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 `postgres` for the matching lines. `head`, `tail` and `wc -l` ask `postgres` 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 PostgreSQL answers through its own API, so fewer files are read. Integration explains each command.

Command	On PostgreSQL
`grep`, `rg` on one file	`LIKE` (`ILIKE` for `-i`) fetches only the rows that may match
`head -n N`	`LIMIT N`
`tail -n N`	The last N rows by one query
`wc -l`	`COUNT(*)`
`tail -f`	Polls for rows past the last key, on a table with a primary key

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

Snapshot behavior

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​Snapshot behavior

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

Snapshot behavior

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration