Skip to content
Back to search

mirage

The World's First Virtual Terminal for AI Agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/strukto-ai/mirage with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/strukto-ai/mirage'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/strukto-ai--mirage/badge.svg)](/listings/strukto-ai--mirage)

HTML

<a href="/listings/strukto-ai--mirage"><img src="/api/listings/strukto-ai--mirage/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

- **Python** ≥ 3.11 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

curl -fsSL https://strukto.ai/mirage/install.sh | sh
# or
npm install -g @struktoai/mirage-cli
# or
uvx --from mirage-ai mirage
# or
npx @struktoai/mirage-cli

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "mirage",
  3. "description": "Mirage filesystem tools and backend authoring skills for Claude Code.",
  4. "owner": {
  5. "name": "Strukto.AI"
  6. },
  7. "plugins": [
  8. {
  9. "name": "mirage",
  10. "source": "./plugins/mirage",
  11. "description": "Use Mirage-mounted cloud, database, and local data as a virtual filesystem."
  12. }
  13. ]
  14. }
README.md · README · 315 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">
  2. <a href="https://www.strukto.ai/mirage">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="assets/mirage-header-dark.svg">
  5. <img src="assets/mirage-header-light.svg" width="100%" alt="Mirage: A Virtual Terminal for AI Agents" />
  6. </picture>
  7. </a>
  8. <a href="https://agentvfs.org">
  9. <picture>
  10. <source media="(max-width: 767px) and (prefers-color-scheme: dark)" srcset="assets/agentvfs-banner-narrow-dark.svg">
  11. <source media="(max-width: 767px)" srcset="assets/agentvfs-banner-narrow-light.svg">
  12. <source media="(prefers-color-scheme: dark)" srcset="assets/agentvfs-banner-dark.svg">
  13. <img src="assets/agentvfs-banner-light.svg" width="100%" alt="AgentVFS: the open, vendor-neutral virtual filesystem interface for AI agents" />
  14. </picture>
  15. </a>
  16. </h1>
  17. <p align="center">
  18. <a href="https://docs.mirage.strukto.ai" alt="Documentation">
  19. <img src="https://img.shields.io/badge/mirage-docs-0C0C0C?labelColor=F0ECE2" /></a>
  20. <a href="https://github.com/strukto-ai/mirage/releases" alt="Status">
  21. <img src="https://img.shields.io/badge/status-preview-0C0C0C?labelColor=F0ECE2" alt="Status: preview" /></a>
  22. <a href="https://www.strukto.ai" alt="Website">
  23. <img src="https://img.shields.io/badge/made by-strukto.ai-0C0C0C?labelColor=F0ECE2" /></a>
  24. <a href="https://github.com/strukto-ai/mirage/blob/main/LICENSE" alt="License">
  25. <img src="https://img.shields.io/badge/license-Apache--2.0-0C0C0C?labelColor=F0ECE2" /></a>
  26. <a href="https://doi.org/10.5281/zenodo.23504502" alt="DOI">
  27. <img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23504502-0C0C0C?labelColor=F0ECE2" alt="DOI 10.5281/zenodo.23504502" /></a>
  28. <a href="https://discord.gg/u8BPQ65KsS" alt="Discord">
  29. <img src="https://img.shields.io/badge/discord-join-0C0C0C?labelColor=F0ECE2&logo=discord&logoColor=0C0C0C" /></a>
  30. <a href="assets/wechat-qr-code.jpg" aria-label="WeChat community">
  31. <img src="https://img.shields.io/badge/wechat-join-0C0C0C?labelColor=F0ECE2&logo=wechat&logoColor=0C0C0C" alt="WeChat community" /></a>
  32. <br/>
  33. <a href="https://docs.mirage.strukto.ai/python/quickstart" alt="Python docs">
  34. <img src="https://img.shields.io/badge/python-docs-0C0C0C?labelColor=F0ECE2&logo=python&logoColor=0C0C0C" alt="Python docs"></a>
  35. <a href="https://pypi.org/project/mirage-ai/" alt="PyPI Version">
  36. <img src="https://img.shields.io/pypi/v/mirage-ai.svg?color=0C0C0C&labelColor=F0ECE2"/></a>
  37. <br/>
  38. <a href="https://docs.mirage.strukto.ai/typescript/quickstart" alt="TypeScript docs">
  39. <img src="https://img.shields.io/badge/typescript-docs-0C0C0C?labelColor=F0ECE2&logo=typescript&logoColor=0C0C0C" alt="TypeScript docs"></a>
  40. <a href="https://www.npmjs.com/package/@struktoai/mirage-node" alt="NPM Version">
  41. <img src="https://img.shields.io/npm/v/@struktoai/mirage-node.svg?color=0C0C0C&labelColor=F0ECE2"/></a>
  42. </p>
  43. <p align="center">
  44. <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-F0ECE2"></a>
  45. <a href="./readme/README.zh-CN.md"><img alt="简体中文 README" src="https://img.shields.io/badge/简体中文-F0ECE2"></a>
  46. <a href="./readme/README.zh-TW.md"><img alt="繁體中文 README" src="https://img.shields.io/badge/繁體中文-F0ECE2"></a>
  47. <a href="./readme/README.fr.md"><img alt="README en Français" src="https://img.shields.io/badge/Français-F0ECE2"></a>
  48. <a href="./readme/README.de.md"><img alt="README auf Deutsch" src="https://img.shields.io/badge/Deutsch-F0ECE2"></a>
  49. <a href="./readme/README.vi.md"><img alt="README Tiếng Việt" src="https://img.shields.io/badge/Ti%E1%BA%BFng%20Vi%E1%BB%87t-F0ECE2"></a>
  50. <a href="./readme/README.ko.md"><img alt="README 한국어" src="https://img.shields.io/badge/%ED%95%9C%EA%B5%AD%EC%96%B4-F0ECE2"></a>
  51. </p>
  52. 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.
  53. <p align="center">
  54. <picture>
  55. <source media="(prefers-color-scheme: dark)" srcset="assets/mirage-terminal-dark.svg">
  56. <img src="assets/mirage-terminal-light.svg" alt="Mirage over three virtual filesystems (S3, Slack, Google Drive), three virtual CLIs (gh, linear, deepwiki-mcp) and three VMs (Monty, an E2B sandbox, an EC2 GPU): one grep searches all three filesystems, the three CLIs feed one grep, and one pipeline runs a stage on each VM" width="100%">
  57. </picture>
  58. </p>
  59. - **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.
  60. - **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.
  61. - **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.
  62. <p align="center">
  63. <picture>
  64. <source media="(prefers-color-scheme: dark)" srcset="assets/mirage-arch-dark.svg">
  65. <img src="assets/mirage-arch-light.svg" alt="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" width="100%">
  66. </picture>
  67. </p>
  68. Here is an example of launching Mirage inside an application:
  69. ```python
  70. ws = Workspace(
  71. {
  72. "/s3": (S3VFS(S3Config(bucket="my-bucket")), MountMode.WRITE),
  73. "/slack": (SlackVFS(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
  74. "/gmail": (GmailVFS(GmailConfig(**google_credentials)), MountMode.READ),
  75. },
  76. # Install the Slack CLI, run by name and listed by `man` and `which` like any program
  77. clis={"slack": (SLACK, {"token": slack_bot_token})},
  78. # the analyst profile hides /s3/secrets and denies posting to Slack and curl
  79. profiles={
  80. "analyst": {
  81. "paths": {"hide": ["/s3/secrets"]},
  82. "commands": {"deny": ["slack send-message", "curl"]},
  83. },
  84. },
  85. # python runs in process on monty, or on the e2b sandbox
  86. machines={
  87. "py": {"provider": "in_process", "runtime": "monty"},
  88. "box": {"provider": "e2b", "sandbox_id": sandbox_id, "mount_type": "ssh", "captures": ["python", "python3"]},
  89. },
  90. # route the underlying computation: numpy lines run on the machine, the rest on monty
  91. route_policy=lambda ctx: "box" if "numpy" in ctx.line else None,
  92. )
  93. # Add an agent using the analyst profile
  94. alice = await ws.session("alice", profile="analyst")
  95. # one grep sweeps S3, Slack and Gmail, on each service's own search where it has one
  96. await alice.shell("grep -rlw invoice /s3 /slack /gmail")
  97. # run a script that lives in Slack on monty, file the report into S3
  98. await alice.shell("python3 /slack/channels/general__C0123/2026-10-21/files/report__F0456.py > /s3/report.txt")
  99. # numpy is not in monty, so the route policy sends this line to e2b
  100. await alice.shell("python3 -c 'import numpy; print(numpy.arange(10).sum())'")
  101. ```
  102. And what `alice` sees in the shell:
  103. ```console
  104. $ grep -rlw invoice /s3 /slack /gmail
  105. /s3/billing/2026-10.csv
  106. /gmail/INBOX/2026-10-21/Invoice_1042__18f3a9c2b7d1e0f4.gmail.json
  107. $ ls /s3
  108. billing
  109. report.txt
  110. $ cat /s3/secrets/aws.txt
  111. cat: /s3/secrets/aws.txt: No such file or directory
  112. $ slack send-message --channel general --text "report is up"
  113. slack: Permission denied
  114. ```
  115. ## About
  116. - **Unified virtual terminal interface, not N SDKs and M MCPs.** Every backend speaks the same filesystem semantics, so pipelines compose across services.
  117. - **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`.
  118. - **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.
  119. - **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.
  120. - **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.
  121. - **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.
  122. - **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.
  123. - **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.
  124. - **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.
  125. ## Virtual Filesystem
  126. Everything [Mirage](https://www.strukto.ai/mirage) "mounts" as one unified virtual filesystem for AI agents. Each
  127. service sits side-by-side under a single root and answers the same POSIX semantics.
  128. | | VFS |
  129. | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  130. | **Object Storage** | <a href="https://docs.mirage.strukto.ai/home/setup/s3"><img src="https://api.iconify.design/logos/aws-s3.svg" width="20" height="20" alt="Amazon S3" title="Amazon S3" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/r2"><img src="https://cdn.simpleicons.org/cloudflare" width="20" height="20" alt="Cloudflare R2" title="Cloudflare R2" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/gcs"><img src="https://api.iconify.design/logos/google-cloud.svg" width="25" height="20" alt="Google Cloud Storage" title="Google Cloud Storage" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/oci"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/oracle.svg" width="32" height="20" alt="Oracle OCI" title="Oracle OCI" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/supabase"><img src="https://api.iconify.design/logos/supabase-icon.svg" width="19" height="20" alt="Supabase Storage" title="Supabase Storage" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/minio"><img src="https://cdn.simpleicons.org/minio" width="20" height="20" alt="MinIO" title="MinIO" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/ceph"><img src="https://cdn.simpleicons.org/ceph" width="20" height="20" alt="Ceph" title="Ceph" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/seaweedfs"><img src="assets/icons/seaweedfs.svg" width="20" height="20" alt="SeaweedFS" title="SeaweedFS" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/wasabi"><img src="https://cdn.simpleicons.org/wasabi" width="20" height="20" alt="Wasabi" title="Wasabi" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/backblaze"><img src="https://cdn.simpleicons.org/backblaze" width="20" height="20" alt="Backblaze B2" title="Backblaze B2" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/digitalocean"><img src="https://cdn.simpleicons.org/digitalocean" width="20" height="20" alt="DigitalOcean Spaces" title="DigitalOcean Spaces" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/aliyun"><img src="https://cdn.simpleicons.org/alibabacloud" width="20" height="20" alt="Alibaba Cloud OSS" title="Alibaba Cloud OSS" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/tencent"><img src="assets/icons/tencent.png" width="20" height="20" alt="Tencent Cloud COS" title="Tencent Cloud COS" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/scaleway"><img src="https://cdn.simpleicons.org/scaleway" width="20" height="20" alt="Scaleway" title="Scaleway" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/qingstor"><img src="assets/icons/qingstor.png" width="20" height="20" alt="QingStor" title="QingStor" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/hf_buckets"><img src="https://cdn.simpleicons.org/huggingface" width="20" height="20" alt="Hugging Face Buckets" title="Hugging Face Buckets" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/gridfs"><img src="https://cdn.simpleicons.org/mongodb" width="20" height="20" alt="GridFS" title="GridFS" /></a> |
  131. | **Files and Documents** | <a href="https://docs.mirage.strukto.ai/home/setup/google"><img src="https://cdn.simpleicons.org/googledrive" width="20" height="20" alt="Google Drive" title="Google Drive" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/google"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/google-docs.svg" width="14" height="20" alt="Google Docs" title="Google Docs" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/google"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/google-sheets.svg" width="15" height="20" alt="Google Sheets" title="Google Sheets" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/google"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/google-slides.svg" width="15" height="20" alt="Google Slides" title="Google Slides" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/onedrive"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/microsoft-onedrive.svg" width="30" height="20" alt="OneDrive" title="OneDrive" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/sharepoint"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/microsoft-sharepoint.svg" width="20" height="20" alt="SharePoint" title="SharePoint" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/box"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/box.svg" width="20" height="20" alt="Box" title="Box" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/dropbox"><img src="https://cdn.simpleicons.org/dropbox" width="20" height="20" alt="Dropbox" title="Dropbox" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/nextcloud"><img src="https://cdn.simpleicons.org/nextcloud" width="20" height="20" alt="Nextcloud" title="Nextcloud" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/tidb"><img src="https://cdn.simpleicons.org/tidb" width="20" height="20" alt="TiDB Cloud Filesystem" title="TiDB Cloud Filesystem" /></a> |
  132. | **Messaging and Work** | <a href="https://docs.mirage.strukto.ai/home/setup/slack"><img src="https://api.iconify.design/logos/slack-icon.svg" width="20" height="20" alt="Slack" title="Slack" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/discord"><img src="https://cdn.simpleicons.org/discord" width="20" height="20" alt="Discord" title="Discord" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/google"><img src="https://cdn.simpleicons.org/gmail" width="20" height="20" alt="Gmail" title="Gmail" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/email"><img src="https://api.iconify.design/lucide/mail.svg?color=%23888888" width="20" height="20" alt="IMAP / SMTP email" title="IMAP / SMTP email" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/github"><img src="https://cdn.simpleicons.org/github/181717/e6edf3" width="20" height="20" alt="GitHub" title="GitHub" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/linear"><img src="https://cdn.simpleicons.org/linear" width="20" height="20" alt="Linear" title="Linear" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/notion"><img src="https://cdn.simpleicons.org/notion/000000/e6edf3" width="20" height="20" alt="Notion" title="Notion" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/trello"><img src="https://cdn.simpleicons.org/trello" width="20" height="20" alt="Trello" title="Trello" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/gcal"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/google-calendar.svg" width="20" height="20" alt="Google Calendar" title="Google Calendar" /></a> |
  133. | **Databases and Data Platforms** | <a href="https://docs.mirage.strukto.ai/home/setup/postgres"><img src="https://cdn.simpleicons.org/postgresql" width="20" height="20" alt="PostgreSQL" title="PostgreSQL" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/mongodb"><img src="https://cdn.simpleicons.org/mongodb" width="20" height="20" alt="MongoDB" title="MongoDB" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/redis"><img src="https://cdn.simpleicons.org/redis" width="20" height="20" alt="Redis" title="Redis" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/redis"><img src="https://cdn.simpleicons.org/upstash" width="20" height="20" alt="Upstash Redis" title="Upstash Redis" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/sql"><img src="https://api.iconify.design/lucide/database.svg?color=%23888888" width="20" height="20" alt="SQL" title="SQL" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/airtable"><img src="https://cdn.simpleicons.org/airtable" width="20" height="20" alt="Airtable" title="Airtable" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/lancedb"><img src="assets/icons/lancedb.png" width="20" height="20" alt="LanceDB" title="LanceDB" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/qdrant"><img src="https://cdn.simpleicons.org/qdrant" width="20" height="20" alt="Qdrant" title="Qdrant" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/chroma"><img src="https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/chroma.svg" width="31" height="20" alt="Chroma" title="Chroma" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/mem0"><img src="docs/images/mem0.svg" width="20" height="20" alt="Mem0" title="Mem0" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/hf_datasets"><img src="https://cdn.simpleicons.org/huggingface" width="20" height="20" alt="Hugging Face Datasets" title="Hugging Face Datasets" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/hf_models"><img src="https://cdn.simpleicons.org/huggingface" width="20" height="20" alt="Hugging Face Models" title="Hugging Face Models" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/hf_spaces"><img src="https://cdn.simpleicons.org/huggingface" width="20" height="20" alt="Hugging Face Spaces" title="Hugging Face Spaces" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/databricks"><img src="https://cdn.simpleicons.org/databricks" width="20" height="20" alt="Databricks Volumes" title="Databricks Volumes" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/dify"><img src="https://cdn.simpleicons.org/dify" width="20" height="20" alt="Dify" title="Dify" /></a> |
  134. | **Observability** | <a href="https://docs.mirage.strukto.ai/home/setup/langfuse"><img src="docs/images/langfuse-logo.svg" width="20" height="20" alt="Langfuse" title="Langfuse" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/jaeger"><img src="https://cdn.simpleicons.org/jaeger" width="20" height="20" alt="Jaeger" title="Jaeger" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/wandb"><img src="https://cdn.simpleicons.org/weightsandbiases" width="20" height="20" alt="Weights & Biases" title="Weights & Biases" /></a> |
  135. | **Local and Remote** | <a href="https://docs.mirage.strukto.ai/home/setup/ram"><img src="https://api.iconify.design/lucide/memory-stick.svg?color=%23888888" width="20" height="20" alt="RAM" title="RAM" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/disk"><img src="https://api.iconify.design/lucide/hard-drive.svg?color=%23888888" width="20" height="20" alt="Disk" title="Disk" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/opfs"><img src="https://api.iconify.design/lucide/folder-lock.svg?color=%23888888" width="20" height="20" alt="OPFS" title="OPFS" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/ssh"><img src="docs/images/ssh-logo.svg" width="20" height="20" alt="SSH" title="SSH" /></a> |
  136. Agents reach it through the Python and TypeScript SDKs, the `mirage` CLI, or a real
  137. mountpoint over FUSE and FSKit, then work it with the unix tools they already know,
  138. like `ls`, `grep`, `find` and `jq`.
  139. ## Virtual Command Line Tool
  140. These command line tools are virtualized: [Mirage](https://www.strukto.ai/mirage) answers `git`, `slack` or `ntn`
  141. itself, so an agent drives the service without that program being installed on the
  142. machine. Each one mimics the real tool, so an agent that knows the CLI needs nothing
  143. new. Because they are virtual, the same tool can be installed more than once under
  144. different names, each with its own credentials, so every agent gets exactly the
  145. accounts it is given.
  146. | | CLIs |
  147. | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  148. | **Code** | <a href="https://docs.mirage.strukto.ai/home/setup/cli/git"><img src="https://cdn.simpleicons.org/git" width="20" height="20" alt="git" title="git" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/cli/gh"><img src="https://cdn.simpleicons.org/github/181717/e6edf3" width="20" height="20" alt="gh" title="gh" /></a> |
  149. | **Communication** | <a href="https://docs.mirage.strukto.ai/home/setup/cli/slack"><img src="https://api.iconify.design/logos/slack-icon.svg" width="20" height="20" alt="slack" title="slack" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/cli/discord"><img src="https://cdn.simpleicons.org/discord" width="20" height="20" alt="discord" title="discord" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/cli/himalaya"><img src="assets/icons/himalaya.png" width="20" height="20" alt="himalaya" title="himalaya" /></a> |
  150. | **Work and Data** | <a href="https://docs.mirage.strukto.ai/home/setup/cli/linear"><img src="https://cdn.simpleicons.org/linear" width="20" height="20" alt="linear" title="linear" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/cli/ntn"><img src="https://cdn.simpleicons.org/notion/000000/e6edf3" width="20" height="20" alt="ntn" title="ntn" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/cli/trello"><img src="https://cdn.simpleicons.org/trello" width="20" height="20" alt="trello" title="trello" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/cli/airtable"><img src="https://cdn.simpleicons.org/airtable" width="20" height="20" alt="airtable" title="airtable" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/cli/gws"><img src="https://cdn.simpleicons.org/google" width="20" height="20" alt="gws" title="gws" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/cli/hf"><img src="https://cdn.simpleicons.org/huggingface" width="20" height="20" alt="hf" title="hf" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/cli/office"><img src="https://api.iconify.design/lucide/file-spreadsheet.svg?color=%23888888" width="20" height="20" alt="office" title="office" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/cli/pdftotext"><img src="https://api.iconify.design/lucide/file-text.svg?color=%23888888" width="20" height="20" alt="pdftotext" title="pdftotext" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/cli/pdfinfo"><img src="https://api.iconify.design/lucide/file-search.svg?color=%23888888" width="20" height="20" alt="pdfinfo" title="pdfinfo" /></a> |
  151. ## Virtual Machine
  152. Machines are virtualized the same way, and not only for coding languages. Any
  153. command on the line can be sent to a configured machine, so Python might run
  154. in-process with [Monty](https://pydantic.dev/articles/pydantic-monty) while
  155. another command, say `kubectl`, runs on a remote machine over SSH. Which machine
  156. serves a given line can be decided by a
  157. [scripted machine router](https://docs.mirage.strukto.ai/home/policy/route-machine).
  158. | | Machines |
  159. | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  160. | **Python** | <a href="https://docs.mirage.strukto.ai/home/setup/runtime/monty"><img src="https://cdn.simpleicons.org/pydantic" width="20" height="20" alt="Monty" title="Monty" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/runtime/wasi"><img src="https://cdn.simpleicons.org/webassembly" width="20" height="20" alt="WASI CPython on wasmtime" title="WASI CPython on wasmtime" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/runtime/pyodide"><img src="assets/icons/pyodide.svg" width="56" height="20" alt="Pyodide" title="Pyodide" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/machine/host"><img src="docs/images/sandlock-logo.svg" width="20" height="20" alt="sandlock" title="sandlock" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/machine/host"><img src="https://cdn.simpleicons.org/python" width="20" height="20" alt="Host CPython" title="Host CPython" /></a> |
  161. | **JavaScript** | <a href="https://docs.mirage.strukto.ai/home/setup/runtime/quickjs"><img src="assets/icons/quickjs.png" width="20" height="20" alt="QuickJS, serving node and js" title="QuickJS, serving node and js" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/runtime/quickjs"><img src="https://cdn.simpleicons.org/javascript" width="20" height="20" alt="JavaScript" title="JavaScript" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/runtime/quickjs"><img src="https://cdn.simpleicons.org/typescript" width="20" height="20" alt="TypeScript" title="TypeScript" /></a> |
  162. | **Machines** | <a href="https://docs.mirage.strukto.ai/home/setup/machine/docker"><img src="https://cdn.simpleicons.org/docker" width="20" height="20" alt="Docker" title="Docker" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/machine/kubernetes"><img src="https://cdn.simpleicons.org/kubernetes" width="20" height="20" alt="Kubernetes" title="Kubernetes" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/machine/e2b"><img src="docs/images/e2b-logo.svg" width="20" height="20" alt="E2B" title="E2B" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/machine/daytona"><img src="docs/images/daytona-logo.svg" width="20" height="20" alt="Daytona" title="Daytona" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/machine/cloudflare_container"><img src="https://cdn.simpleicons.org/cloudflare" width="20" height="20" alt="Cloudflare Container" title="Cloudflare Container" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/machine/boxd"><img src="docs/images/boxd-logo.svg" width="20" height="20" alt="boxd" title="boxd" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/machine/smolvm"><img src="docs/images/smolvm-logo.svg" width="20" height="20" alt="smolVM" title="smolVM" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/machine/microsandbox"><img src="docs/images/microsandbox-logo.svg" width="20" height="20" alt="Microsandbox" title="Microsandbox" /></a> <a href="https://docs.mirage.strukto.ai/home/setup/machine/apple_container"><img src="https://cdn.simpleicons.org/apple/000000/e6edf3" width="20" height="20" alt="Apple Container" title="Apple Container" /></a>  <a href="https://docs.mirage.strukto.ai/home/setup/machine/ssh"><img src="docs/images/ssh-logo.svg" width="20" height="20" alt="SSH" title="SSH" /></a> |
  163. ## Security
  164. A profile decides what a session may run and what it may see. Commands are governed
  165. by customizable `allow`, `ask` and `deny` rules, and paths by `hide` and `show`, so a
  166. hidden file is not merely unreadable but absent from the filesystem the agent sees.
  167. For anything those rules cannot express, a profile can name a policy script that runs
  168. at the gate on every command and answers allow, deny or ask itself, though like every
  169. rule it can only restrict and never grant. Separately, a host can register its own
  170. policies on the [policy engine](https://docs.mirage.strukto.ai/home/policy/policies), an
  171. ordered stack the workspace consults on every command, VFS op and session write. See
  172. the [policy docs](https://docs.mirage.strukto.ai/home/policy/overview).
  173. ## Service Credentials
  174. Service credentials integrate with the stores secrets already live in,
  175. including AWS Secrets Manager, 1Password and dotenv, so an environment variable
  176. in Mirage can resolve straight to a credential held in one of them.
  177. | | Sources |
  178. | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  179. | **Built in** | <a href="https://docs.mirage.strukto.ai/home/service-credentials#sources"><img src="assets/icons/terminal.svg" width="20" height="20" alt="Environment" title="Environment" /></a> <a href="https://docs.mirage.strukto.ai/home/service-credentials#sources"><img src="https://cdn.simpleicons.org/dotenv" width="20" height="20" alt="dotenv" title="dotenv" /></a> |
  180. | **Custom** | <a href="https://docs.mirage.strukto.ai/home/service-credentials/1password"><img src="https://cdn.simpleicons.org/1password" width="20" height="20" alt="1Password" title="1Password" /></a> <a href="https://docs.mirage.strukto.ai/home/service-credentials/aws-secrets-manager"><img src="https://api.iconify.design/logos/aws-secrets-manager.svg" width="20" height="20" alt="AWS Secrets Manager" title="AWS Secrets Manager" /></a> |
  181. ## Installation
  182. - **Python** ≥ 3.12 for the `mirage-ai` package and the `mirage` CLI
  183. - **Node.js** 22.20+ on Node 22, 24.12+ on Node 24, or 25+ for the TypeScript SDK
  184. ### Python
  185. ```bash
  186. uv add mirage-ai # installs the `mirage` library and the `mirage` CLI binary
  187. uv add 'mirage-ai[openai]' # OpenAI Agents adapter; each agent framework is an extra
  188. uv add 'mirage-ai[monty]' # Monty, the in-process Python runtime the examples run on
  189. ```
  190. ### TypeScript
  191. ```bash
  192. npm install @struktoai/mirage-node # Node.js servers and CLIs
  193. npm install @struktoai/mirage-browser # browser / edge runtimes
  194. ```
  195. Both runtime packages pull in `@struktoai/mirage-core` automatically.
  196. ### CLI
  197. ```bash
  198. npm install -g @struktoai/mirage-cli
  199. # or
  200. uvx --from mirage-ai mirage
  201. # or
  202. npx @struktoai/mirage-cli
  203. ```
  204. To get started, see the quickstarts for
  205. [Python](https://docs.mirage.strukto.ai/python/quickstart),
  206. [TypeScript](https://docs.mirage.strukto.ai/typescript/quickstart) and the
  207. [CLI](https://docs.mirage.strukto.ai/home/access/cli).
  208. ## Scriptable Policy
  209. A profile can name policy scripts for what its rules cannot express. A script's
  210. `pre_command` takes the command, can open the files it names, and returns a
  211. deny, an ask or `None`. This one disables `rm`, and a Python script whose code
  212. deletes files:
  213. ```python
  214. def deletes(path):
  215. try:
  216. code = open(path).read()
  217. except OSError:
  218. return False
  219. return any(call in code for call in ("os.remove", "os.unlink", "shutil.rmtree"))
  220. def pre_command(ctx):
  221. if ctx["command"] == "rm" or (
  222. ctx["command"].startswith("python") and any(deletes(p) for p in ctx["paths"])
  223. ):
  224. return {"kind": "deny", "reason": "deleting files is disabled"}
  225. ```
  226. Register it in a profile, here to run on Monty before every command:
  227. ```python
  228. ws = Workspace(
  229. {"/s3": (S3VFS(S3Config(bucket="my-bucket")), MountMode.WRITE)},
  230. profiles={
  231. "analyst": {
  232. "policy": {
  233. "pre_command": [{"script": ScriptSource(Path("guard.py").read_text()), "runtime": "monty"}],
  234. },
  235. },
  236. },
  237. profile="analyst",
  238. )
  239. ```
  240. ```console
  241. $ cat /s3/clean.py
  242. import os
  243. os.remove("/s3/report.txt")
  244. $ rm /s3/report.txt
  245. rm: Permission denied
  246. $ python3 /s3/clean.py
  247. python3: Permission denied
  248. ```
  249. See [policy scripts](https://docs.mirage.strukto.ai/home/policy/scripts) for
  250. the other stages a script can answer at.
  251. ## Examples
  252. - **[In-Process Terminal](https://docs.mirage.strukto.ai/home/examples/in-process-terminal).** A terminal for agents inside your application, even within a FastAPI or Express server, without a fixed machine or sandbox.
  253. - **[Multi-machine Terminal](https://docs.mirage.strukto.ai/home/examples/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.
  254. - **[Secured Terminal](https://docs.mirage.strukto.ai/home/examples/secured-terminal).** Decide which files an agent sees, which commands and CLIs it runs and which credentials its tools use, in one workspace config.
  255. - **[Infra-agnostic Terminal](https://docs.mirage.strukto.ai/home/examples/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.
  256. ## Contributors
  257. Thanks to everyone who has contributed to Mirage.
  258. <a href="https://github.com/strukto-ai/mirage/graphs/contributors">
  259. <img src="https://contrib.rocks/image?repo=strukto-ai/mirage" alt="Mirage contributors" />
  260. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.