Skip to main content
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

A self-hosted Qdrant sets host and port (default localhost:6333) instead of url. blob_field and blob_ext serve a payload field of raw or base64 bytes as a file, such as 3.jpg.

Fields

float
default:"30"
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.
str
Full URL of the Qdrant server, such as a Qdrant Cloud cluster URL; when set, host, port and https are ignored.
str
default:"'localhost'"
Host name of the Qdrant server when url is unset.
int
default:"6333"
Port of the Qdrant server when url is unset.
bool
default:"False"
Connect to host over HTTPS when url is unset.
str
secret
Qdrant API key, required by Qdrant Cloud.
str
Collection the mount root shows; unset lists every collection as a top-level folder.
list[str]
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.
list[str]
default:"[]"
group_by 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.
str
default:"'id'"
Key the point id is written under in a point’s .json; it replaces a payload field of that name.
str
Payload field whose value prefixes each point’s file stem as <name>__<id>; unset names files by point id alone.
str
Payload field served as the point’s .txt file and printed by search; unset leaves no .txt, and search returns the .json.
str
Payload field of raw or base64 bytes served as <id>.<blob_ext> and left out of the .json; unset adds no blob file.
str
default:"'bin'"
File extension of the blob file, without the dot.
str
Payload field holding a copy of the vector, left out of the .json.
int
default:"10"
Results search returns when --top-k is not given.
int
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.
str
default:"'sentence-transformers/all-MiniLM-L6-v2'"
Model the server embeds a search query with under cloud_inference; it must match the model the stored vectors came from.
bool
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.
callable
secret
Async function that turns a search query into a vector in-process, (text: str) -> list[float].
Fields marked secret are redacted in snapshots.

Authentication

A self-hosted Qdrant needs no key. Qdrant Cloud needs api_key; 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 group_by 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

Each folder level filters on one group_by field, in order. Once every field is bound, the folder lists each point’s files, named by point id, or <name>__<id> with name_field. 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>.txt is the text_field value, the text the vector was built from.
  • <id>.json is the full payload as compact JSON, without the vector and the blob.
  • <id>.<blob_ext> is the raw bytes of blob_field, when it is set.

Behavior

  • Read-only: no command changes the collection.
  • Nested fields: fields take Qdrant’s dotted keys. For LangChain-style chunks, group_by=["metadata.source"], basename_fields=["metadata.source"], name_field="metadata.page" and text_field="page_content" show page 004 of s3://docs/policies/refund-2026.pdf as refund-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: basename_fields keeps 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 past max_rows is 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 max_rows (1,000) points; points past it are left out. Keep group_by to low-cardinality fields on a large collection.
The search CLI runs Qdrant’s vector query. Register it on the workspace:
Each hit prints the point’s .txt path, or its .json without text_field, with the similarity score, then the content:
--top-k defaults to search_limit (10). --threshold is the lowest score kept. --method takes only semantic. The query needs a vector. embed, an async (text: str) -> list[float], builds it in-process, so a self-hosted Qdrant works with any model. Without it, cloud_inference=True sends the query text to the cluster, which must have inference enabled (Qdrant Cloud) and store vectors from the same embedding_model. With neither, search refuses the query. embed never lands in a snapshot, so a restored mount needs a fresh QdrantVFS.

Integration

Qdrant answers this command through its own API, so fewer files are read. See Integration.
  • grep -r and rg: one scroll per folder, as a listing does, picks the .json and .txt files 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 .json or .txt over 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>.
Virtual FilesystemVFS 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.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.