Mirage Unified VFS
A Bash-oriented virtual filesystem that lets AI agents work across connected data services.
- Source repo
- strukto-ai/mirage
- Stars
- ★ 3.8k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 70/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- 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. - Not a fit if
- Teams that need fully offline operation with no external service credentials
- Windows-only environments or setups where FUSE mounts are unavailable
- Users unwilling to configure network access and credentials for remote backends
- Source review
- 70/100 · Some 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 | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mirage Unified VFS This agent | 70 · Some gaps | Library / SDKFree | ★ 3.8k | today | TypeScript | Codex · Claude Code · OpenAI API |
| AnyAgent | 58 · Major gaps | Library / SDKFree + model costs | ★ 1.3k | 1mo ago | Python | — |
| Agentic AI Engineering Course | 40 · Major gaps | FrameworkFree + model costs | ★ 6.6k | 7d ago | Jupyter Notebook | OpenAI API |
| OpenGAP | 54 · Major gaps | CLIFree + model costs | ★ 3k | 4mo ago | TypeScript | Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The configuration example shows read/write mount modes, profile-based path hiding, and command denial. Security documentation describes host ceilings, workspace and profile permissions, and resource limits, so least privilege has concrete support; however, confirmation behavior is not specified, and profiles may raise workspace limits. For sensitive data, examples keep credentials in application configuration and documentation says policies can block environment-variable leakage. Dependency-license checks have CI gates, but this packet does not establish vulnerability management. Data flows and external effects such as mounted services and API/message actions are described, while general write confirmation and recovery are not. A security reporting channel and Apache license provide attribution evidence; publisher identity remains unknown.
AGENTS/CLAUDE describe two-language semantic parity, parity gates, and shared integration cases; security documentation gives default resource limits, and the CLI maps configuration and connectivity errors to clear messages and exit codes. The development guide also says the interface is still moving, and some integration jobs are path-filtered, so the material does not establish complete consistency or availability of every dependency. This is a static review; no code or tests were executed.
The material covers embedded applications, Python, TypeScript, CLI, server, browser/edge environments, and file, database, SaaS, and custom VFS scenarios; installation docs state runtime and platform prerequisites. Profiles, mount modes, and runtime routing define some capability boundaries, and skill triggers are specific. However, many backend capabilities are presented as catalogs or summaries, examples cover only a few paths, and environments still require feature-specific dependencies and native setup.
Repository guidance, installation instructions, API quickstart, security docs, and authoring skills form a clear information structure. Language- and runtime-specific prerequisites, commands, and optional dependencies are detailed. Naming and cross-language conventions are documented, but the interface is explicitly evolving; examples are useful while FAQ/troubleshooting coverage is limited, and limitations are distributed across docs. The repository includes an Apache-2.0 license and a security reporting policy. The guide says changesets are not currently required and release notes await interface stability, so version history evidence is thin. A maintenance contact and reporting process are stated, but publisher identity is unverified.
The combination of shell, virtual filesystem, virtual CLIs, and runtime routing is illustrated with concrete examples that can inform real workflows; unified cross-service search and policy controls show clear marginal value. The README's low-memory and cost claims are not verified by this static review. Supporting multiple languages, runtimes, and optional backends also adds integration and operations costs, so cost-benefit does not receive full marks.
README architecture and usage claims have partial counterparts in the installation, security, and development guides; code samples show explicit error handling, and workflow files list build/check commands, providing some corroboration. However, performance and some capability claims are only asserted in documentation, and sample code or integration fixtures do not prove that tests ran. The materials distinguish configuration facts from an evolving interface, but inference and quantitative claims lack measurement evidence in this packet.
- This is a low-confidence static assessment; descriptions of tests and gates do not mean they were run for this review.
- Before connecting real services, configure mount permissions, profiles, and host resource ceilings for the intended task, and establish recovery procedures for writes and external actions.
- The project says its interface is still evolving; performance, coverage, and cost claims should not be treated as verified by this assessment.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/mirage)<a href="https://followagents.com/en/agents/mirage"><img src="https://followagents.com/badge/mirage.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.0.8 Mirage 0.0.8
Release notes excerpt
We are excited to announce the release of Mirage 0.0.8 🎉🎉🎉 Mirage 0.0.8 is a hosting release. 0.0.7 sent every way in through one dispatcher; 0.0.8 makes that dispatcher safe to run many workspaces side by side. A workspace now has a memory budget, a network it may reach, mounts with capacity, and processes and jobs that live in the shared store, and the server runs its workspaces on several workers with rate limits, readiness, a graceful drain and OpenTelemetry. Underneath, the shell runs on Mirage's own bash parser in Rust, and jq, awk, tar, zip, patch, od, iconv and most text commands move …View on GitHub ↗ -
v0.0.7 Mirage 0.0.7
Release notes excerpt
We are excited to announce the release of Mirage 0.0.7 🎉🎉🎉 Mirage 0.0.7 is a one-dispatcher release. 0.0.6 decided what an agent may do; 0.0.7 sends every way in through the same place, so that decision, the cache and the search hold alike for a command, a CLI, a runtime and every server endpoint. Commands read and write through the dispatcher, and every backend runs the same generic commands. Underneath, the command kernels move into one Rust crate that both hosts run, through PyO3 in Python and WebAssembly in TypeScript: sed, grep, rg, sort, jq, printf, bc, diff, cut and tr among them. A mo …View on GitHub ↗ -
v0.0.6 Mirage 0.0.6
Release notes excerpt
We are excited to announce the release of Mirage 0.0.6 🎉🎉🎉 Mirage 0.0.6 is a permissions release. 0.0.5 gave an agent typed programs to act with; 0.0.6 decides what it may do with them. A permissions document replaces the old guard list: allow, ask and deny rules, one role per session, mounts that narrow rather than gate, hidden subtrees that stay hidden through a mutation, an approval door where an asked line reaches a person, and a decision ledger you can query and explain. A policy can now be a program, written in Python or JavaScript and judged at the command, op and session doors. Creden …View on GitHub ↗
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.Is FUSE required?
Thanks — we use this to improve the page.