Mirage in 30 Seconds
Mount your resources, then run shell commands across them. The same echo, ls, grep work against an in-memory mount, S3, Slack, etc.
Python
TypeScript
- CLI
Add GitHub, Postgres, SSH, Notion, Google Drive, … and the same shell vocabulary keeps working. That’s the whole pitch.
What is Mirage?
Mirage is a Unified Virtual Filesystem for AI agents. It mounts your apps, services, and systems behind one filesystem interface, so an agent reaches every backend with the same handful of Unix-like tools instead of a new SDK per service.
One Filesystem
Every service speaks the same filesystem semantics, so agents reason about one abstraction instead of N SDKs and M MCPs. S3, R2, Google Drive, GitHub, Linear, Notion, Slack, Discord, MongoDB, Redis, SSH, and more mount side-by-side under a single root.
Familiar Bash Tools
Agents reuse the same handful of Unix-like tools (ls, find, grep, cat, …) instead of learning a new API per service. Pipelines compose across services as naturally as on a local disk, the exact corpus modern LLMs are most heavily trained on.
Portable, Versioned Workspaces
Snapshot, clone, and version a workspace the way git treats source. Move agent runs between machines without restarting, fork from any past state, and replay a run on demand.
Embed in Apps and Agents
Python and TypeScript SDKs give your AI agents a virtual filesystem directly inside FastAPI, Express, browser apps, or any async runtime, no separate process required. Works with the major agent frameworks (OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, OpenHands) and a lightweight CLI plugs into coding agents like Claude Code and
Codex.
A Real-world Example
An agent watches your team’s Slack #incident channel. A user posts a screenshot of mirage —help with the message “the CLI design is confusing and hard to follow”.
Built with the OpenAI Agents SDK, the agent walks Slack, GitHub, and Linear through one bash tool.
Code
Python
TypeScript
Full runnable source: examples/python/demo/design_feedback.py.
Walk-through
Inside the workspace shell, the agent runs three steps:
The agent files a new issue in Linear with the user’s feedback and links to the relevant source files.
Use Cases
Mirage shows up wherever an agent needs to read, write, or stitch together data that doesn’t already live on a local disk.
Cross-app triage agents
SWE agents on remote data
RAG with writes
Ops & observability copilots
tail, grep, jq over remote logs, metrics, and config without per-source plugins.Sandbox-native workflows
Reproducible agent runs
FAQ
Do I need FUSE?
Do I need FUSE?
ws.execute(…) parses and dispatches commands without mounting anything on the host. FUSE is an optional surface if you also want host tools (editors, language servers, rg) to see the workspace.Where does the shell run? Is it really bash?
Where does the shell run? Is it really bash?
/bin/bash and no os.system. Most common Unix verbs work (ls, cat, grep, find, head, wc, jq, …) plus pipes, redirects, globs, and &&/||.Is it sandboxed?
Is it sandboxed?
What about latency and cost?
What about latency and cost?
cat /s3/… is one GetObject; find /postgres/… is a SQL query. Reads cache per session, and mirage provision returns a dry-run estimate (network bytes, cache hits, projected cost) before you commit to an expensive operation.Hosted or self-hosted?
Hosted or self-hosted?
Which agent frameworks are supported?
Which agent frameworks are supported?
Python or TypeScript?
Python or TypeScript?
@struktoai/mirage-node) ships the same Workspace/execute surface and most resources. Some agent integrations land on Python first.What if a resource I want isn't supported yet?
What if a resource I want isn't supported yet?