Skip to main content
Haystack is deepset’s framework for LLM applications and agents. deepset maintains the Mirage integration in haystack-core-integrations. It describes a mount tree, builds a Mirage workspace from it, and hands an Agent one bash tool over that workspace.

Install

mirage-haystack 0.0.1 pins mirage-ai==0.0.3, because Mirage is pre-1.0, so installing it moves mirage-ai to that release. It builds mounts through mirage.resource.registry, which mirage-ai 0.0.7 replaced with mirage.vfs.registry, so it cannot share an environment with a current mirage-ai. Check the integration’s pyproject.toml for the current pin.

Usage

Describe the mounts, wrap the workspace in a tool, and hand the tool to an Agent:
resource is a Mirage backend name (MirageMount.available_resources() lists them) and config takes that backend’s config keys. A config value may be a Haystack Secret, resolved only when the workspace is built.

Tools

The agent gets one tool, mirage_shell, with a single command parameter, so the model writes ordinary bash and pipes across mounts. Its description is generated from the mount tree, so the model learns which paths exist and which are read-only.

Guarding the agent

Three controls, and they are not interchangeable:
  • read_only=True on a mount is the write boundary. Mirage refuses every write to that mount whatever command runs, so this is what prevents modification and deletion.
  • allowed_commands limits which command names may run. It is checked against every command Mirage would execute, including ones nested in $(...), backticks, <(...) and subshells, so ls "$(rm x)" is refused unless rm is allowed too. Treat it as steering, not a sandbox: allowing a command that runs other commands (eval, bash, sh, source, xargs, timeout) allows anything.
  • denied_paths refuses any command whose text contains one of the given path substrings.
Commands never reach the host shell. Mirage interprets them itself, so the reach is the attached mounts.

Exports