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

slugMetadataName picks the document metadata field that holds each path (default slug). maxConcurrency, retryAttempts and retryMaxDelay bound the requests in flight and the retries after a 429, a 5xx or a transport error.

Fields

string
required
secret
Dify Knowledge API key, sent as Authorization: Bearer.
string
required
Dify API root, such as https://api.dify.ai/v1.
string
required
ID of the Knowledge dataset the mount shows.
string
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.
number
default:"10"
The most Dify API requests in flight at once.
number
default:"4"
Attempts per request, the first included. A 429, a 5xx or a transport error is retried.
number
default:"30"
Longest wait in seconds before a retry, whether from backoff or Retry-After.
number
default:"DEFAULT_TIMEOUT"
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.
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 leaves out the API key, so Workspace.load takes a live DifyVFS in its third argument: Workspace.load(snapshot, {}, { '/knowledge': knowledge }).
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. A search under a path filters retrieval by the slug field, or by document_name for a document without a slug, which needs Built-in Fields turned on in the dataset’s metadata settings.

Browser

The same DifyVFS runs in the browser from @struktoai/mirage-browser.
  • The page calls the Dify API directly, so it must accept requests from the page’s origin.
  • The API key is visible to anyone who loads the page: give it access to the mounted knowledge base only.

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.