Qdrant

QdrantVFS exposes a Qdrant collection as a read-only filesystem: group-by payload fields become nested folders, each point is a .json payload file (plus a .txt text file and an optional blob), and semantic search is the search CLI. The TypeScript backend mirrors the Python one and returns identical results.

Install

The client is browser-safe, so the VFS ships in core and is available from both the Node and browser packages:

pnpm add @struktoai/mirage-node @qdrant/js-client-rest

import { QdrantVFS, MountMode, Workspace } from "@struktoai/mirage-node";

const fashion = new QdrantVFS({
  config: {
    url: "https://xyz.cloud.qdrant.io",
    apiKey: process.env.QDRANT_API_KEY,
    collection: "fashion",
    groupBy: ["gender", "articleType", "baseColour"],
    idField: "id",
    textField: "productDisplayName",
    blobField: "image_b64",
    blobExt: "jpg",
    searchLimit: 5,
  },
});

const ws = new Workspace({ "/fashion/": fashion }, { mode: MountMode.READ });

await ws.shell("ls /fashion/Men/Shoes/White");

This first setup supports filesystem browsing. Configure query embedding in Search embedding and register the search CLI with ws.registerCli('search', SEARCH) before running search.

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.
`url`	Full URL of the Qdrant server, such as a Qdrant Cloud cluster URL; when set, `host`, `port` and `https` are ignored.
`host` default `'localhost'`	Host name of the Qdrant server when `url` is unset.
`port` default `6333`	Port of the Qdrant server when `url` is unset.
`https` default `false`	Connect to `host` over HTTPS when `url` is unset.
`apiKey` secret	Qdrant API key, required by Qdrant Cloud.
`collection`	Collection the mount root shows; unset lists every collection as a top-level folder.
`groupBy` default `[]`	Payload fields that become folder levels, one per field in order; dotted paths reach nested keys. Unset puts every point’s files directly under the collection.
`basenameFields` default `[]`	`groupBy` fields whose folder names keep only the last path or URL segment of the value; two values with one basename under the same parent are refused as a collision.
`idField` default `'id'`	Key the point id is written under in a point’s `.json`; it replaces a payload field of that name.
`nameField`	Payload field whose value prefixes each point’s file stem as `<name>__<id>`; unset names files by point id alone.
`textField`	Payload field served as the point’s `.txt` file and printed by `search`; unset leaves no `.txt`, and `search` returns the `.json`.
`blobField`	Payload field of raw or base64 bytes served as `<id>.<blobExt>` and left out of the `.json`; unset adds no blob file.
`blobExt` default `'bin'`	File extension of the blob file, without the dot.
`vectorField`	Payload field holding a copy of the vector, left out of the `.json`.
`searchLimit` default `10`	Results `search` returns when `--top-k` is not given.
`maxRows` default `1000`	Most points one folder listing scrolls; points past it are left out, and a group folder lists only the values those points carry.
`embeddingModel` default `'sentence-transformers/all-MiniLM-L6-v2'`	Model the server embeds a `search` query with under `cloudInference`; it must match the model the stored vectors came from.
`cloudInference` default `false`	Send the `search` query text to the server to embed, which needs a cluster with inference enabled (Qdrant Cloud). `embed` takes precedence; with neither, `search` refuses the query.
`embed` secret	Async function that turns a `search` query into a vector in-process, `(text: string) => Promise<number[]>`.

Fields marked secret are redacted in snapshots.

Document and chunk lineage

Config fields accept Qdrant’s dotted nested-key syntax. A LangChain-style payload with page_content and metadata: { source, page } can therefore use:

const docs = new QdrantVFS({
  config: {
    collection: "company_docs",
    groupBy: ["metadata.source"],
    basenameFields: ["metadata.source"],
    nameField: "metadata.page",
    textField: "page_content",
  },
});

