LanceDB

LanceDBVFS exposes a LanceDB table as a read-only filesystem: group-by columns become nested folders, each row is a card plus an optional blob file, and semantic search is the search CLI. The TypeScript backend mirrors the Python one and returns identical results.

Node

pnpm add @struktoai/mirage-node @lancedb/lancedb

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

const fashion = new LanceDBVFS({
  config: {
    uri: '/data/fashion.lancedb', // or s3://, gs://, db:// (LanceDB Cloud)
    table: 'fashion',
    groupBy: ['gender', 'articleType', 'baseColour'],
    idColumn: 'id',
    titleColumn: 'productDisplayName',
    blobColumn: 'image_bytes',
    blobExt: 'jpg',
    vectorColumn: 'vector',
    searchLimit: 5,
  },
})

const ws = new Workspace({ '/fashion/': fashion }, { mode: MountMode.READ })
ws.registerCli('search', SEARCH)

await ws.shell('ls /fashion/Men/Shoes/White')
await ws.shell('search "red running shoes" /fashion')

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	Database location: a local directory, an `s3://`, `gs://` or `az://` URI, or a `db://` URI for LanceDB Cloud or Enterprise.
`apiKey` secret	API key for LanceDB Cloud or Enterprise.
`region` default `'us-east-1'`	LanceDB Cloud region of a `db://` database; ignored for other URIs.
`hostOverride`	Endpoint of a LanceDB Enterprise deployment for a `db://` URI; ignored for other URIs.
`storageOptions`	Options passed to LanceDB’s object-store layer, such as credentials or an endpoint for an `s3://` URI.
`table`	Table the mount root shows; unset lists every table as a top-level folder.
`groupBy` default `[]`	Columns that become folder levels, one per column in order; unset puts every row’s files directly under the table.
`idColumn` default `'id'`	Column whose value names each row’s files (`<id>.md`, `<id>.<blobExt>`).
`titleColumn`	Column whose value heads a row’s card as a `#` title; unset leaves the card without one.
`blobColumn`	Column of raw or base64 bytes served as `<id>.<blobExt>` and left out of the card; unset adds no blob file.
`blobExt` default `'bin'`	File extension of the blob file, without the dot.
`vectorColumn`	Embedding column left out of cards and listings.
`searchLimit` default `10`	Results `search` returns when `--top-k` is not given.
`maxRows` default `1000`	Most rows one folder listing reads; rows past it are left out, and a group folder lists only the values those rows carry.

Fields marked secret are redacted in snapshots.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

`/<path>` layout

This mount is a LanceDB table exposed as a filesystem.

Directories are the configured group-by columns; descending narrows a filter.
Each matching row is a <id>.md card plus a <id>.<ext> blob file. Use
ls/cd/cat/tree/find/wc/grep/rg as usual.

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 -r` and `rg` ask `lancedb` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `lancedb` answers only for `/.md`; `grep -r` and `rg` read every other file. `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>` | `lancedb`, read |

## `/<path>` layout

```text
This mount is a LanceDB table exposed as a filesystem.

Directories are the configured group-by columns; descending narrows a filter.
Each matching row is a <id>.md card plus a <id>.<ext> blob file. Use
ls/cd/cat/tree/find/wc/grep/rg as usual.
```

## 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 -r` and `rg` ask `lancedb` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `lancedb` answers only for `*/*.md`; `grep -r` and `rg` read every other file. `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.

/fashion/<gender>/<articleType>/<baseColour>/<id>.md   # row card
/fashion/<gender>/<articleType>/<baseColour>/<id>.jpg  # raw blob bytes

A groupBy value holding / renders as ∕, and a blank or dot-led value is led by ⁄, so every value keeps its own directory that lists and opens, and descending into it filters for exactly that value. Semantic search is the search command, not a path: it returns ranked rows as the canonical <id>.md paths above, annotated with the vector distance.

Cloud and Enterprise

db:// URIs connect to LanceDB Cloud (apiKey + region) or Enterprise (apiKey + hostOverride):

const fashion = new LanceDBVFS({
  config: {
    uri: 'db://my-database',
    apiKey: process.env.LANCEDB_API_KEY,
    region: 'us-east-1',
    hostOverride: 'https://my-database.us-east-1.api.lancedb.com', // Enterprise only
    table: 'fashion',
    groupBy: ['gender'],
    idColumn: 'id',
    vectorColumn: 'vector',
  },
})

Integration

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

Command	On LanceDB
`grep -r`, `rg`	The string columns of each row, for any text; a table with list, struct or bytes columns reads every card. It misses nothing.

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

Supported commands

ls, cd, tree, cat, stat, find and wc. grep/rg stay lexical; the search CLI’s search "<query>" <path> is the semantic path, returning ranked rows as canonical <id>.md paths plus a score, so results compose with cat, wc, and pipes. Flags: --top-k, --threshold, --method semantic. Search requires a table built with an embedding function on a source field, so tbl.search(text) auto-embeds the query. The Node example under examples/typescript/vfs/lancedb/ builds such a table and produces the same output as the Python example, including identical similarity scores (0.2679).

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cloud and Enterprise

Integration

Supported commands

​Node

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Cloud and Enterprise

​Integration

​Supported commands

Node

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cloud and Enterprise

Integration

Supported commands