Skip to main content
A Dify Knowledge dataset becomes a tree of text files. Each document is one file, assembled from its segments.

Setup

The mount reads the Dify Knowledge Base API with a Knowledge API key:
  1. In Dify, open Knowledge, click Service API in the top right, then API Key, and create a key. Only workspace owners and admins can.
  2. Give the key access to all knowledge bases or to the one to mount. The scope cannot change later.
  3. Copy the Service API endpoint from the same panel: https://api.dify.ai/v1 on Dify Cloud, the instance’s own /v1 URL when self-hosted.
  4. Copy the dataset ID, the value after /datasets/ in the knowledge base URL.
  5. Keep API Access on for that knowledge base (it is on by default).
A document’s path is the value of its slug metadata field. Without one, the file takes the document name. slug_metadata_name picks another field, such as path.In the Knowledge UI, open each document and add a metadata item named slug. Documents uploaded through the API carry the same item in their metadata.
  • Forward slashes make folders; leading and trailing slashes are trimmed.
  • No empty segment, . or ...
  • Values stay unique: two documents with one slug fail as a duplicate path.
  • A slug is never a parent of another: guides and guides/quickstart.md collide.
search limited to a path filters Dify retrieval by the slug field, or by document_name for a document without one. That filter needs Built-in Fields turned on in the dataset’s metadata settings, with document_name available. Without it, scoped search on name-based files may return nothing, while ls, find, cat and grep still work. A slug on every document gives the most predictable paths.

Connect

workspace.yaml

Layout

  • Only enabled, fully indexed, unarchived documents appear.
  • A file is plain text, its segments joined by line breaks, whatever the original format.
  • The search CLI asks Dify’s retrieval with --method semantic, fulltext, hybrid or keyword; --top-k is capped at 100.

Sample runs

The mount is read-only.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.