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), запускают виртуальные CLI, направляют код в разные рантаймы и остаются в оболочке, контролируемой политиками.
Mirage — это фреймворк, встраиваемый в приложение, или отдельный CLI-инструмент?Это фреймворк, который вы запускаете внутри собственного приложения, а не отдельное приложение. Он связывает виртуальную файловую систему, виртуальные CLI и рантаймы в одну оболочку, которой управляет ваш агент.
Как начать использовать Mirage со своим агентом?Вы запускаете Mirage внутри своего приложения и монтируете источники данных (объектные хранилища, файлы, мессенджеры и т.д.) под его единым корнем виртуальной файловой системы; тестовые наборы в репозитории покрывают интеграции и для Python, и для TypeScript.
Нужен ли отдельный SDK или MCP-сервер для каждого сервиса, до которого агент должен добраться?Нет. Mirage заменяет SDK и MCP-серверы для отдельных сервисов одним унифицированным интерфейсом виртуального терминала, так что каждый бэкенд говорит на одной и той же семантике файловой системы.
Может ли мой агент видеть файлы или папки, которые я хочу от него скрыть?Нет — профили с правилами hide и show полностью убирают закрытые пути из поля зрения агента, а не просто блокируют чтение, а сценарный движок политик контролирует каждую операцию с файловой системой и каждую запись сессии.
Это работает с Claude Code или другими агентными фреймворками?Да — Mirage поставляется как плагин dsh, а в темах репозитория заявлена поддержка Claude Code и OpenAI Agents SDK наряду с общей интеграцией LLM-агентов.
Что помешает агенту совершить опасное действие, например удалить файлы?Сценарный движок политик может запретить любое опасное действие до его выполнения, и тот же стек контролирует каждую операцию виртуальной файловой системы и запись сессии, чтобы ничего не просочилось.
Может ли один и тот же базовый инструмент иметь два разных identity с отдельными учетными данными?Да — один реальный инструмент можно виртуализовать в два и более именованных CLI, каждый со своими учетными данными, и агент видит их как отдельные команды.
Как Mirage реагирует на внешние изменения, например новое сообщение в Slack?Внешние изменения приходят потоком событий в монтирование — новый ответ в Slack проявляется как изменение файла чата в виртуальной файловой системе, поэтому агент реагирует на него, а не пересканирует дерево.
В какие рантаймы можно направлять выполнение кода агента?Python, JavaScript и другие команды можно отправлять в настроенный рантайм — внутрипроцессный, изолированный (песочница) или удаленный — отделяя вычисления от хранения.
What are similar projects?capsule-fs, nono, xerj, cynative, computer, coop, DSH-taskboard, agentbox
Creator
strukto-ai
Size
112.7 MB
Stars
3.7K
Age
5mo
Commits · 90 Days