DifyVFS mounts a Dify Knowledge dataset, read-only, as a tree of text files.
Each document is one file, assembled from its segments. Set up the API key and the dataset as in Dify setup.
Install
Configure
slug_metadata_name picks the document metadata field that holds each path
(default slug). max_concurrency, retry_attempts and retry_max_delay
bound the requests in flight and the retries after a 429, a 5xx or a
transport error.
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.
Document metadata field whose value is the document’s path in the mount. A document without it is mounted under its document name.
Attempts per request, the first included. A 429, a 5xx or a transport error is retried.
Authentication
The mount sends a Dify Knowledge API key, created under Knowledge, Service API. The key reaches either every knowledge base or only the one mounted, and that knowledge base keeps API Access on.Layout
slug metadata field; without one, the
file takes the document name.
/makes folders. No empty segment,.or...- Each slug is unique across the dataset.
- A slug is never also a folder:
guidesandguides/quickstart.mdcannot both be documents. - Only enabled, fully indexed, unarchived documents appear.
Behavior
- Read-only: no command changes the dataset.
- Plain text: a file is its completed, enabled segments joined by line breaks, whatever the original format.
- Tree refresh: listings are reused until the index expires, so a document edited in Dify can show its old path and metadata until then.
- Snapshots: a snapshot keeps the config, and loading it needs the mount
handed back through
mounts=.
Search
Thesearch CLI asks Dify’s dataset retrieval API.
Register it on the workspace:
--method takes semantic (the default), fulltext, hybrid or keyword.
--top-k defaults to 10 and is capped at 100. --threshold is between 0 and
1; another value, or another method, exits 1 before Dify ranks anything. Each
hit prints its path and score, then the segment, and two hits in one document
stay two records:
document_name for a document without a slug. That filter needs Built-in
Fields turned on in the dataset’s metadata settings. Without it, a scoped
search on name-based files may return nothing while ls, find, cat and
grep still see them, so a slug on every document is the reliable choice.
VFS.md
The VFS.md an agent reads with Dify mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Every file is plain text assembled from the document’s Dify segments, whatever its original extension.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.