Mirage: A Unified Virtual Filesystem for AI Agents
摘要：Mirage provides a unified virtual filesystem abstraction for AI agents — mount GitHub, local dirs, databases, and cloud storage through a single consistent interface.
文章目录
- Unified VFS Abstraction: Agents interact with a single, consistent filesystem API regardless of whether the backend is a local directory, a GitHub repo, an S3 bucket, or a Notion database — no more per-backend SDK integration. Modular Resource System: Resources are self-contained Python classes that expose standard filesystem primitives (read, write, list, stat). Users can write custom Resources for any backend in under 100 lines of code. FUSE Mount & Agent Harness: Can mount as a FUSE filesystem on macOS/Linux for full host integration, or run as a lightweight Python harness that AI coding agents use as their primary execution environment. Session Forking for Parallel Exploration: Agents can branch from any session point and explore multiple paths in parallel, with winner-takes-all state merging — enabling powerful tree-of-thought workflows.
- Issue #24 — Session.fork() filesystem isolation bug 1 comment — raised by community member analyzing PR #23 "PR #23 added Session.fork() and frames it as the primitive for parallel agent exploration — two agents branching from the same point, each pursuing a different path, with the winner's changes committed back. That framing is right, but the implementation only covers half the problem. Forked sessions inherit a copy of cwd, env, allowed_mounts, and functions. They do not get an isolated view of the filesystem. Both sessions dispatch to the same resource adapter instances. A write from session A to /data/scratch.txt in a RAM resource is immediately visible from session B." Maintainer response (@zechengz): "IMO we can have a plan for the branching functionality instead of the current vanilla unix style one... session.fork may not be a good place to define the fork — we need to rethink where branching should be scoped." Issue #25 — FUSE as primary execution substrate (not optional overlay) 1 comment — architectural design discussion "FUSE should be the primary execution substrate, not an optional mount overlay. The whole point of a VFS is that the agent should be living inside the virtual filesystem, not talking to it from the outside." Maintainer response (@zechengz): "In my current design we can make the FUSE as a tighter integration but in the short term we don't need to make the FUSE as the primary execution layer to fully support current claude code / codex etc. As future model capability increases, heavy execution can be done via remote execution such as from the sandbox or cloud service." Issue #40 — Feature Request: Nextcloud / WebDAV Resource 3 comments — community contribution discussion "Seems excellent fit, will support them. :)" — @zechengz "I am happy to contribute if it's okay @zechengz" — @nnayz "Sure! :)" — @zechengz Follow-up PR #44 (@nnayz): implements NextcloudResource for WebDAV/Nextcloud integration. The community is actively stepping up to extend the Resource ecosystem, with the maintainer welcoming external contributors.
- Mirage is a fresh take on the agentic computing substrate problem — rather than bolting on tools and plugins to a bare Python REPL, it builds a proper virtual filesystem layer that makes AI agents feel at home with diverse data sources. The discussions above reveal an active community wrestling with real design trade-offs: filesystem isolation in forked sessions, the role of FUSE in agent execution, and the pace of community-driven Resource expansion. For developers building AI-native applications or coding agents, Mirage offers a thoughtfully designed foundation worth exploring. --- Project: strukto-ai/mirage | 2,246 ⭐ | Python + TypeScript
Mirage is an open-source unified virtual filesystem (VFS) designed specifically for AI agents. It provides a clean, consistent interface for agents to interact with diverse backend resources — local files, GitHub repositories, databases, cloud storage, and more — without needing to understand the underlying implementation of each. Built in Python with TypeScript bindings, Mirage lets developers define "Resources" as modular, composable building blocks that agents can mount, read, write, and explore. The project supports FUSE mounting for seamless host system integration, and can run as a lightweight sandboxed harness for AI coding agents like Claude Code, Codex, and OpenAI Agents.
- Unified VFS Abstraction: Agents interact with a single, consistent filesystem API regardless of whether the backend is a local directory, a GitHub repo, an S3 bucket, or a Notion database — no more per-backend SDK integration.
- Modular Resource System: Resources are self-contained Python classes that expose standard filesystem primitives (read, write, list, stat). Users can write custom Resources for any backend in under 100 lines of code.
- FUSE Mount & Agent Harness: Can mount as a FUSE filesystem on macOS/Linux for full host integration, or run as a lightweight Python harness that AI coding agents use as their primary execution environment.
- Session Forking for Parallel Exploration: Agents can branch from any session point and explore multiple paths in parallel, with winner-takes-all state merging — enabling powerful tree-of-thought workflows.
Issue #24 — Session.fork() filesystem isolation bug
1 comment — raised by community member analyzing PR #23
"PR #23 added Session.fork() and frames it as the primitive for parallel agent exploration — two agents branching from the same point, each pursuing a different path, with the winner's changes committed back. That framing is right, but the implementation only covers half the problem. Forked sessions inherit a copy of cwd, env, allowed_mounts, and functions. They do not get an isolated view of the filesystem. Both sessions dispatch to the same resource adapter instances. A write from session A to /data/scratch.txt in a RAM resource is immediately visible from session B."
Maintainer response (@zechengz): "IMO we can have a plan for the branching functionality instead of the current vanilla unix style one... session.fork may not be a good place to define the fork — we need to rethink where branching should be scoped."
Issue #25 — FUSE as primary execution substrate (not optional overlay)
1 comment — architectural design discussion
"FUSE should be the primary execution substrate, not an optional mount overlay. The whole point of a VFS is that the agent should be living inside the virtual filesystem, not talking to it from the outside."
Maintainer response (@zechengz): "In my current design we can make the FUSE as a tighter integration but in the short term we don't need to make the FUSE as the primary execution layer to fully support current claude code / codex etc. As future model capability increases, heavy execution can be done via remote execution such as from the sandbox or cloud service."
Issue #40 — Feature Request: Nextcloud / WebDAV Resource
3 comments — community contribution discussion
"Seems excellent fit, will support them. :)" — @zechengz
"I am happy to contribute if it's okay @zechengz" — @nnayz
"Sure! :)" — @zechengz
Follow-up PR #44 (@nnayz): implements NextcloudResource for WebDAV/Nextcloud integration. The community is actively stepping up to extend the Resource ecosystem, with the maintainer welcoming external contributors.
Mirage is a fresh take on the agentic computing substrate problem — rather than bolting on tools and plugins to a bare Python REPL, it builds a proper virtual filesystem layer that makes AI agents feel at home with diverse data sources. The discussions above reveal an active community wrestling with real design trade-offs: filesystem isolation in forked sessions, the role of FUSE in agent execution, and the pace of community-driven Resource expansion. For developers building AI-native applications or coding agents, Mirage offers a thoughtfully designed foundation worth exploring.
---
Project: strukto-ai/mirage | 2,246 ⭐ | Python + TypeScript
微信扫一扫,分享到朋友圈
