Zum Hauptinhalt springen
S

mirage (dsh)

strukto-ai/mirage/typescript/packages/dsh

Ersetzt die Dateisystem- und Bash-Provider durch einen virtuellen mirage-Arbeitsbereich: Datei-Tools und Shell-Befehle laufen über eingebundene Ressourcen (RAM, S3, Redis, Slack, Gmail, Notion, Postgres) anstelle der Host-Festplatte, mit Lese-/Schreib-/Ausführungsmodi je Mount, Sandbox-Routing je Befehl (monty, pyodide, quickjs im Prozess; docker, e2b, daytona remote) und installierten CLIs (git, gh, slack, linear, ntn, gws oder eine selbst registrierte) als Kopfwörter im virtuellen Terminal.

Installation

dsh plugin --profile web add github:strukto-ai/mirage

Dieses Plugin befindet sich im Unterverzeichnis typescript/packages/dsh des Repositorys.

README

Mirage: A Virtual Terminal for AI Agents AgentVFS: the open, vendor-neutral virtual filesystem interface for AI agents

Status: experimental DOI 10.5281/zenodo.23504502 WeChat community
Python docs
TypeScript docs

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

LLMs are post-trained in terminal environments, so AI agents are most familiar with the terminal interface. But a terminal today is bound to a single machine and its operating system kernel, with its files and its computation on that same machine.

Mirage is a virtual terminal for AI agents that separates the terminal interface from the data storage and the computing machines. It virtualizes the shell, the filesystem, the CLIs and the machines. Each virtual terminal starts with only KBs of memory, so AI agents can use terminal environments everywhere, inside an application, a mobile app, a browser tab, a FastAPI or Express server, and even an edge device such as a Raspberry Pi.

Mirage over three virtual filesystems (S3, Slack, Google Drive), three virtual CLIs (gh, linear, deepwiki-mcp), three VMs (Monty, an E2B sandbox, an EC2 GPU) and a policy layer: one grep searches all three filesystems, the three CLIs feed one grep, one pipeline runs a stage on each VM, and policy refuses one line that reads a hidden .pem key, deletes from the read-only /s3 mount and merges a PR

  • Controllable. Each agent gets only the files, commands, credentials and machines its profile allows.
  • Scriptable. The whole terminal is defined in code or one config file, from its filesystems, CLIs and machines to its rules.
  • Managed. State lives on infrastructure that already runs, such as RAM, disk, Redis or S3, and every command is recorded and can be exported as an OpenTelemetry trace.
  • Lightweight. Each workspace takes only KBs of memory and Mirage is async from the shell down to each service call, so one process serves many agents at once. It can be deployed almost everywhere, to a Python or TypeScript server, a browser tab, a Cloudflare Worker or a Raspberry Pi.

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

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, find and jq.
  • Virtual command line tools (CLIs). git, slack and ntn are 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, ask and deny govern commands and CLIs, while hide and show govern 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.

Unified 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 StorageAmazon 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 DocumentsGoogle Drive  Google Docs  Google Sheets  Google Slides  OneDrive  SharePoint  Box  Dropbox  Nextcloud TiDB Cloud Filesystem
Messaging and WorkSlack  Discord  Gmail  IMAP / SMTP email  GitHub  Linear  Notion  Trello  Google Calendar
Databases and Data PlatformsPostgreSQL  MongoDB  Redis Upstash Redis SQL Airtable  LanceDB  Qdrant  Chroma  Mem0  Hugging Face Datasets  Hugging Face Models  Hugging Face Spaces  Databricks Volumes  Dify
ObservabilityLangfuse  Jaeger Weights & Biases
Local and RemoteRAM  Disk  OPFS  SSH

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 CLIs

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
Codegit  gh
Communicationslack  discord  himalaya
Work and Datalinear  ntn trello airtable  gws  hf office pdftotext pdfinfo

Virtual Machines

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
PythonMonty  WASI CPython on wasmtime  Pyodide  sandlock  Host CPython
JavaScriptQuickJS, serving node and js JavaScript TypeScript
MachinesDocker Kubernetes  E2B  Daytona Cloudflare Container boxd  smolVM Microsandbox Apple Container  SSH

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.

Service Credentials

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

Sources
Built inEnvironment dotenv
Custom1Password AWS Secrets Manager

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
uv add 'mirage-ai[monty]'     # Monty, the in-process Python runtime the examples run on

TypeScript

npm install @struktoai/mirage-node      # Node.js servers and CLIs
npm install @struktoai/mirage-browser   # browser / edge runtimes

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's pre_command takes the command, can open the files it names, and returns a deny, an ask or None. This one disables rm, and a Python script whose code deletes files:

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"))


def pre_command(ctx):
    if ctx["command"] == "rm" or (
        ctx["command"].startswith("python") and any(deletes(p) for p in ctx["paths"])
    ):
        return {"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.

Examples

  • In-Process Terminal. A terminal for agents inside your application, even within a FastAPI or Express server, without a fixed machine or sandbox.
  • Multi-machine Terminal. A unified virtual terminal across different machines that runs each task on the machine that fits it, so AI agents perform tasks more efficiently and at lower cost.
  • Secured Terminal. Decide which files an agent sees, which commands and CLIs it runs and which credentials its tools use, in one workspace config.
  • Infra-agnostic Terminal. A virtual terminal not tied to any fixed infrastructure, keeping its files, sessions and command logs on whichever backends are already in place.

Contributors

Thanks to everyone who has contributed to Mirage.

Mirage contributors

Ähnliche Plugins