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

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
required
secret
Dify Knowledge API key, sent as Authorization: Bearer.
str
required
Dify API root, such as https://api.dify.ai/v1.
str
required
ID of the Knowledge dataset the mount shows.
str
default:"'slug'"
Document metadata field whose value is the document’s path in the mount. A document without it is mounted under its document name.
int
default:"10"
The most Dify API requests in flight at once.
int
default:"4"
Attempts per request, the first included. A 429, a 5xx or a transport error is retried.
float
default:"30.0"
Longest wait in seconds before a retry, whether from backoff or Retry-After.
Fields marked secret are redacted in snapshots.

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

A document’s path is the value of its 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: guides and guides/quickstart.md cannot 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=.
The search 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:
A search under a path filters retrieval by the slug field, or by 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>.
Virtual FilesystemVFS Layout/<path>
  • Every file is plain text assembled from the document’s Dify segments, whatever its original extension.
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.