mirage
The World's First Unified Virtual Filesystem For AI Agents
What is it?
What it is
Mirage is a Unified Virtual File System for AI Agents that mounts diverse services and data sources—such as S3, Google Drive, Slack, Gmail, Redis, and many more—side‑by‑side under a single filesystem, allowing agents to use familiar POSIX commands to read, write, and pipe across any backend without new vocabulary.
Why it exists
It eliminates the need for agents to interact with dozens of SDKs and APIs, streamlining development, enabling natural pipelines across services, providing caching, portability, and a consistent interface for agent frameworks and coding agents.
Who should use it
Developers working with AI agents, data scientists, and software engineers needing a unified virtual file system for integrating multiple data sources (e.g., S3, Slack, Redis) into agent workflows.
Who should avoid it
Non-technical users, those not requiring VFS integration or agent tooling, and projects lacking compatibility with TypeScript/Python ecosystems.
How it works
A quick walkthrough in plain English
How mirage works
Step 1 of 3
You interact with it
Open mirage, send a request, or connect it to your stack.
Features
Advantages
- Simplifies multi‑service integration by providing a single filesystem interface
- Enables natural pipelines across services using familiar shell commands
- Reduces SDK and API complexity for developers and agents
- Caching improves performance and reduces network usage
- Portability allows agents to run on different machines without re‑setup
- Extensibility lets users customize behavior per resource or filetype
- Embeddable SDKs fit into existing applications and runtimes
- Wide agent framework support accelerates adoption
- CLI/daemon support facilitates quick prototyping and coding agents
Disadvantages
- Adds an abstraction layer that may introduce latency for some operations
- Requires network connectivity for remote backends; offline use limited
- Learning curve for users unfamiliar with virtual filesystem concepts
- Not all backend features may be fully exposed via POSIX commands
- Platform support for FUSE mounts may be limited (macOS/Linux only)
- Large number of backends can increase maintenance complexity
- Potential security considerations when mounting sensitive services
Installation
native
Python: uv add mirage-ai. TypeScript: npm install @struktoai/mirage-node, npm install @struktoai/mirage-browser, or npm install @struktoai/mirage-agents. CLI: curl -fsSL https://strukto.ai/mirage/install.sh | sh, npm install -g @struktoai/mirage-cli, uvx mirage-ai, or npx @struktoai/mirage-cli.
FAQ
How do I install Mirage for Python?
Use `uv add mirage-ai` (or pip) to install the `mirage-ai` package, which provides the Mirage library and the `mirage` CLI binary.
How do I install Mirage for TypeScript projects?
Run `npm install @struktoai/mirage-node` for Node.js servers/CLIs, `@struktoai/mirage-browser` for browser/edge runtimes, and `@struktoai/mirage-agents` for framework adapters; all pull in `@struktoai/mirage-core` automatically.
How can I execute bash-like commands across multiple mounted backends?
Create a Workspace with resources mounted at paths (e.g., `/data`, `/s3`, `/slack`) and call `ws.execute('your command')`; the command runs in the unified virtual filesystem, allowing grep, cp, find, etc., across services.
How does Mirage caching work and how can I configure a shared Redis cache?
Each Workspace has an index cache (listings/metadata) and a file cache (object bytes), both in-process RAM by default. To share cache across workers, pass a `RedisFileCacheStore` for the file cache and a Redis index store with TTL when constructing the Workspace.
How do I snapshot and restore a Mirage workspace?
Use `ws.snapshot('demo.tar')` to save the workspace state to a tar file, and later `mirage workspace load demo.tar --id demo-restored` (or the SDK equivalent) to load it into a new Workspace ID.
How does Mirage integrate with agent frameworks like OpenAI Agents SDK or LangChain?
Mirage provides SDK-specific adapters: for Python, see the OpenAI Agents SDK, LangChain, Pydantic AI, CAMEL, OpenHands, and Agno docs; for TypeScript, see the Vercel AI SDK, OpenAI Agents SDK, LangChain, and Mastra adapters, allowing agents to treat Mirage as a sandbox or tool layer.
Featured in Videos
YouTube tutorials and walkthroughs for mirage
Alternatives
Similar projects ranked by category, topics, and text overlap.
