Mirage - strukto-ai: An open-source AI agent and unified virtual file system.

What is Mirage?

Mirage is a unified virtual file system for AI agents developed by the strukto-ai team. The tool mounts heterogeneous data sources such as S3, Slack, Gmail, GitHub, and MongoDB into 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 needing to learn any new APIs. This achieves a single file system that handles all backends.

Mirage's main functions

• Unified Virtual MountMap all S3/R2/GCS, Google suites (Gmail/Drive/Docs), Slack/Discord/Telegram, GitHub/Linear/Notion, MongoDB/Redis/PostgreSQL, SSH remote servers, etc. to /s3,/slack,/github Standard catalogs, etc.
• Cross-service Bash operationsAI is available. cat,grep,head,find,cp,mvUnix commands such as pipes and redirection operate on any mount point, allowing cross-service pipes such as... grep alert /s3/log.jsonl | wc -l It takes effect immediately.
• Portable workspaceIt supports snapshots, cloning, and rollback. The entire Agent execution environment can be packaged into a tar file and migrated to another machine for direct recovery without reconfiguration.
• Two-layer smart cachingBuilt-in index cache (directory and metadata) and file cache (object bytes), zero network calls for repeated reads; supports memory (default 512MB) or Redis backend.
• Seamless integration with mainstream frameworksIt provides adapters for OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, OpenHands, etc.

Mirage's technical principles

• Core design philosophy: The file system is a universal abstraction. Mirage's technological foundation is built on a key insight: modern large language models have far more training data in Bash, Unix commands, and file operations than any single API SDK. Therefore, instead of 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 the AI has already internalized. This allows the Agent to operate on any data source without having to learn any new vocabulary, relying solely on its native Shell commands.
• Four-layer architecture. Mirage employs a top-down four-layer architecture: the top layer is the AI Agent and application layer, which interacts with the system via standard Bash or system calls; the second layer is the Mirage Bash and VFS layer, containing a command registry and a VFS operation registry, responsible for parsing and standardizing upper-layer input; the third layer is the Dispatcher and Cache layer, which routes requests to the corresponding backend based on the mount point and intercepts duplicate reads through two layers of caching; the bottom layer mounts local infrastructure such as RAM, disks, and Redis, along with remote services such as S3, GitHub, and Slack, into a single 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 (VFS) is the core translation engine of Mirage. Each backend service is mapped to behaviors that "look like a file system" by implementing standardized VFS interfaces (such as readdir, open, read, stat, etc.)—Slack channels become virtual directories, messages become JSON files, MongoDB collections become directories, and documents become JSON files. VFS does not care whether the underlying system is object storage or a chat channel; it only requires the backend to provide unified file operation semantics, thus allowing the upper-layer Agent to operate any backend with a completely consistent mindset.

How to use Mirage

• Environmental preparation:Ensure your system has Python ≥ 3.12 or Node.js ≥ 20 installed, and your operating system is macOS or Linux.
• Installation and deployment:Python through uv add mirage-ai Installation; TypeScript via @struktoai/mirage-node or @struktoai/mirage-browser Installation; CLI can be installed via one-click script, npm, uvx, or npx.
• Creating and configuring a workspace: Instantiate a Workspace object in the code, and specify the virtual path (e.g., ...) /s3,/slack) and corresponding resource-driven (e.g. S3Resource,SlackResourcePerform mount mapping.
• Execute Bash commands:pass ws.execute() Pass in standard Unix commands (such as...) cat,grep,cpMirage automatically translates these (pipelines, etc.) into actual API calls for the underlying services.
• Snapshots and Migration:Call ws.snapshot("demo.tar") Package the entire environment, through mirage workspace load demo.tar It can be restored directly on the new machine without reconfiguration.
• Integrating with the Agent framework:pass MirageSandboxClient Embed the OpenAI Agents SDK, or via mirageTools(ws) To integrate with the Vercel AI SDK, official adapters are provided for LangChain, Pydantic AI, CAMEL, and OpenHands.

Mirage's core advantages

• Zero learning costAI does not need to learn any new APIs or MCPs; it can directly reuse the semantics of Bash and the file system, which have the richest training data.
• Native support for cross-service pipelinesData flow between different backends is like local disk operation, and the agent can complete more actual work in a single round.
• Environmentally transplantableSnapshot and cloning capabilities enable versioning and migration of the Agent runtime environment, solving the state consistency problem in multi-machine deployment and Serverless scenarios.
• High-performance cacheThe two-layer caching mechanism significantly reduces the frequency of remote API calls, and the Redis backend is more adaptable to multi-process and serverless architectures.
• Frame-independent: Do not force a change of the Agent framework; embed it into the existing technology stack in the form of a sandbox or tool layer.

Mirage's project address

• Project official websitehttps://www.strukto.ai/mirage
• GitHub repositoryhttps://github.com/strukto-ai/mirage

Comparison of Mirage with similar products

Application scenarios of Mirage

• Multi-source log analysisThe agent simultaneously mounts the S3 log directory, Slack alert channel, and GitHub Issue repository, via... grep and wc Cross-service statistics on failure frequency and root cause identification.
• Automated report generationIt extracts data from Google Sheets, retrieves attachments from Gmail, and reads project documents from Notion, then aggregates them into a local virtual directory and automatically generates a comprehensive report.
• Remote server maintenanceBy mounting multiple remote hosts via SSH, the agent uses standard Bash to execute diagnostic commands, copy configuration files, and change system states in batches.
• Data migration and synchronizationBetween different cloud storage systems such as S3, R2, and GCS, or from MongoDB to local disks, via cp Use pipeline commands to migrate data from heterogeneous backends.
• Serverless Agent ServiceCombined with Redis shared cache, it provides a stateful and recoverable virtual file layer for serverless multi-replica AI applications, ensuring that the environment is not lost after the instance restarts.