Mirage — Dify Plugin

Author: ki3nd
Type: Tool
Github Repo: https://github.com/ki3nd/mirage-plugin
Github Issues: https://github.com/ki3nd/mirage-plugin/issues

Run bash commands across S3, Slack, Redis, RAM, and more — as one unified virtual filesystem — from inside Dify.

This plugin embeds Mirage, a unified virtual filesystem for AI agents. It mounts external resources (object storage, chat, databases, local scratch space, …) at filesystem paths, so an agent can , , , and pipe across all of them with plain bash — no per-service SDK or custom vocabulary.

Tools

Tool	What it does
execute	Run a bash command inside a Mirage workspace. Returns , , and . Supports pipes and cross-resource operations, e.g. or .
snapshot	Export the current workspace as a downloadable tar archive (optionally gzip-compressed). Captures mount configs, touched file bytes, sessions, and history.

How it works

The plugin runs the Mirage engine in a local daemon process () and talks to it over HTTP. The daemon holds live connections and a warm read cache, so repeated commands hit local state instead of re-connecting to remote services on every call.
Each conversation gets its own workspace (keyed by the workspace config together with the conversation), so parallel conversations stay isolated. Within a conversation the workspace is reused. Idle workspaces are evicted automatically.
Secrets never appear in tool parameters or in anything the model sees — they live only in the plugin credentials and are injected locally.

Configuration

Provider credentials (set once, encrypted)

Field	Description
Secrets (.env)	per line (UPPERCASE keys), e.g. . Referenced from the workspace YAML as .
Cache backend	(default) or .
Redis URL	Required only when the cache backend is , e.g. .

Paste your secrets into the Secrets (.env) field, one per line.
These are stored encrypted by Dify and are the only place actual secret values
should ever live:

Each line becomes a you can reference from the workspace YAML — for the
example above, , , and
. If you set Cache backend to , also fill in the
Redis URL field (e.g. ).

Workspace YAML (a tool parameter)

Each tool call takes a that declares the mounts. Secrets are referenced by name () and resolved from the credentials above — never inline the actual secret value.

Use block style (indented), not inline flow style: a placeholder inside is not valid YAML and will fail to parse.

Then, for example, call execute with .

Resource setup

Each mount's and fields follow Mirage's own resource specs.
For the full list of supported backends and how to configure each one (required
credentials, options, mount modes), see the Mirage docs:

Resource matrix (all backends): https://docs.mirage.strukto.ai/home/resource-matrix
Per-resource setup guides: https://docs.mirage.strukto.ai/home/setup/ — e.g.
S3,
Slack,
GitHub,
Postgres,
Notion,
Hugging Face Datasets,
and more.

Put secret values in the provider credentials and reference them from the YAML
as — don't paste the actual credential into .

Safety — read-only by default

A workspace is read-only unless you opt in. Commands that write, modify, or delete fail unless the YAML sets at the top level (whole workspace) or on an individual mount. Enable writes only when the task actually requires creating, editing, or deleting something.

Requirements

Python 3.12.
The plugin starts a local daemon subprocess and binds a port, so it must run in an environment that permits spawning a subprocess and local networking (e.g. a self-hosted Dify deployment).

Development

Design docs and the implementation plan live under .