Dify

The Dify VFS exposes completed Dify Knowledge documents as text files mounted at a prefix such as /knowledge/. Each file is assembled from the document’s completed, enabled segments. For API key setup, see Dify Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.dify import DifyConfig, DifyVFS

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name=os.environ.get("DIFY_SLUG_METADATA_NAME", "slug"),
)
vfs = DifyVFS(config=config)
ws = Workspace({"/knowledge/": vfs}, mode=MountMode.READ)

The VFS is read-only. A snapshot keeps its config, and a load needs the mount handed back through mounts=; it has no drift detection, so restored cache entries are served as saved and other reads reach the live backend.

Field	Description
`timeout` 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.
`api_key` required, secret	Dify Knowledge API key, sent as `Authorization: Bearer`.
`base_url` required	Dify API root, such as `https://api.dify.ai/v1`.
`dataset_id` required	ID of the Knowledge dataset the mount shows.
`slug_metadata_name` 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.
`max_concurrency` default `10`	The most Dify API requests in flight at once.
`retry_attempts` default `4`	Attempts per request, the first included. A 429, a 5xx or a transport error is retried.
`retry_max_delay` default `30.0`	Longest wait in seconds before a retry, whether from backoff or `Retry-After`.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Dify mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`dify`, read

`/<path>` layout

This is a Dify Knowledge Base mounted as a read-only filesystem.

All files are plain text assembled from Dify document segments, regardless of
their original extension. You can use cat, head, tail, grep, find, ls, and wc
on these files.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest).

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `dify`, read |

## `/<path>` layout

```text
This is a Dify Knowledge Base mounted as a read-only filesystem.

All files are plain text assembled from Dify document segments, regardless of
their original extension. You can use cat, head, tail, grep, find, ls, and wc
on these files.
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Dify documents are mapped to paths using the configured slug metadata field. The default metadata field name is slug. If a document has no configured slug metadata, Mirage falls back to the Dify document name.

/knowledge/
  README.md
  guides/
    quickstart.md
    api.md
  policies/
    support.md

Example mapping:

Dify document	Metadata	Mirage path
`Quickstart`	`slug=guides/quickstart.md`	`/knowledge/guides/quickstart.md`
`README.md`	no slug	`/knowledge/README.md`

Creating Slug Metadata in Dify

In the Dify Knowledge UI, open a document and add a metadata item whose name matches slug_metadata_name. The default name is slug.

name: slug
value: guides/quickstart.md

For a custom Dify metadata name:

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name="path",
)

Then use:

name: path
value: guides/quickstart.md

Mirage reads doc_metadata from Dify and uses this value as the document’s virtual path below the mount prefix. Use these rules for slug metadata values:

Use / to create folders.
Do not use empty segments, ., or ...
Keep each slug metadata value unique across the dataset.
Do not use a path that is also needed as a folder. For example, guides and guides/quickstart.md cannot both be document paths.

Only visible documents are included:

enabled is true
indexing_status is completed
archived is false

Reading Documents

cat, head, tail, and grep read Dify document segments. Segment content is joined with a single newline between chunks.

ls /knowledge/
find /knowledge/ -type f
cat /knowledge/guides/quickstart.md
head -n 20 /knowledge/guides/quickstart.md
grep -i "billing" /knowledge/guides/quickstart.md
wc /knowledge/guides/quickstart.md

Search

The search CLI asks Dify’s dataset retrieval API. Use it when meaning matters more than exact text matching. Register it on the workspace:

from mirage.commands.cli.builtin.search import SEARCH

ws.register_cli("search", SEARCH)

search "how do I reset my password" /knowledge/
search --method hybrid --top-k 5 "billing policy" /knowledge/policies/
search --method semantic --threshold 0.4 "quickstart" /knowledge/guides/*.md

Supported methods:

Method	Dify retrieval mode
`semantic`	semantic search
`fulltext`	full text search
`hybrid`	hybrid search
`keyword`	keyword search

--top-k defaults to 10 and is capped at 100. --threshold must be between 0 and 1; another value, or another method, exits 1 before Dify ranks anything. Results are emitted one retrieval hit per block:

/knowledge/policies/refunds:0.82
Refunds are allowed within 30 days.

Mirage uses the configured slug metadata field to derive the path, and falls back to the Dify document name when that metadata is missing. Multiple hits from the same document remain separate records. Scoped search uses Dify metadata filtering. Documents with the configured slug metadata field are filtered by that field; name-based documents are filtered by document_name, which requires Dify Built-in Fields to be enabled in dataset metadata.

Scoped Search Requirements

Mirage converts a scoped search path into Dify metadata filters:

Mirage target	Dify metadata filter
Document with configured slug metadata	`<slug_metadata_name> in [...]`
Document without configured slug metadata	`document_name in [...]`
Folder or glob	`<slug_metadata_name>` / `document_name` filters for all matched files

To make scoped search reliable:

Add the configured slug metadata field to every document.
Enable Dify Built-in Fields in the dataset metadata settings.
Ensure document_name is available if you rely on name-based paths.

If Built-in Fields are disabled, scoped search against documents without the configured slug metadata field may return empty results even though cat, grep, and find can still see the same file.

Cache

The VFS uses Mirage’s index cache for the virtual tree. Directory listings and path resolution reuse the cached document tree until the index expires or the workspace is recreated. If documents are edited directly in Dify, repeated operations can temporarily see cached paths and metadata. Document content is still read from Dify when commands materialize file data.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.search import SEARCH
from mirage.vfs.dify import DifyConfig, DifyVFS

load_dotenv(".env.development")

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name=os.environ.get("DIFY_SLUG_METADATA_NAME", "slug"),
)
vfs = DifyVFS(config=config)


async def main() -> None:
    ws = Workspace({"/knowledge/": vfs}, mode=MountMode.READ)
    ws.register_cli("search", SEARCH)

    r = await ws.shell("ls /knowledge/")
    print(await r.stdout_str())

    r = await ws.shell("find /knowledge/ -type f | head -n 10")
    print(await r.stdout_str())

    r = await ws.shell('search --method hybrid --top-k 5 "getting started" /knowledge/')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

A runnable version is available at examples/python/vfs/dify/dify.py.

Shell Commands

Command	Notes
`ls`	List folders and documents
`cat`	Read full document text from completed segments
`head` / `tail`	Read the first or last lines/bytes
`grep`	Exact or regex matching over streamed document text
`find`	Search the virtual tree by name, type, depth, and size
`wc`	Count lines, words, bytes, characters, and max line length

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Creating Slug Metadata in Dify

Reading Documents

Search

Scoped Search Requirements

Cache

Example

Shell Commands

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Creating Slug Metadata in Dify

​Reading Documents

​Search

​Scoped Search Requirements

​Cache

​Example

​Shell Commands

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Creating Slug Metadata in Dify

Reading Documents

Search

Scoped Search Requirements

Cache

Example

Shell Commands