Mirage - strukto-ai's open-source unified virtual file system for AI Agents

What is Mirage

Mirage is a unified virtual file system for AI Agents launched by the strukto-ai team. The tool mounts heterogeneous data sources such as S3, Slack, Gmail, GitHub, MongoDB, and more as a single virtual file tree, allowing AI Agents to read, write, query, and copy data across services using Bash commands (cat, grep, wc, pipes, etc.) without learning any new API, achieving one file system that handles all backends.

Main Features of Mirage

• Unified virtual mounting: Maps S3/R2/GCS, Google Suite (Gmail/Drive/Docs), Slack/Discord/Telegram, GitHub/Linear/Notion, MongoDB/Redis/PostgreSQL, SSH remote servers, and more all to /s3、/slack、/github and other standard directories.
• Cross-service Bash operations: AI can use cat、grep、head、find、cp、mv, pipes, redirection, and other Unix commands to operate on any mount point, with cross-service pipelines such as grep alert /s3/log.jsonl | wc -l taking effect directly.
• Portable workspace: Supports snapshots, cloning, and rollback; the entire Agent execution environment can be packaged as a tar file, migrated to another machine, and restored directly without reconfiguration.
• Two-layer intelligent cache: Built-in index cache (directories and metadata) and file cache (object bytes), with zero network calls on repeated reads; supports in-memory (512MB by default) or Redis backend.
• Seamless integration with mainstream frameworks: Provides adapters for OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, OpenHands, and more.

Technical Principles of Mirage

• Core design philosophy: the file system as a universal abstraction. Mirage's technical foundation is built on a key insight—modern large language models have far more training data on Bash, Unix commands, and file operations than on any single API SDK. Therefore, rather than having AI learn N sets of heterogeneous interfaces, it is better to uniformly translate all backends such as S3, Slack, Gmail, and MongoDB into POSIX-style file semantics that AI has already deeply internalized, so that Agents can operate any data source using only the native Shell commands they excel at, without mastering any new vocabulary.
• Four-layer hierarchical architecture. Mirage adopts a top-down four-layer structure: the top layer is the AI Agent and application layer, which interacts with the system through standard Bash or system calls; the second layer is the Mirage Bash and VFS layer, which contains the command registry and VFS operation registry and is responsible for parsing and standardizing input from the upper layer; the third layer is the Dispatcher and Cache layer, which routes requests to the corresponding backend by mount point and intercepts repeated reads through two layers of cache; the bottom layer uniformly mounts local infrastructure such as RAM, disk, and Redis together with remote services such as S3, GitHub, and Slack into the same file tree, while the FUSE Adapter allows external applications to access it directly as a local disk.
• VFS virtual file system abstraction layer. The virtual file system is Mirage's core translation engine. Each backend service is mapped to behavior that "looks like a file system" by implementing standardized VFS interfaces (such as readdir, open, read, stat, etc.)—Slack channels become virtual directories and messages become JSON files, MongoDB collections become directories and documents become JSON files. The VFS does not care whether the underlying layer is object storage or a chat channel; it only requires the backend to provide unified file operation semantics, thereby enabling upper-layer Agents to operate any backend with a completely consistent mental model.

How to Use Mirage

• Environment preparation:Ensure the system has Python ≥ 3.12 or Node.js ≥ 20 installed, with macOS or Linux as the operating system.
• Installation and deployment:Python is installed via uv add mirage-ai ; TypeScript is installed via @struktoai/mirage-node or @struktoai/mirage-browser ; the CLI is installed via a one-click script, npm, uvx, or npx.
• Create and configure a workspace: In code, instantiate a Workspace object and mount-map virtual paths (such as /s3、/slack) to the corresponding resource drivers (such as S3Resource、SlackResource).
• Execute Bash commands:Pass standard Unix commands (such as ws.execute() and pipes) through cat、grep、cp, and Mirage automatically translates them into actual API calls for the underlying services.
• Snapshots and migration:Call ws.snapshot("demo.tar") to package the entire environment, and restore it directly on a new machine via mirage workspace load demo.tar , with no need to reconfigure.
• Integrate with Agent frameworks:Embed via MirageSandboxClient into the OpenAI Agents SDK, or integrate via mirageTools(ws) with the Vercel AI SDK; LangChain, Pydantic AI, CAMEL, and OpenHands all provide official adapters.

Mirage's core advantages

• Zero learning cost: AI does not need to master any new API or MCP, and directly reuses the Bash and file system semantics with the richest training data.
• Native support for cross-service pipelines: Data flows between different backends just like local disk operations, allowing an Agent to complete more actual work in a single turn.
• Portable environment: Snapshot and cloning capabilities make the Agent runtime environment versionable and migratable, solving state consistency issues in multi-machine deployment and Serverless scenarios.
• High-performance caching: The two-layer caching mechanism significantly reduces the frequency of remote API calls, and the Redis backend is better suited to multi-process and serverless architectures.
• Framework-agnostic: It does not force a change of Agent framework, and embeds into existing technology stacks as a sandbox or tool layer.

Mirage's project address

• Project website：https://www.strukto.ai/mirage
• GitHub repository：https://github.com/strukto-ai/mirage

Comparison of Mirage with similar competitors

Mirage application scenarios

• Multi-source log analysis: The Agent simultaneously mounts an S3 log directory, a Slack alert channel, and a GitHub Issue repository, and uses grep and wc to tally failure frequencies across services and identify root causes.
• Automated report generation: Extracts data from Google Sheets, retrieves attachments from Gmail, and reads project documents from Notion, aggregates them into a local virtual directory, and then automatically generates a comprehensive report.
• Remote server operations: Mounts multiple remote hosts via SSH; the Agent uses standard Bash to execute diagnostic commands in batches, copy configuration files, and change system state.
• Data migration and synchronization: Between different cloud storages such as S3, R2, and GCS, or from MongoDB to a local disk, complete data migration across heterogeneous backends using cp and pipeline commands.
• Serverless Agent services: Combined with Redis shared caching, provides a stateful, recoverable virtual file layer for multi-replica AI applications in serverless architectures, ensuring the environment is not lost after instance restarts.