AI 代理虚拟终端 strukto-ai/mirage

Mirage 是给 AI 智能体用的虚拟终端：一层 shell，统管数据、命令行和运行时。Unix 工具能触达每个服务，grep 直接跑在服务自己的搜索上，比如 Gmail 或 Slack 的搜索。Mirage 把每条命令路由到合适的运行时，多数命令行在进程内执行，只有重活才进沙箱，基础设施成本和 token 消耗都降下来。终端本身很轻：一个工作区占约 100 KB 内存，每个新会话约 10 KB，一个进程能同时服务多个智能体。配置档决定智能体能跑什么、甚至能看见什么，可脚本化的策略则拒绝那些规则表达不了的情况。

下面是在应用里启动 Mirage 的例子：

ws = Workspace(
{
"/s3": (S3VFS(S3Config(bucket="my-bucket")), MountMode.WRITE),
"/slack": (SlackVFS(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
"/gmail": (GmailVFS(GmailConfig(**google_credentials)), MountMode.READ),
},
Install the Slack CLI, run by name and listed by man and which like any program
clis={"slack": (SLACK, {"token": slack_bot_token})},
the analyst profile hides /s3/secrets and denies posting to Slack and curl
profiles={
"analyst": {
"paths": {"hide": ["/s3/secrets"]},
"commands": {"deny": ["slack send-message", "curl"]},
},
},
runtimes=[
MontyRuntime(captures=["python", "python3"]),
E2BRuntime(
captures=["python", "python3"],
config={"sandbox_id": sandbox_id, "mount_type": "ssh"},
),
],
路由底层计算：numpy 行在 e2b 沙箱中运行，其余在 monty 上运行
route_policy=lambda ctx: "e2b" if "numpy" in ctx.line else None,
)

用 analyst 配置档添加智能体
alice = await ws.session("alice", profile="analyst")

一条 grep 扫过 S3、Slack 和 Gmail，每个服务有自己搜索能力时就用它自己的 await alice.shell("grep -rlw invoice /s3 /slack /gmail")

运行一个存放在 Slack 里的脚本，在 monty 上跑，把报告归档到 S3 await alice.shell("python3 /slack/channels/general__C0123/2026-10-21/files/report__F0456.py > /s3/report.txt")

monty 里没有 numpy，所以路由策略把这一行发给 e2b await alice.shell("python3 -c 'import numpy; print(numpy.arange(10).sum())'")

以及 alice 在 shell 里看到的内容：

$ grep -rlw invoice /s3 /slack /gmail
/s3/billing/2026-10.csv
/gmail/INBOX/2026-10-21/Invoice_1042__18f3a9c2b7d1e0f4.gmail.json
$ ls /s3
billing
report.txt
$ cat /s3/secrets/aws.txt
cat: /s3/secrets/aws.txt: No such file or directory
$ slack send-message --channel general --text "report is up"
slack: Permission denied

关于

- 统一的虚拟终端接口，而不是 N 个 SDK 加 M 个 MCP。 每个后端都遵循同一套文件系统语义，所以流水线可以跨服务组合。
- 覆盖每个数据源的虚拟文件系统。 S3、Google Drive、Slack、Gmail、Redis 等并排挂载在同一个根目录下，智能体用已经熟悉的 unix 工具（如 ls、grep、find 和 jq）就能通过统一接口访问它们。
- 虚拟命令行工具（CLI）。 git、slack 和 ntn 由 Mirage 自己应答，所以智能体无需安装任何东西就能驱动服务，跨不同运行时和机器都行；一个工具还能虚拟化成两个或多个，各自有独立名称和独立凭据。
- 可路由的动态运行时。 Python、JavaScript 以及任何其他命令都能发往配置好的运行时——进程内、沙箱或远程——从而把计算与存储解耦，让两者各自变化而互不影响。
- 虚拟化的 Mirage shell。 它把文件系统、CLI 和运行时绑定到同一条命令行，所以管道、重定向、变量、作业和历史记录在三者之间都能用。
- 设计上轻量。 一个工作区（也就是虚拟终端本身）约占 100 KB 内存，每个新会话约占 10 KB，所以一个进程能服务多个智能体，无需为每个智能体单独开容器或 VM。
- 为智能体设计的配置档。 allow、ask 和 deny 管控命令和 CLI，hide 和 show 管控文件和文件夹，所以隐藏路径不只是不可读，而是根本不出现在智能体看到的文件系统里。
- 可脚本化的策略引擎。 策略脚本能在任何危险操作运行前将其禁止，同一套栈还会拦截每次 VFS 操作和会话写入，所以文件和環境变量都不会泄漏。
- 通知已接入 VFS 和智能体。 外部变化会变成挂载点上的事件流，因此 Slack 里来了新回复，就会表现为虚拟文件系统中聊天文件的一次变更，智能体直接响应这次变更，不用重新扫描整棵目录树。

虚拟文件系统

Mirage 把一切都「挂载」成同一个虚拟文件系统，供 AI 智能体使用。每项服务并排放在同一个根目录下，遵循同一套 POSIX 语义。
| | VFS |
| 对象存储 | |
| 文件与文档 | |
| 消息与工作 | |
| 数据库与数据平台 | |
| 可观测性 | |

| Local and Remote | |

Agents reach it through the Python and TypeScript SDKs, the mirage CLI, or a real
mountpoint over FUSE and FSKit, then work it with the unix tools they already know,
like ls, grep, find and jq.

Virtual Command Line Tool

These command line tools are virtualized: Mirage answers git, slack or ntn
itself, so an agent drives the service without that program being installed on the
machine. Each one mimics the real tool, so an agent that knows the CLI needs nothing
new. Because they are virtual, the same tool can be installed more than once under
different names, each with its own credentials, so every agent gets exactly the
accounts it is given.

| | CLIs |
| Code | |
| Communication | |
| Work and Data | |

Virtual Runtime

Runtimes are virtualized the same way, and not only for coding languages. Any
command on the line can be redirected to a configured runtime, so Python might
run in-process with Monty while
another command, say kubectl, is sent to a remote machine over SSH. Which runtime
serves a given line can be decided by a
scripted runtime router.

| | Runtimes |
| Python | |
| JavaScript | |
| Sandboxes | |

Security

A profile decides what a session may run and what it may see. Commands are governed
by customizable allow, ask and deny rules, and paths by hide and show, so a
hidden file is not merely unreadable but absent from the filesystem the agent sees.
For anything those rules cannot express, a profile can name a policy script that runs
at the gate on every command and answers allow, deny or ask itself, though like every
rule it can only restrict and never grant. Separately, a host can register its own
policies on the policy engine, an
ordered stack the workspace consults on every command, VFS op and session write. See
the policy docs.

Authentication

Credentials and authentication integrate with the stores secrets already live in,
including AWS Secrets Manager, 1Password, Auth0 and dotenv, so an environment variable
in Mirage can resolve straight to a credential held in one of them.

| | Sources |
| Built in | |
| Custom | |

Installation

- Python ≥ 3.12 for the mirage-ai package and the mirage CLI
- Node.js 22.20+ on Node 22, 24.12+ on Node 24, or 25+ for the TypeScript SDK

Python

uv add mirage-ai # installs the mirage library and the mirage CLI binary
uv add 'mirage-ai[openai]' # OpenAI Agents adapter; each agent framework is an extra

TypeScript

npm install @struktoai/mirage-node # Node.js servers and CLIs
npm install @struktoai/mirage-browser # browser / edge runtimes
npm install @struktoai/mirage-vercel # Vercel AI adapter; each agent framework has its own package

Both runtime packages pull in @struktoai/mirage-core automatically.

CLI

npm install -g @struktoai/mirage-cli
or
uvx --from mirage-ai mirage
or
npx @struktoai/mirage-cli

To get started, see the quickstarts for
Python,
TypeScript and the
CLI.

Scriptable Policy

A profile can name policy scripts for what its rules cannot express. A script
reads the command as JSON, can open the files it names, and prints a deny, an
ask or nothing. This one disables rm, and a Python script whose code
deletes files:

import json, os

ctx = json.loads(os.environ["MIRAGE_POLICY_CTX"])

def deletes(path):
try:
code = open(path).read()
except OSError:
return False
return any(call in code for call in ("os.remove", "os.unlink", "shutil.rmtree"))

if ctx["command"] == "rm" or (
ctx["command"].startswith("python") and any(deletes(p) for p in ctx["paths"])
):
print(json.dumps({"kind": "deny", "reason": "deleting files is disabled"}))

Register it in a profile, here to run on Monty before every command:

ws = Workspace(
{"/s3": (S3VFS(S3Config(bucket="my-bucket")), MountMode.WRITE)},
profiles={
"analyst": {
"policy": {
"pre_command": [{"script": ScriptSource(Path("guard.py").read_text()), "runtime": "monty"}],
},
},
},
profile="analyst",
)

$ cat /s3/clean.py
import os
os.remove("/s3/report.txt")
$ rm /s3/report.txt
rm: Permission denied
$ python3 /s3/clean.py
python3: Permission denied

See policy scripts for
the other stages a script can answer at.

Embedded Terminal

Most of the time an agent does not need a sandbox, only a terminal-like
interface, and Mirage embeds one in an application server. Each terminal is a
Mirage session with its own working directory, environment and history, and Python
runs in-process on Monty, so a terminal starts with no container or VM. Here
it is in Express; the FastAPI version is in the
docs.

npm install @struktoai/mirage-node @pydantic/monty express

import express from 'express'
import { MontyRuntime, MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
{ '/work': new RAMVFS() },
{ mode: MountMode.EXEC, runtimes: [new MontyRuntime({ captures: ['python', 'python3'] })] },
)
const app = express()
app.use(express.json())

app.post('/sessions/:id', (req, res) => {
ws.createSession(req.params.id)
res.sendStatus(201)
})

app.post('/sessions/:id/run', async (req, res) => {
const r = await ws.shell(req.body.command, { sessionId: req.params.id })
res.json({ stdout: r.stdoutText, stderr: r.stderrText, exitCode: r.exitCode })
})

app.listen(3000, '127.0.0.1')

Contributors

Thanks to everyone who has contributed to Mirage.