mirage README

The project's README from github.com/strukto-ai/mirage. As one markdown file: README.md.

Mirage: A Virtual Terminal for AI Agents

Status: preview
Python docs
TypeScript docs

README in English 简体中文 README 繁體中文 README README en Français README auf Deutsch README Tiếng Việt README 한국어

Mirage is a Virtual Terminal for AI Agents. The virtual filesystem delivers broad data context, virtualized CLIs give an agent more flexibility on tool use, dynamic runtimes save underlying infrastructure cost and are more token efficient, and fine-grained control over an agent's actions and even over what it can see gives the best security. Together these parts form one virtualized terminal, giving the best agent performance, cost efficiency and security.

Mirage architecture: agents and harness reach profiles and the Mirage shell, which resolve Unix-like commands, virtual CLIs and programming languages onto runtimes and the virtual filesystem, with authentication, the policy engine and notifications alongside

Here is an example of launching Mirage inside an application:

ws = Workspace(
    {
        "/tmp":   (RAMResource(), MountMode.EXEC),
        "/redis": (RedisResource(url=redis_url), MountMode.WRITE),
        "/slack": (SlackResource(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
    },
    # monty captures python, so scripts run sandboxed inside the workspace
    runtimes=[MontyRuntime(captures=["python", "python3"]), "vfs"],
)

# one grep sweeps every source
await ws.execute("grep -rln session /redis /tmp")

# run a script that lives in Slack, file the report into Redis
await ws.execute("python3 /slack/channels/general_.../files/example__F....py > /redis/report.txt")

# install a typed CLI under a head word: dispatched by name, not by path,
# and discoverable through `man`, `type` and `which` like any other program
ws.register_cli("slack", SLACK, {"token": slack_bot_token})
await ws.execute('slack send-message --channel general --text "report is up"')

About

Virtual Filesystem

Everything Mirage "mounts" as one unified virtual filesystem for AI agents. Each service sits side-by-side under a single root and answers the same POSIX semantics.

Resources
Object Storage Amazon S3  Cloudflare R2  Google Cloud Storage  Oracle OCI  Supabase Storage  MinIO  Ceph  SeaweedFS  Wasabi  Backblaze B2  DigitalOcean Spaces  Alibaba Cloud OSS  Tencent Cloud COS  Scaleway  QingStor  Hugging Face Buckets  GridFS
Files and Documents Google Drive  Google Docs  Google Sheets  Google Slides  OneDrive  SharePoint  Box  Dropbox  Nextcloud
Messaging and Work Slack  Discord  Gmail  IMAP / SMTP email  GitHub  Linear  Notion  Trello  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard

mirage (strukto-ai/mirage)

Searching Database…

3.7K ·GitHub
这是什么?Mirage 是一个面向 AI 代理的虚拟终端,它把 S3、Google Drive、Slack、Gmail 和 Redis 等服务挂载到一个统一的虚拟文件系统中,让代理用熟悉的 unix 工具(ls、grep、find、jq)访问一切、运行虚拟命令行、把代码路由到不同的运行时,并始终处于受策略控制的 shell 之内。
Mirage 是嵌入我应用里的框架,还是独立的命令行工具?它是你在自己的应用程序内启动的框架,而不是独立应用。它把虚拟文件系统、虚拟命令行和运行时绑定到一个由你的代理驱动的 shell 中。
怎么开始让我的代理使用 Mirage?你在应用程序内启动 Mirage,并把数据源(对象存储、文件、消息工具等)挂载到它唯一的虚拟文件系统根目录下;仓库的测试套件覆盖了 Python 和 TypeScript 两种集成。
代理要访问的每个服务都需要单独的 SDK 或 MCP 服务器吗?不需要。Mirage 用一个统一的虚拟终端接口取代了每个服务各自的 SDK 和 MCP 服务器,所有后端都说同一套文件系统语义。
代理能看到我想对它隐藏的文件或文件夹吗?不能——带 hide 和 show 规则的配置会把受限路径从代理可见范围内彻底移除,而不只是阻止读取;并且有一个可脚本化的策略引擎把关每一次文件系统操作和会话写入。
它能配合 Claude Code 或其他代理框架使用吗?可以——Mirage 以 dsh 插件的形式发布,其仓库主题标签列出了对 Claude Code 和 OpenAI Agents SDK 的支持,以及通用的 LLM 代理集成。
靠什么阻止代理执行删除文件这类危险操作?可脚本化的策略引擎可以在危险操作执行之前予以禁止,同一套机制还把关每一次虚拟文件系统操作和会话写入,确保什么都不泄露。
同一个底层工具能有带独立凭据的两个不同身份吗?可以——一个真实工具可以被虚拟化成两个或更多个命名的命令行,各自拥有独立凭据,代理会把它们看作不同的命令。
Mirage 如何应对外部变化,比如收到新的 Slack 消息?外部变化以事件的形式流入挂载点——一条新的 Slack 回复会体现为虚拟文件系统中聊天文件的变更,代理据此做出反应,而无需重新扫描整棵目录树。
代理执行的代码可以路由到哪些运行时?Python、JavaScript 和其他命令都可以发送到配置好的运行时——进程内、沙箱或远程——从而把计算与存储解耦。
What are similar projects?capsule-fs, nono, xerj, cynative, computer, coop, DSH-taskboard, agentbox
Creator
strukto-ai
Size
109.9 MB
Stars
3.7K
Age
5mo
Commits · 90 Days