Mirage Unified VFS
A Bash-oriented virtual filesystem that lets AI agents work across connected data services.
- Source repo
- strukto-ai/mirage
- Stars
- ★ 3.6k
- Last updated
- 4d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 54/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API
- You'll need
- Typical use
- An operations team building a log-analysis agent can mount an S3 log bucket and Slack channels together, then use
grepandwcto count alerts. - Main limitation
- Remote backends depend on their own network access, configuration, and credentials; the Slack example requires
SLACK_BOT_TOKEN. - Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
Mirage is a unified virtual filesystem for AI agents that mounts services such as S3, Google Drive, Slack, Gmail, and Redis into one workspace tree. It provides Python and TypeScript SDKs, the `mirage` CLI, and an optional FUSE-based mount path; the SDKs can run in-process in FastAPI, Express, browser applications, or other async runtimes. Agents and applications invoke Bash-style commands through `Workspace.execute` to read, filter, copy, and pipe data across backends. A `Workspace` can be snapshotted, loaded, and cached to preserve or reuse workspace state. The repository also documents integrations for OpenAI Agents SDK, LangChain, Vercel AI SDK, Claude Code, Codex, and other frameworks.
A developer creates a Workspace with mounts such as RAMResource at /data and S3Resource at /s3, then calls await ws.execute("cp /s3/report.csv /data/report.csv") or runs commands including grep, find, and wc. Commands can compose across mounted directories, while ws.command can register a command or override behavior such as cat for a specific resource and filetype. The mirage CLI can create a workspace, execute commands, provision resources, create snapshots, and load a workspace from demo.tar. Each Workspace has index and file caches, with RedisFileCacheStore and a Redis index available for shared cache state across workers, processes, or machines.
- An operations team building a log-analysis agent can mount an S3 log bucket and Slack channels together, then use
grepandwcto count alerts. - A Python service that prepares reports from object storage can copy
/s3/report.csvinto a RAM-backed/dataworkspace throughWorkspace.execute. - A developer adding a common data-access layer to an OpenAI Agents SDK, LangChain, or Pydantic AI application can use the documented Python integration paths.
- A Node.js team combining Google Drive, Gmail, GitHub, Notion, or Slack data can expose the selected backends as directories through the TypeScript SDK.
- An engineering team that needs to preserve or move an agent run can export and restore a workspace with the snapshot and load commands.
How do you install or deploy this agent?
Python requires version 3.11 or later: uv add mirage-ai. Node.js requires version 20 or later: npm install @struktoai/mirage-node; use npm install @struktoai/mirage-browser for browser or edge runtimes, and npm install @struktoai/mirage-agents for agent adapters. The CLI is available through npm install -g @struktoai/mirage-cli, uvx mirage-ai, npx @struktoai/mirage-cli, or the installation script shown in the README. Remote resources need their applicable configuration and credentials: the Slack example uses SLACK_BOT_TOKEN, while S3Resource is configured with a bucket.
How do you use this agent?
For a minimal Python setup, import Workspace and RAMResource, create ws = Workspace({"/data": RAMResource()}), and run await ws.execute("ls /data"). To work with S3, add "/s3": S3Resource(S3Config(bucket="my-bucket")), then run await ws.execute("cp /s3/report.csv /data/report.csv"). A CLI flow starts with mirage workspace create ws.yaml --id demo, followed by mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv".
What are this agent's strengths and limitations?
- It exposes multiple data backends through paths, Bash commands, and pipelines instead of requiring separate interaction patterns for each service.
- Python and TypeScript SDKs run in-process and are accompanied by CLI, MCP, FUSE, and documented agent-framework integration paths.
- Its built-in index and file caches work in process by default, with Redis support for cache sharing across workers, processes, and machines.
- Workspaces can be cloned, snapshotted, and versioned; the CLI can also load a snapshot into a workspace.
- Remote backends depend on their own network access, configuration, and credentials; the Slack example requires
SLACK_BOT_TOKEN. - Python, Node.js, and FUSE have different runtime requirements, and FUSE mounts depend on supported macOS or Linux platforms.
- Although the repository lists around 50 backends, the supplied material does not specify permissions, operation coverage, or failure behavior for each one.
- The documented defaults are a 10-minute index TTL and a 512 MB file cache, so freshness-sensitive or large-file workloads may need configuration changes.
How does this agent compare with similar options?
Mirage is positioned as one filesystem interface in place of learning separate service SDKs and multiple MCP interfaces. It keeps Bash-style operations such as reading, grep, and piping rather than introducing a distinct command vocabulary for every backend.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Mirage Unified VFS This agent | 54 · Major gaps | ★ 3.6k | 4d ago | TypeScript | Codex · Claude Code · OpenAI API |
| AnyAgent | 41 · Major gaps | ★ 1.2k | 4mo ago | Python | — |
| Agentic AI Engineering Course | 39 · Major gaps | ★ 6.2k | 4d ago | Jupyter Notebook | OpenAI API |
| OpenGAP | 51 · Major gaps | ★ 2.9k | 2mo ago | TypeScript | Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: CLI tests verify auth modes (local/token/jwt), token file permissions 600, health check bypasses auth, but no user confirmation mechanism or data flow transparency documentation found. Deductions: user confirmation missing, data flow transparency only partially mentioned (cache), sensitive data handling has auth but no explicit encryption.
Evidence shows: CLI tests cover exit code propagation, pipe behavior, command limits, indicating error handling is tested. Deductions: dependency availability not explicit, failure messages not detailed in docs.
Evidence shows: README lists many backends and integrations, supports Python and TypeScript, has CLI and SDK. Deductions: capability boundaries not explicit, trigger precision (commands) has examples but not comprehensive, environment fit described but not in depth.
Evidence shows: README structure clear, install notes detailed, examples present, license Apache-2.0. Deductions: naming stability not explicit, known limitations not listed, versioning/changelog not provided, maintenance responsibility not explicit.
Evidence shows: output usability has examples, marginal value high (unified filesystem), cost-benefit not quantified. Deductions: cost-benefit no data.
Evidence shows: README claims have some doc links, but no specific evidence. Deductions: claim traceability insufficient, cross-source corroboration limited, fact/inference separation not explicit.
- No user confirmation mechanism found, commands may execute without prompt.
- Data flow transparency limited, caching may obscure data access.
- Dependency security not explicit, need to check for vulnerabilities.
- Known limitations not listed, may affect production use.
FAQ
Is it limited to one model or agent framework?
Does every remote operation make a new request?
Can a workspace move to another machine?
mirage workspace snapshot and mirage workspace load.