For a source value s3://docs/policies/refund-2026.pdf and page value 004, the chunk text is exposed as refund-2026.pdf/004__<point-id>.txt. The point id remains as a stable suffix, so duplicate labels cannot collide and direct reads work without a warm cache. Only the stem the listing publishes opens: another label in front of the same id reads as absent. A label that is not a string spells as compact JSON (true, 1, 1e-7), the same in TypeScript and Python. basenameFields strips URL/path parents from the named groupBy fields; omit a field to preserve its complete value in one path-safe segment: / renders as ∕, and a blank or dot-led value is led by ⁄, so every value has its own segment that lists and opens. A basename longer than 255 bytes, which ext4 and APFS refuse, is cut to fit and ends in __ plus the md5 of the whole name, so two long leaves stay two directories. Basenames must be unique within a parent group; ambiguous listings are refused, and opening a basename directory checks every point of its parent group, so a second source past maxRows is refused rather than hidden.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

A Qdrant vector database, exposed as a filesystem.
At the root each directory is a collection, unless config pins a single collection.
Inside a collection, directories are the configured group-by payload fields; descending one narrows a filter.
Each matching point appears as files named by its Qdrant point id: <id>.json (the full payload), <id>.txt (the embedded source text) when a text field is configured, and <id>.<ext> (raw blob bytes) when a blob field is configured. The embedding vector is never shown.
ls, cd, cat, tree, find, wc, grep and rg work 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 `qdrant` 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. `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>` | `qdrant`, read |

## VFS Layout

### `/<path>`

- A Qdrant vector database, exposed as a filesystem.
- At the root each directory is a collection, unless config pins a
  single collection.
- Inside a collection, directories are the configured group-by payload
  fields; descending one narrows a filter.
- Each matching point appears as files named by its Qdrant point id:
  `<id>.json` (the full payload), `<id>.txt` (the embedded source text)
  when a text field is configured, and `<id>.<ext>` (raw blob bytes)
  when a blob field is configured. The embedding vector is never shown.
- `ls`, `cd`, `cat`, `tree`, `find`, `wc`, `grep` and `rg` work 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 `qdrant` 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. `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>.json  # full payload (metadata)
/fashion/<gender>/<articleType>/<baseColour>/<id>.txt   # embedded source text
/fashion/<gender>/<articleType>/<baseColour>/<id>.jpg   # raw blob bytes

<id> is the Qdrant point id. With nameField, leaf stems use <name>__<id>. Semantic search is the search command, not a path: it returns ranked points as the canonical .txt (or .json) paths above, annotated with the similarity score.

Search embedding

search needs a vector for the query, and the config decides where it comes from. With embed set, a (text: string) => Promise<number[]> the caller brings, the query is vectorized in-process, so a self-hosted Qdrant works and mirage depends on no model runtime; examples/typescript/vfs/qdrant/qdrant_vfs.ts feeds it a dependency-free hashed bag of words, and any model that returns a vector plugs in the same way. Without it, cloudInference: true sends the query text to the server, so the cluster must have inference enabled (Qdrant Cloud) and store vectors from the same embeddingModel (default sentence-transformers/all-MiniLM-L6-v2). With neither, search refuses the query. The hook never lands in a snapshot: a restored mount asks for a fresh VFS. Browsing (ls/cat/find/grep) needs no embedding.

Integration

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

Command	On Qdrant
`grep -r`, `rg`	The payload text the listing keeps, for ASCII text. It misses nothing.

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

Supported commands

ls, cd, tree, cat, stat, find, wc, head and tail. grep/rg stay lexical; the search CLI’s search "<query>" <path> is the semantic path, returning ranked points as canonical <id>.txt (or <id>.json) paths plus a score, so results compose with cat, wc, and pipes. Flags: --top-k, --threshold, --method semantic. Folder listings filter on payload fields. A filtered listing scrolls first and only creates keyword payload indexes for the groupBy fields if Qdrant reports one is required. maxRows caps how many points are scanned per folder.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes