strukto-ai/mirage

Mirage ist ein virtuelles Terminal für KI-Agenten. Das virtuelle Dateisystem liefert breiten Datenkontext, virtualisierte CLIs geben einem Agenten mehr Spielraum beim Werkzeugeinsatz, dynamische Laufzeitumgebungen senken die Kosten der darunterliegenden Infrastruktur und sparen Tokens, und eine feingranulare Kontrolle über die Aktionen eines Agenten und sogar darüber, was er sehen darf, sorgt für die beste Sicherheit. Zusammen bilden diese Teile ein einziges virtualisiertes Terminal, das die beste Agentenleistung, Kosteneffizienz und Sicherheit bietet.

ws = Workspace(
    {
        "/tmp":   (RAMVFS(), MountMode.EXEC),
        "/redis": (RedisVFS(url=redis_url), MountMode.WRITE),
        "/slack": (SlackVFS(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
    },
    # monty fängt python ab, Skripte laufen also sandboxed im Workspace
    runtimes=[MontyRuntime(captures=["python", "python3"]), "workspace"],
)

# ein einziges grep durchsucht alle Quellen
await ws.shell("grep -rln session /redis /tmp")

# führt ein Skript aus, das in Slack liegt, und schreibt den Bericht nach Redis
await ws.shell("python3 /slack/channels/general_.../files/example__F....py > /redis/report.txt")

# installiert eine typisierte CLI unter einem Kopfwort: per Name verteilt, nicht per Pfad,
# und über `man`, `type` und `which` auffindbar wie jedes andere Programm
ws.register_cli("slack", SLACK, {"token": slack_bot_token})
await ws.shell('slack send-message --channel general --text "report is up"')

Überblick

• Eine einheitliche virtuelle Terminal-Schnittstelle statt N SDKs und M MCPs. Jedes Backend spricht dieselbe Dateisystem-Semantik, sodass sich Pipelines über Dienste hinweg zusammensetzen lassen.
• Ein virtuelles Dateisystem über alle Quellen. S3, Google Drive, Slack, Gmail, Redis und die übrigen werden nebeneinander unter einer einzigen Wurzel eingehängt, sodass ein Agent sie alle über eine einheitliche Schnittstelle erreicht, mit den Unix-Werkzeugen, die er ohnehin kennt, etwa ls, grep, find und jq.
• Virtuelle Kommandozeilenwerkzeuge (CLIs). git, slack und ntn beantwortet Mirage selbst, sodass ein Agent den Dienst ohne jede Installation bedient, über verschiedene Laufzeitumgebungen und Maschinen hinweg; ein Werkzeug lässt sich zudem in zwei oder mehr virtualisieren, jedes unter eigenem Namen mit eigenen Zugangsdaten.
• Geroutete, dynamische Laufzeitumgebungen. Python, JavaScript und jeder andere Befehl kann an eine konfigurierte Laufzeitumgebung geschickt werden, im Prozess, in einer Sandbox oder entfernt, was Berechnung von Speicher entkoppelt und beide unabhängig voneinander austauschbar macht.
• Die virtualisierte Mirage-Shell. Sie verbindet Dateisystem, CLIs und Laufzeitumgebungen zu einer einzigen Kommandozeile, sodass Pipes, Umleitungen, Variablen, Jobs und History über alle drei hinweg funktionieren.
• Profile, die für Agenten entworfen sind. allow, ask und deny steuern Befehle und CLIs, hide und show steuern Dateien und Ordner, sodass ein verborgener Pfad nicht bloß unlesbar ist, sondern in dem Dateisystem, das der Agent sieht, gar nicht existiert.
• Eine skriptfähige Policy-Engine. Ein Policy-Skript kann jede gefährliche Aktion verhindern, bevor sie ausgeführt wird, und derselbe Stapel prüft jede VFS-Operation und jeden Session-Schreibzugriff, sodass weder eine Datei noch eine Umgebungsvariable nach außen dringt.
• Benachrichtigungen, die mit dem VFS und den Agenten verdrahtet sind. Externe Änderungen werden zu einem Ereignisstrom auf dem Mount, sodass eine neue Slack-Antwort als Änderung der Chat-Datei im virtuellen Dateisystem erscheint und der Agent darauf reagiert, statt den Baum erneut zu durchsuchen.

Architektur

Installation

• Python ≥ 3.12 für das Paket mirage-ai und die CLI mirage
• Node.js ≥ 20 für das TypeScript-SDK
• macOS oder Linux (FUSE-Mounts brauchen Unterstützung durch die Plattform)

Python

uv add mirage-ai              # installiert die Bibliothek `mirage` und die CLI `mirage`
uv add 'mirage-ai[openai]'    # OpenAI-Agents-Adapter; jedes Agent-Framework ist ein Extra

TypeScript

npm install @struktoai/mirage-node      # Node.js-Server und CLI
npm install @struktoai/mirage-browser   # Browser- und Edge-Laufzeitumgebungen
npm install @struktoai/mirage-vercel    # Vercel-AI-Adapter; jedes Agent-Framework hat ein eigenes Paket

Beide Runtime-Pakete installieren @struktoai/mirage-core automatisch mit.

CLI

npm install -g @struktoai/mirage-cli
# oder
uvx mirage-ai
# oder
npx @struktoai/mirage-cli

Schnellstart

Python

from mirage import Workspace
from mirage.vfs.ram import RAMVFS
from mirage.vfs.s3 import S3Config, S3VFS

ws = Workspace({
    "/data": RAMVFS(),
    "/s3":   S3VFS(S3Config(bucket="my-bucket")),
})

await ws.shell("cp /s3/report.csv /data/report.csv")
await ws.shell("grep alert /s3/data/log.jsonl | wc -l")

await ws.snapshot("demo.tar")

TypeScript

import { Workspace, RAMVFS, S3VFS } from '@struktoai/mirage-node'

const ws = new Workspace({
  '/data': new RAMVFS(),
  '/s3':   new S3VFS({ bucket: 'my-bucket' }),
})

await ws.shell('cp /s3/report.csv /data/report.csv')
await ws.shell('grep alert /s3/data/log.jsonl | wc -l')

await ws.snapshot('demo.tar')

CLI

mirage workspace create ws.yaml --id demo
mirage shell --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

Agenten-Frameworks

Mirage lässt sich in Agenten-Frameworks als Sandbox oder als Werkzeugschicht einbinden. POSIX-Operationen wie read sind außerdem pro VFS und pro Dateityp anpassbar: Mirage bringt keine Renderer für Dateiformate mit, ein Format wird also so dargestellt, wie es registriert wurde, und ein für ein VFS und eine Endung registrierter Befehl schlägt den generischen.

	Integrationen
Python	OpenAI Agents SDK, LangChain, Pydantic AI, Agno
TypeScript	Vercel AI SDK, OpenAI Agents SDK, LangChain, Mastra
Coding-Agenten	Claude Code, Codex, DeepSeek Harness, Grok Build, OpenCode, Pi

Cache

Jeder Workspace hat einen zweistufigen Cache, damit wiederholte Arbeit gegen entfernte Backends lokalen Zustand trifft statt das Netzwerk:

• Index-Cache: Auflistungen und Metadaten. Der erste Verzeichnisdurchlauf ruft die API auf; die folgenden bedient der Index, bis die TTL abläuft (standardmäßig 10 Minuten).
• Datei-Cache: Objekt-Bytes. Der erste Lesevorgang wird vom Ursprung gestreamt; nachfolgende Pipelines lesen aus dem Cache (standardmäßig 512 MB).

Beide Stufen nutzen standardmäßig den Arbeitsspeicher des Prozesses, ganz ohne Konfiguration. Ein Redis-Store teilt den Cache-Zustand zwischen Workern, Prozessen und Maschinen:

import { RedisFileCacheStore, S3VFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/s3': new S3VFS({ bucket: 'my-bucket' }) },
  {
    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', cacheLimit: '8GB' }),
    index: { type: 'redis', url: 'redis://localhost:6379/0', ttl: 600 },
  },
)

Mitwirkende

Dank an alle, die zu Mirage beigetragen haben.