Skip to main content

How to use mirage

Replace dsh's ctx.fs and ctx.shell capabilities with the Mirage workspace, enabling the DSH Agent to directly read and write to mounted data sources such as S3, Slack, and Redis.

This article is auto-derived from indexed fields (wiki / faq / compatibility_json), not freshly AI-generated.

This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

mirage

— source: plugin_wiki.wiki_content

Install & verify

dsh plugin --profile web add @struktoai/mirage-dsh

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

  • One interface instead of N SDKs and M MCPs. Every service speaks the same filesystem semantics, and pipelines compose across services as naturally as on a local disk.
  • Portable workspaces: clone, snapshot, and version a workspace; agent runs move between machines without restarting or reconfiguring the system.
  • Embeddable: the Python and TypeScript SDKs run in-process inside FastAPI, Express, browser apps, or any async runtime; no separate process required.
  • Agent integrations: OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands via the SDKs; coding agents through native adapters, installable plugins, MCP, or FUSE.
  • Python ≥ 3.11 for the mirage-ai package and the mirage CLI

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

What content does dsh see by default after installation?

A /tmp path is automatically mounted, with type RAM temporary disk and exec (executable) permissions. Apart from this, there are no other real data sources; all read/write operations are in this session's memory.

How to connect real data sources like Slack, Redis, S3?

Override the mirage line in your profile's cordis.patch.yml, use the mounts block to declare resources (resource for registration name, mode for read/write/exec, config for resource-required fields), and use !!js process.env.X to parse secret fields like tokens.

After enabling, why did the built-in PowerShell and ripgrep search tools in dsh disappear?

These two tools run host processes, but there's no place for them in the mirage workspace, so the installation package explicitly disables dsh's pwsh-sandbox, tool-pwsh and tool-fs-search; you can use grep in the bash tool to cover the search.

How to keep the directory and variables persistent across multiple bash tool calls?

Pass the sessionId field to the shell plugin; cd, export, and function definitions will persist across calls. When sessionId is not passed, each call is an independent subshell with non-persistent state.

How are background commands with large output handled?

Default stdout buffer is 200KB, stderr buffer is 64KB; exceeding this truncates the output and marks it as truncated. To get the full output, point the shell's spillDir to a workspace directory (such as /tmp); overflow parts will be spilled to disk as files, with paths returned in readOutput().

Is it an official DSH plugin?

It is not part of the DSH repository; it uses dsh's bundle mechanism (cordis.patch.yml) to insert its three Cordis plugins into the dsh system, thereby taking over the ctx.fs and ctx.shell capability gaps.

— source: plugin_wiki.faq_json

Compatibility

  • DSH: 0.1.0-rc.6
  • Node: >=20.10.0

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule