QdrantVFS mounts a Qdrant collection, read-only, as
nested folders, one level per group-by payload field. Each point is a .json
payload file, plus a .txt text file and an optional blob. Set up the cluster URL and API key as in Qdrant setup.
Install
Configure
host and port (default localhost:6333) instead
of url. blobField and blobExt serve a payload field of raw or base64
bytes as a file, such as 3.jpg.
Fields
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.
Full URL of the Qdrant server, such as a Qdrant Cloud cluster URL; when set,
host, port and https are ignored.Collection the mount root shows; unset lists every collection as a top-level folder.
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.
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.Key the point id is written under in a point’s
.json; it replaces a payload field of that name.Payload field whose value prefixes each point’s file stem as
<name>__<id>; unset names files by point id alone.Payload field served as the point’s
.txt file and printed by search; unset leaves no .txt, and search returns the .json.Payload field of raw or base64 bytes served as
<id>.<blobExt> and left out of the .json; unset adds no blob file.Most points one folder listing scrolls; points past it are left out, and a group folder lists only the values those points carry.
Model the server embeds a
search query with under cloudInference; it must match the model the stored vectors came from.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.Async function that turns a
search query into a vector in-process, (text: string) => Promise<number[]>.Authentication
A self-hosted Qdrant needs no key. Qdrant Cloud needsapiKey; a read-only
key, for the cluster or for the mounted collections, is enough to browse.
A filtered listing creates a keyword payload index for a groupBy field only
when Qdrant reports that one is required. A read-only key cannot create it, so
index those fields first or use a key that manages the collection.
Layout
groupBy field, in order. Once every field is
bound, the folder lists each point’s files, named by point id, or
<name>__<id> with nameField. Without collection, every collection is a
top-level folder. A value holding / renders as ∕, and a blank or dot-led
value is led by ⁄, so every value keeps its own folder that lists and opens.
<id>.txtis thetextFieldvalue, the text the vector was built from.<id>.jsonis the full payload as compact JSON, without the vector and the blob.<id>.<blobExt>is the raw bytes ofblobField, when it is set.
Behavior
- Read-only: no command changes the collection.
- Nested fields: fields take Qdrant’s dotted keys. For LangChain-style
chunks,
groupBy: ['metadata.source'],basenameFields: ['metadata.source'],nameField: 'metadata.page'andtextField: 'page_content'show page004ofs3://docs/policies/refund-2026.pdfasrefund-2026.pdf/004__<point-id>.txt. - File names: the point id stays in every name, so two equal labels never
collide. Only the name a listing shows opens: another label in front of the
same id reads as absent. A label that is not a string is written as compact
JSON (
true,1,1e-7). - Basenames:
basenameFieldskeeps only the last path or URL segment of a value. Two values with one basename under the same parent are refused rather than merged, and opening a basename folder checks every point of its parent, so a second source pastmaxRowsis refused rather than hidden. A name over 255 bytes is cut to fit and ends in__plus the md5 of the whole name. - Listing cap: one folder listing scrolls at most
maxRows(1,000) points; points past it are left out. KeepgroupByto low-cardinality fields on a large collection.
Semantic search
Thesearch CLI runs Qdrant’s vector query. Register
it on the workspace:
.txt path, or its .json without textField,
with the similarity score, then the content. --top-k defaults to
searchLimit (10). --threshold is the lowest score kept. --method takes
only semantic.
The query needs a vector. embed, a (text: string) => Promise<number[]>,
builds it in-process, so a self-hosted Qdrant works with any model. Without it,
cloudInference: true sends the query text to the cluster, which must have
inference enabled (Qdrant Cloud) and store vectors from the same
embeddingModel. With neither, search refuses the query. embed never lands
in a snapshot, so a restored mount needs a fresh QdrantVFS.
Browser
The sameQdrantVFS runs in the browser from @struktoai/mirage-browser.
- The page calls Qdrant directly, so the server must accept requests from the page’s origin.
- The API key is visible to anyone who loads the page: use a read-only key limited to the mounted collections.
Integration
Qdrant answers this command through its own API, so fewer files are read. See Integration.grep -randrg: one scroll per folder, as a listing does, picks the.jsonand.txtfiles whose text holds the pattern’s text in any case, for ASCII text, and misses nothing. A point changed since the last listing is still found. A blob, a.jsonor.txtover 8 KiB, and every file for a text that is not ASCII are read as usual.
VFS.md
The VFS.md an agent reads with Qdrant mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- At the root each directory is a collection, unless config pins one.
- Inside a collection, directories are the group-by payload fields; descending one narrows a filter.
- Each point is
<id>.json(its payload), plus<id>.txt(source text) and<id>.<ext>(blob bytes) when those fields are configured. The vector is never shown.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.