mirage  by strukto-ai

A Unified Virtual Filesystem For AI Agents

Mirage offers a unified virtual filesystem for AI agents, abstracting diverse backend services like cloud storage, SaaS applications, and databases into a single, navigable tree. This enables agents, especially LLMs trained on bash, to interact with any service using familiar Unix-like tools, simplifying multi-service workflows and enabling natural pipeline composition across disparate data sources.

How It Works

Mirage implements a virtual filesystem layer that mounts various resources—including RAM, disk, Redis, cloud object storage (S3, GCS), SaaS platforms (Google Workspace, Slack, GitHub), and databases—under a single root. Agents interact with these mounted services using standard bash commands and Unix utilities. This approach leverages LLMs' extensive training on shell environments, eliminating the need to learn numerous SDKs/APIs and allowing pipelines to compose across services as seamlessly as local file operations.

Quick Start & Requirements

Installation: Python: uv add mirage-ai (requires Python >= 3.12). Node.js: npm install @struktoai/mirage-node or @struktoai/mirage-browser (requires Node.js >= 20). CLI: curl -fsSL https://strukto.ai/mirage/install.sh | sh. Mirage requires macOS or Linux due to FUSE-based mounts.

Highlighted Details

• Extensive Service Integration: Supports S3, GCS, R2, OCI, Supabase, Redis, MongoDB, SSH, Gmail, GDrive, GDocs, Slack, Discord, GitHub, Linear, Notion, Trello, and more.
• Agent Framework Compatibility: Integrates with OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands.
• Performance Caching: Features a two-layer cache (index and file) for remote resources, reducing latency by serving subsequent requests from local state. Cache backends: RAM (default) or Redis.
• Portable Workspaces: Enables cloning, snapshotting, and versioning of the agent environment for reproducible runs and easy migration.
• Embeddable SDKs: Python and TypeScript SDKs allow direct integration into applications without a separate process.

Maintenance & Community

The provided README lacks specific details on maintainers, community channels (e.g., Discord, Slack), or project roadmap.

Licensing & Compatibility

The README does not specify a software license. This omission requires clarification regarding usage terms, particularly for commercial applications or integration into closed-source projects.

Limitations & Caveats

Mirage's FUSE-based mounting restricts its use to macOS and Linux. The absence of explicit licensing information is a significant adoption blocker, necessitating further investigation into usage rights.