开发与运行时
mirage#dsh
strukto-ai/mirage/typescript/packages/dsh · ★ 3,785
把文件系统与 bash 提供者换成 mirage 虚拟工作区:文件工具与 shell 命令作用于挂载的资源(RAM、S3、Redis、Slack、Gmail、Notion、Postgres)而非宿主磁盘,支持按挂载点设置读/写/执行模式、按命令选择沙箱(进程内 monty、pyodide、quickjs;远程 docker、e2b、daytona),并可在虚拟终端中安装 CLI(git、gh、slack、linear、ntn、gws,或自行注册的程序树)作为命令头词。
README 正文来自英文版本。
查看 manifest 检查详情
安装
dsh plugin --profile web add github:strukto-ai/mirage#path:/typescript/packages/dshGitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试
安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗
项目说明
AI agents work in a terminal. Mirage is a virtual terminal that separates the terminal interface, the data storage and the computing machines. Mirage routes each command to the machine that fits it, across heterogeneous machines such as containers, microVMs, cloud sandboxes and SSH hosts. Files, CLIs and machines are added to it separately, which keeps it flexible and its infrastructure cost low, and lets agents work in the most efficient and safest way.
- Controllable. Decide what each agent reaches, which files it sees, which credentials its virtual filesystems and CLIs use without showing them, and which machine runs each of its programs.
- Scriptable. The whole terminal is defined in code or a config file, from its virtual filesystems, CLIs and machines to its rules, such as which commands need approval and how much output an agent gets back.
- Managed. Mirage manages the virtual terminal's infrastructure, composed from the chosen backends. The virtual filesystem sits on S3, Drive, a database or RAM, jobs and history on RAM, Redis or disk, and whole workspaces can be saved as snapshots. Every command an agent runs is recorded and can be sent to an OpenTelemetry backend as a trace.
Here is an example of launching Mirage inside an application:
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"]},
},
},
# python runs in process on monty, or on the e2b sandbox
machines={
"py": {"provider": "in_process", "runtime": "monty"},
"box": {"provider": "e2b", "sandbox_id": sandbox_id, "mount_type": "ssh", "captures": ["python", "python3"]},
},
# route the underlying computation: numpy lines run on the machine, the rest on monty
route_policy=lambda ctx: "box" if "numpy" in ctx.line else None,
)
# Add an agent using the analyst profile
alice = await ws.session("alice", profile="analyst")
# one grep sweeps S3, Slack and Gmail, on each service's own search where it has one
await alice.shell("grep -rlw invoice /s3 /slack /gmail")
# run a script that lives in Slack on monty, file the report into S3
await alice.shell("python3 /slack/channels/general__C0123/2026-10-21/files/report__F0456.py > /s3/report.txt")
# numpy is not in monty, so the route policy sends this line to e2b
await alice.shell("python3 -c 'import numpy; print(numpy.arange(10).sum())'")
And what alice sees in the 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
About
- Unified virtual terminal interface, not N SDKs and M MCPs. Every backend speaks the same filesystem semantics, so pipelines compose across services.
- A virtual filesystem over every source. S3, Google Drive, Slack, Gmail, Redis and the rest mount side by side under one root, so an agent reaches all of them through a unified interface with the unix tools it already knows, like
ls,grep,findandjq. - Virtual command line tools (CLIs).
git,slackandntnare answered by Mirage itself, so an agent drives the service with nothing installed, across different runtimes and machines, and one tool can be virtualized into two or more, each under its own name with its own credentials. - Routed, dynamic machines. Python, JavaScript and any other command can be sent to a configured machine, in process, sandboxed or remote, which decouples computation from storage and lets either change without touching the other.
- The virtualized Mirage shell. It binds the filesystem, the CLIs and the machines into one command line, so pipes, redirection, variables, jobs and history work across all three.
- Lightweight by design. A workspace, the virtual terminal itself, takes about 100 KB of memory and each new session about 10 KB, so one process serves many agents without a container or VM per agent.
- Profiles designed for agents.
allow,askanddenygovern commands and CLIs, whilehideandshowgovern files and folders, so a hidden path is not merely unreadable but absent from the filesystem the agent sees. - A scriptable policy engine. A policy script can prohibit any dangerous action before it runs, and the same stack gates every VFS op and session write, so neither a file nor an environment variable leaks.
- Notifications wired into the VFS and agents. External changes become an event stream on the mount, so a new Slack reply surfaces as a change to the chat file in the virtual filesystem, and the agent reacts to it instead of rescanning the tree.
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.
| VFS | |
|---|---|
| Object Storage | |
| Files and Documents | |
| Messaging and Work | |
| Databases and Data Platforms | |
| Observability | |
| 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 Machine
Machines are virtualized the same way, and not only for coding languages. Any
command on the line can be sent to a configured machine, so Python might run
in-process with Monty while
another command, say kubectl, runs on a remote machine over SSH. Which machine
serves a given line can be decided by a
scripted machine router.
| Machines |
|---|
…