strukto-ai/miragePublic

The World's First Virtual Terminal for AI Agents

AI summary: A unified virtual filesystem explicitly designed for AI agents to interact seamlessly with disparate data environments.

Stars
3.8K
+9 today
Forks
284
Watchers
8
Open issues
18
Open PRs
2
Contributors
~39
Commits
7.8K
Branches
6

TypeScriptApache-2.0Created May 6, 2026Last push todayLatest release v0.0.8+15 stars this week+97 this month

Quick answers

What is mirage?
A unified virtual filesystem explicitly designed for AI agents to interact seamlessly with disparate data environments.
What does mirage do?
Mirage provides a highly unified virtual filesystem tailored specifically for AI agents, allowing them to interact seamlessly with various data sources exactly as if they were local files. It intelligently abstracts away the immense complexity of different storage backends, diverse APIs, and segmented cloud environments, presenting a standard POSIX-like interface to the agent. This unified approach entirely eliminates the need to build custom, brittle connectors for every new data source an agent needs to access. By heavily standardizing the critical interaction layer, Mirage significantly accelerates the development and overall reliability of data-heavy autonomous systems.
Who is mirage for?
Mirage is built for AI developers and system architects constructing complex agents that require broad, highly abstracted data access. It is best suited for engineering teams actively working in Python or TypeScript.
How do I get started with mirage?
pip install mirage-ai
How popular is mirage on GitHub?
strukto-ai/mirage has 3,797 stars and 284 forks on GitHub, and gained 15 stars in the last 7 days.
What license does mirage use?
strukto-ai/mirage is released under the Apache-2.0 license.

Star history

since Jul 29, 2026
01K2K3KJul 2026Sep 2026Oct 2026Nov 2026
3.8K stars as of Nov 20, 2026. Measured daily since Jul 29, 2026; GitHub no longer exposes earlier star timestamps.

Update history

2 recorded
  • Nov 12, 2026New release v0.0.8 (previously v0.0.7).
  • Oct 21, 2026New release v0.0.7 (previously v0.0.6).

Contribution activity

commits per day, last 52 weeks
NovDecJanFebMarAprMayJunJulAugSepOctNovMonWedFri2025-11-16: 0 commits2025-11-17: 0 commits2025-11-18: 0 commits2025-11-19: 0 commits2025-11-20: 0 commits2025-11-21: 0 commits2025-11-22: 0 commits2025-11-23: 0 commits2025-11-24: 0 commits2025-11-25: 0 commits2025-11-26: 0 commits2025-11-27: 0 commits2025-11-28: 0 commits2025-11-29: 0 commits2025-11-30: 0 commits2025-12-01: 0 commits2025-12-02: 0 commits2025-12-03: 0 commits2025-12-04: 0 commits2025-12-05: 0 commits2025-12-06: 0 commits2025-12-07: 0 commits2025-12-08: 0 commits2025-12-09: 0 commits2025-12-10: 0 commits2025-12-11: 0 commits2025-12-12: 0 commits2025-12-13: 0 commits2025-12-14: 0 commits2025-12-15: 0 commits2025-12-16: 0 commits2025-12-17: 0 commits2025-12-18: 0 commits2025-12-19: 0 commits2025-12-20: 0 commits2025-12-21: 0 commits2025-12-22: 0 commits2025-12-23: 0 commits2025-12-24: 0 commits2025-12-25: 0 commits2025-12-26: 0 commits2025-12-27: 0 commits2025-12-28: 0 commits2025-12-29: 0 commits2025-12-30: 0 commits2025-12-31: 0 commits2026-01-01: 0 commits2026-01-02: 0 commits2026-01-03: 0 commits2026-01-04: 0 commits2026-01-05: 0 commits2026-01-06: 0 commits2026-01-07: 0 commits2026-01-08: 0 commits2026-01-09: 0 commits2026-01-10: 0 commits2026-01-11: 0 commits2026-01-12: 0 commits2026-01-13: 0 commits2026-01-14: 0 commits2026-01-15: 0 commits2026-01-16: 0 commits2026-01-17: 0 commits2026-01-18: 0 commits2026-01-19: 0 commits2026-01-20: 0 commits2026-01-21: 0 commits2026-01-22: 0 commits2026-01-23: 0 commits2026-01-24: 0 commits2026-01-25: 0 commits2026-01-26: 0 commits2026-01-27: 0 commits2026-01-28: 0 commits2026-01-29: 0 commits2026-01-30: 0 commits2026-01-31: 0 commits2026-02-01: 0 commits2026-02-02: 0 commits2026-02-03: 0 commits2026-02-04: 0 commits2026-02-05: 0 commits2026-02-06: 0 commits2026-02-07: 0 commits2026-02-08: 0 commits2026-02-09: 0 commits2026-02-10: 0 commits2026-02-11: 0 commits2026-02-12: 0 commits2026-02-13: 0 commits2026-02-14: 0 commits2026-02-15: 0 commits2026-02-16: 0 commits2026-02-17: 0 commits2026-02-18: 0 commits2026-02-19: 0 commits2026-02-20: 0 commits2026-02-21: 0 commits2026-02-22: 0 commits2026-02-23: 0 commits2026-02-24: 0 commits2026-02-25: 0 commits2026-02-26: 0 commits2026-02-27: 0 commits2026-02-28: 0 commits2026-03-01: 0 commits2026-03-02: 0 commits2026-03-03: 0 commits2026-03-04: 0 commits2026-03-05: 0 commits2026-03-06: 0 commits2026-03-07: 0 commits2026-03-08: 0 commits2026-03-09: 0 commits2026-03-10: 0 commits2026-03-11: 0 commits2026-03-12: 0 commits2026-03-13: 0 commits2026-03-14: 0 commits2026-03-15: 0 commits2026-03-16: 0 commits2026-03-17: 0 commits2026-03-18: 0 commits2026-03-19: 0 commits2026-03-20: 0 commits2026-03-21: 0 commits2026-03-22: 0 commits2026-03-23: 0 commits2026-03-24: 0 commits2026-03-25: 0 commits2026-03-26: 0 commits2026-03-27: 0 commits2026-03-28: 0 commits2026-03-29: 0 commits2026-03-30: 0 commits2026-03-31: 0 commits2026-04-01: 0 commits2026-04-02: 0 commits2026-04-03: 0 commits2026-04-04: 0 commits2026-04-05: 0 commits2026-04-06: 0 commits2026-04-07: 0 commits2026-04-08: 0 commits2026-04-09: 0 commits2026-04-10: 0 commits2026-04-11: 0 commits2026-04-12: 0 commits2026-04-13: 0 commits2026-04-14: 0 commits2026-04-15: 0 commits2026-04-16: 0 commits2026-04-17: 0 commits2026-04-18: 0 commits2026-04-19: 0 commits2026-04-20: 0 commits2026-04-21: 0 commits2026-04-22: 0 commits2026-04-23: 0 commits2026-04-24: 0 commits2026-04-25: 0 commits2026-04-26: 0 commits2026-04-27: 0 commits2026-04-28: 0 commits2026-04-29: 0 commits2026-04-30: 0 commits2026-05-01: 0 commits2026-05-02: 0 commits2026-05-03: 0 commits2026-05-04: 0 commits2026-05-05: 0 commits2026-05-06: 4 commits2026-05-07: 25 commits2026-05-08: 19 commits2026-05-09: 32 commits2026-05-10: 4 commits2026-05-11: 8 commits2026-05-12: 9 commits2026-05-13: 3 commits2026-05-14: 4 commits2026-05-15: 5 commits2026-05-16: 1 commit2026-05-17: 6 commits2026-05-18: 1 commit2026-05-19: 4 commits2026-05-20: 0 commits2026-05-21: 7 commits2026-05-22: 1 commit2026-05-23: 1 commit2026-05-24: 4 commits2026-05-25: 7 commits2026-05-26: 3 commits2026-05-27: 6 commits2026-05-28: 6 commits2026-05-29: 3 commits2026-05-30: 2 commits2026-05-31: 11 commits2026-06-01: 5 commits2026-06-02: 1 commit2026-06-03: 2 commits2026-06-04: 13 commits2026-06-05: 18 commits2026-06-06: 11 commits2026-06-07: 19 commits2026-06-08: 32 commits2026-06-09: 79 commits2026-06-10: 89 commits2026-06-11: 48 commits2026-06-12: 13 commits2026-06-13: 26 commits2026-06-14: 14 commits2026-06-15: 37 commits2026-06-16: 17 commits2026-06-17: 17 commits2026-06-18: 3 commits2026-06-19: 23 commits2026-06-20: 5 commits2026-06-21: 11 commits2026-06-22: 6 commits2026-06-23: 19 commits2026-06-24: 15 commits2026-06-25: 12 commits2026-06-26: 4 commits2026-06-27: 10 commits2026-06-28: 24 commits2026-06-29: 14 commits2026-06-30: 8 commits2026-07-01: 2 commits2026-07-02: 17 commits2026-07-03: 5 commits2026-07-04: 1 commit2026-07-05: 2 commits2026-07-06: 0 commits2026-07-07: 8 commits2026-07-08: 9 commits2026-07-09: 10 commits2026-07-10: 24 commits2026-07-11: 9 commits2026-07-12: 11 commits2026-07-13: 17 commits2026-07-14: 18 commits2026-07-15: 6 commits2026-07-16: 11 commits2026-07-17: 18 commits2026-07-18: 17 commits2026-07-19: 14 commits2026-07-20: 14 commits2026-07-21: 12 commits2026-07-22: 8 commits2026-07-23: 8 commits2026-07-24: 6 commits2026-07-25: 7 commits2026-07-26: 5 commits2026-07-27: 2 commits2026-07-28: 4 commits2026-07-29: 2 commits2026-07-30: 7 commits2026-07-31: 9 commits2026-08-01: 6 commits2026-08-02: 12 commits2026-08-03: 11 commits2026-08-04: 6 commits2026-08-05: 5 commits2026-08-06: 3 commits2026-08-07: 8 commits2026-08-08: 13 commits2026-08-09: 17 commits2026-08-10: 15 commits2026-08-11: 21 commits2026-08-12: 21 commits2026-08-13: 23 commits2026-08-14: 23 commits2026-08-15: 50 commits2026-08-16: 50 commits2026-08-17: 17 commits2026-08-18: 33 commits2026-08-19: 13 commits2026-08-20: 12 commits2026-08-21: 18 commits2026-08-22: 15 commits2026-08-23: 26 commits2026-08-24: 24 commits2026-08-25: 16 commits2026-08-26: 11 commits2026-08-27: 48 commits2026-08-28: 45 commits2026-08-29: 3 commits2026-08-30: 41 commits2026-08-31: 27 commits2026-09-01: 28 commits2026-09-02: 19 commits2026-09-03: 18 commits2026-09-04: 26 commits2026-09-05: 46 commits2026-09-06: 26 commits2026-09-07: 30 commits2026-09-08: 36 commits2026-09-09: 55 commits2026-09-10: 57 commits2026-09-11: 28 commits2026-09-12: 13 commits2026-09-13: 7 commits2026-09-14: 29 commits2026-09-15: 72 commits2026-09-16: 32 commits2026-09-17: 12 commits2026-09-18: 8 commits2026-09-19: 27 commits2026-09-20: 19 commits2026-09-21: 29 commits2026-09-22: 34 commits2026-09-23: 58 commits2026-09-24: 97 commits2026-09-25: 75 commits2026-09-26: 31 commits2026-09-27: 73 commits2026-09-28: 66 commits2026-09-29: 102 commits2026-09-30: 94 commits2026-10-01: 119 commits2026-10-02: 119 commits2026-10-03: 79 commits2026-10-04: 109 commits2026-10-05: 75 commits2026-10-06: 114 commits2026-10-07: 77 commits2026-10-08: 141 commits2026-10-09: 95 commits2026-10-10: 105 commits2026-10-11: 55 commits2026-10-12: 83 commits2026-10-13: 62 commits2026-10-14: 89 commits2026-10-15: 91 commits2026-10-16: 94 commits2026-10-17: 37 commits2026-10-18: 122 commits2026-10-19: 90 commits2026-10-20: 55 commits2026-10-21: 16 commits2026-10-22: 14 commits2026-10-23: 20 commits2026-10-24: 83 commits2026-10-25: 205 commits2026-10-26: 121 commits2026-10-27: 85 commits2026-10-28: 152 commits2026-10-29: 107 commits2026-10-30: 72 commits2026-10-31: 83 commits2026-11-01: 49 commits2026-11-02: 60 commits2026-11-03: 85 commits2026-11-04: 60 commits2026-11-05: 66 commits2026-11-06: 45 commits2026-11-07: 20 commits2026-11-08: 22 commits2026-11-09: 39 commits2026-11-10: 117 commits2026-11-11: 69 commits2026-11-12: 27 commits2026-11-13: 0 commits2026-11-14: 0 commits
6,362 commits in the last yearLessMore

Signals and awards

derived from tracked data
  • Very active

    6,362 commits in 52 weeks

  • Permissive license

    Apache-2.0

  • Continuous integration

    Automated checks passing

What mirage does

Mirage provides a highly unified virtual filesystem tailored specifically for AI agents, allowing them to interact seamlessly with various data sources exactly as if they were local files. It intelligently abstracts away the immense complexity of different storage backends, diverse APIs, and segmented cloud environments, presenting a standard POSIX-like interface to the agent. This unified approach entirely eliminates the need to build custom, brittle connectors for every new data source an agent needs to access. By heavily standardizing the critical interaction layer, Mirage significantly accelerates the development and overall reliability of data-heavy autonomous systems.

Mirage is built for AI developers and system architects constructing complex agents that require broad, highly abstracted data access. It is best suited for engineering teams actively working in Python or TypeScript.

  • Unified filesystem interface: Clearly presents diverse data sources to AI agents as a highly standard, easily navigable virtual filesystem.
  • Storage abstraction: Effectively hides the underlying complexities of interacting with various cloud providers, databases, and APIs.
  • POSIX-like interactions: Directly allows agents to use familiar commands and logic to confidently read, write, and manage data.
  • Multi-language support: Provides highly robust SDKs and comprehensive documentation for both Python and TypeScript environments.
  • Extensible architecture: Distinctly designed to easily support new storage backends and custom data connectors as strictly needed.

Where teams use it

Cross-cloud data access

AI agents can seamlessly read critical files from AWS S3 and write corresponding outputs to Google Cloud Storage using standard file operations.

Agentic data pipelines

Developers can reliably build data processing pipelines where agents interact with database records precisely as if they were local text files.

Simplified agent tooling

Engineering teams can entirely replace complex API interaction logic in their agents with simple, robust file read/write commands.

Secure sandboxing

Security teams can safely mount specific data subsets into the virtual filesystem to strictly restrict an agent's access scope.

Getting started: pip install mirage-ai

README

main branch

Status: preview 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 한국어

Mirage is a Virtual Terminal for AI Agents: one shell over data, CLIs and runtimes. Unix tools reach every service, and grep runs on each service's own search, such as Gmail's or Slack's. Mirage routes each command to the runtime that fits it, so most lines run in-process and only heavy work reaches a sandbox, which cuts infrastructure cost and tokens. The terminal itself is light: a workspace takes about 100 KB of memory and each new session about 10 KB, so one process serves many agents at once. Profiles decide what an agent can run and even what it can see, and scriptable policies refuse anything those rules cannot express.

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"]},
        },
    },
    # The e2b sandbox is a machine; the remote runtime runs programs on it
    machines={"box": {"provider": "e2b", "sandbox_id": sandbox_id, "mount_type": "ssh"}},
    runtimes=[
        MontyRuntime(captures=["python", "python3"]),
        RemoteRuntime(captures=["python", "python3"], machine="box"),
    ],
    # route the underlying computation: numpy lines run on the machine, the rest on monty
    route_policy=lambda ctx: "remote" 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 runtimes. Python, JavaScript and any other command can be sent to a configured runtime, 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 runtimes 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.

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 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  Google Calendar
Databases and Data Platforms PostgreSQL  MongoDB  Redis Upstash Redis  LanceDB  Qdrant  Chroma  Mem0  Hugging Face Datasets  Hugging Face Models  Hugging Face Spaces  Databricks Volumes  Dify
Observability Langfuse  Jaeger
Local and Remote RAM  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 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 git  gh
Communication slack  discord  himalaya
Work and Data linear  ntn  gws  hf

Virtual Runtime

Runtimes are virtualized the same way, and not only for coding languages. Any command on the line can be redirected to a configured runtime, so Python might run in-process with Monty while another command, say kubectl, is sent to a remote machine over SSH. Which runtime serves a given line can be decided by a scripted runtime router.

Runtimes
Python Monty  WASI CPython on wasmtime  Pyodide  sandlock  Host CPython
JavaScript QuickJS, serving node and js JavaScript TypeScript
Machines Docker  E2B  Daytona  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 in Environment dotenv
Custom 1Password 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
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

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.

Embedded Terminal

Most of the time an agent does not need a sandbox, only a terminal-like interface, and Mirage embeds one in an application server. Each terminal is a Mirage session with its own working directory, environment and history, and Python runs in-process on Monty, so a terminal starts with no container or VM. Here it is in Express; the FastAPI version is in the docs.

npm install @struktoai/mirage-node @pydantic/monty express
import express from 'express'
import { MontyRuntime, MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/work': new RAMVFS() },
  { mode: MountMode.EXEC, runtimes: [new MontyRuntime({ captures: ['python', 'python3'] })] },
)
const app = express()
app.use(express.json())

app.post('/sessions/:id', (req, res) => {
  ws.createSession(req.params.id)
  res.sendStatus(201)
})

app.post('/sessions/:id/run', async (req, res) => {
  const r = await ws.shell(req.body.command, { sessionId: req.params.id })
  res.json({ stdout: r.stdoutText, stderr: r.stderrText, exitCode: r.exitCode })
})

app.listen(3000, '127.0.0.1')

Contributors

Thanks to everyone who has contributed to Mirage.

Mirage contributors
View on GitHub

Recent activity

commits and pull requests

Recent open issues

view all

Discussions

all 1

Releases and announcements

8 total
  1. Mirage 0.0.8v0.0.8Nov 3, 2026

    We are excited to announce the release of Mirage 0.0.8 🎉🎉🎉 Mirage 0.0.8 is a hosting release. 0.0.7 sent every way in through one dispatcher; 0.0.8 makes that dispatcher safe to run many workspaces side by side. A workspace now has a memory budget, a network it may reach, mounts with capacity, and processes and jobs that live in the shared store, and the server runs its workspaces on several workers with rate limits, readiness, a graceful drain and OpenTelemetry. Underneath, the shell runs on Mirage's own bash parser in Rust, and jq, awk, tar, zip, patch, od, iconv and most text commands move into the same `mirage-rs` crate, so both hosts run one implementation that a timeout can stop mid-step. jq no longer needs libjq or jq-wasm. A VFS has one `read`, `write` and `append` that take bytes or a stream, every open file goes through `MountCore`, and every walk stops at the mount's `walk_limit`. `search` becomes a CLI, an MCP server can be installed as a CLI, and `mirage-bash` lets Claude Code run its Bash tool in a workspace. The agent adapters split into one npm package per framework, and TiDB Cloud Filesystem joins the mounts. Python and TypeScript stay mirrored throughout. `pi

  2. Mirage 0.0.7v0.0.7Oct 20, 2026

    We are excited to announce the release of Mirage 0.0.7 🎉🎉🎉 Mirage 0.0.7 is a one-dispatcher release. 0.0.6 decided what an agent may do; 0.0.7 sends every way in through the same place, so that decision, the cache and the search hold alike for a command, a CLI, a runtime and every server endpoint. Commands read and write through the dispatcher, and every backend runs the same generic commands. Underneath, the command kernels move into one Rust crate that both hosts run, through PyO3 in Python and WebAssembly in TypeScript: sed, grep, rg, sort, jq, printf, bc, diff, cut and tr among them. A mount now says how fresh its reads must be and whether its writes are conditional. grep and rg narrow through a backend's own search while printing exactly what a full scan prints, and output streams instead of arriving at the end. The server hosts workspaces for accounts over HTTP, MCP, SSH and SSH over HTTPS. Policy hooks run by surface and policy programs run on a runtime. Monty becomes the default Python, apple_container and microsandbox join the runtimes, W&B, Airtable, NFS and time-scoped chat mounts arrive, and watch becomes push-only events. The core vocabulary is renamed to `VFS`, `s

  3. Mirage 0.0.6v0.0.6Sep 3, 2026

    We are excited to announce the release of Mirage 0.0.6 🎉🎉🎉 Mirage 0.0.6 is a permissions release. 0.0.5 gave an agent typed programs to act with; 0.0.6 decides what it may do with them. A permissions document replaces the old guard list: allow, ask and deny rules, one role per session, mounts that narrow rather than gate, hidden subtrees that stay hidden through a mutation, an approval door where an asked line reaches a person, and a decision ledger you can query and explain. A policy can now be a program, written in Python or JavaScript and judged at the command, op and session doors. Credentials move behind a secrets plane instead of sitting in a config block. Underneath, a long deduplication pass collapses the backends onto shared HTTP, object-store, hierarchy and render kits, the integration fakes become one TypeScript and Prisma kit that runs off a laptop, bash grows most of tiers 2 and 3, guests see one filesystem through a single stat struct, and Hugging Face Hub arrives as both a mount and a CLI. Python and TypeScript stay mirrored throughout. `pip install mirage-ai==0.0.6` · `npm install @struktoai/[email protected]` (and `-node`, `-browser`, `-server`, `-cli`, `-agen

  4. Mirage 0.0.5v0.0.5Aug 15, 2026

    We are excited to announce the release of Mirage 0.0.5 🎉🎉🎉 Mirage 0.0.5 is a control-surface release. An agent no longer only reads a workspace, it acts on one through typed programs: a CLI tier turns `git`, `gh`, `slack`, `ntn`, `himalaya`, `gws`, `linear`, `discord` and anything you author into installed head words dispatched by name, and a policy layer sits at every door those programs pass through. Underneath, the workspace grows one door per state plane, the runtimes collapse onto a single mount-op vocabulary, background commands stream through a job console instead of arriving whole, and a new `@struktoai/mirage-dsh` package puts a mirage workspace under DeepSeek Harness as its filesystem and shell. Alongside that, a long conformance sweep pins commands, flags and error text against GNU and the real upstream CLIs. Python and TypeScript stay mirrored throughout, now with a layout parity gate that fails when they drift. `pip install mirage-ai==0.0.5` · `npm install @struktoai/[email protected]` (and `-node`, `-browser`, `-server`, `-cli`, `-agents`) New in this release: `npm install @struktoai/[email protected]`, the DeepSeek Harness adapter, on its own version line. ## H

  5. Mirage 0.0.4v0.0.4Jul 23, 2026

    We are excited to announce the release of Mirage 0.0.4 🎉🎉🎉 Mirage 0.0.4 is an architecture and depth release. Path addressing becomes a real namespace layer with first-class symlinks and attribute overlays that survive restarts; the control plane moves onto pluggable state stores (RAM, disk, Redis, S3) with CAS-guarded writes; the shell grows GNU-grade bash semantics (arithmetic, control flow, brace expansion, `printf`, `getopts`, parameter expansion); commands can be run by pluggable runtimes that read and write workspace mounts; and eight new or rebuilt backends land. Python is mypy-clean and TypeScript is tsc-clean, both enforced as CI gates. Python and TypeScript are kept mirrored throughout. `pip install mirage-ai==0.0.4` · `npm install @struktoai/[email protected]` (and `-node`, `-browser`, `-server`, `-cli`, `-agents`) ## Highlights - **The namespace is a real addressing layer.** A `Namespace` facade consolidates mount resolution, symlink following, and attribute overlays behind one surface, and the Workspace routes dispatch, `apply_io`, and post-write invalidation through it instead of holding a dispatcher directly (#420, #424, #426). Symlinks are first-class namespa

Code frequency

additions and deletions
+678.2K-678.2KWeek of 2026-05-03: +553,722 linesWeek of 2026-05-03: -33,059 linesWeek of 2026-05-10: +14,522 linesWeek of 2026-05-10: -3,783 linesWeek of 2026-05-17: +58,388 linesWeek of 2026-05-17: -48,038 linesWeek of 2026-05-24: +55,631 linesWeek of 2026-05-24: -45,008 linesWeek of 2026-05-31: +26,072 linesWeek of 2026-05-31: -15,594 linesWeek of 2026-06-07: +82,832 linesWeek of 2026-06-07: -83,652 linesWeek of 2026-06-14: +27,487 linesWeek of 2026-06-14: -7,385 linesWeek of 2026-06-21: +26,078 linesWeek of 2026-06-21: -64,150 linesWeek of 2026-06-28: +29,099 linesWeek of 2026-06-28: -41,962 linesWeek of 2026-07-05: +30,374 linesWeek of 2026-07-05: -11,780 linesWeek of 2026-07-12: +130,749 linesWeek of 2026-07-12: -58,434 linesWeek of 2026-07-19: +204,864 linesWeek of 2026-07-19: -75,906 linesWeek of 2026-07-26: +124,090 linesWeek of 2026-07-26: -41,087 linesWeek of 2026-08-02: +147,234 linesWeek of 2026-08-02: -52,560 linesWeek of 2026-08-09: +178,421 linesWeek of 2026-08-09: -87,008 linesWeek of 2026-08-16: +202,750 linesWeek of 2026-08-16: -110,037 linesWeek of 2026-08-23: +117,282 linesWeek of 2026-08-23: -49,136 linesWeek of 2026-08-30: +116,194 linesWeek of 2026-08-30: -37,682 linesWeek of 2026-09-06: +103,687 linesWeek of 2026-09-06: -27,197 linesWeek of 2026-09-13: +241,563 linesWeek of 2026-09-13: -145,618 linesWeek of 2026-09-20: +268,762 linesWeek of 2026-09-20: -49,264 linesWeek of 2026-09-27: +678,247 linesWeek of 2026-09-27: -521,974 linesWeek of 2026-10-04: +386,746 linesWeek of 2026-10-04: -258,474 linesWeek of 2026-10-11: +320,271 linesWeek of 2026-10-11: -233,730 linesWeek of 2026-10-18: +419,227 linesWeek of 2026-10-18: -289,970 linesWeek of 2026-10-25: +335,785 linesWeek of 2026-10-25: -159,842 linesWeek of 2026-11-01: +257,202 linesWeek of 2026-11-01: -131,978 linesWeek of 2026-11-08: +237,942 linesWeek of 2026-11-08: -133,158 linesMay 3, 2026Nov 8, 2026
+5.4M lines added, -2.8M removed over the last year.

Commits per week

last 52 weeks
8250Week of 2025-11-16: 0 commitsWeek of 2025-11-23: 0 commitsWeek of 2025-11-30: 0 commitsWeek of 2025-12-07: 0 commitsWeek of 2025-12-14: 0 commitsWeek of 2025-12-21: 0 commitsWeek of 2025-12-28: 0 commitsWeek of 2026-01-04: 0 commitsWeek of 2026-01-11: 0 commitsWeek of 2026-01-18: 0 commitsWeek of 2026-01-25: 0 commitsWeek of 2026-02-01: 0 commitsWeek of 2026-02-08: 0 commitsWeek of 2026-02-15: 0 commitsWeek of 2026-02-22: 0 commitsWeek of 2026-03-01: 0 commitsWeek of 2026-03-08: 0 commitsWeek of 2026-03-15: 0 commitsWeek of 2026-03-22: 0 commitsWeek of 2026-03-29: 0 commitsWeek of 2026-04-05: 0 commitsWeek of 2026-04-12: 0 commitsWeek of 2026-04-19: 0 commitsWeek of 2026-04-26: 0 commitsWeek of 2026-05-03: 80 commitsWeek of 2026-05-10: 34 commitsWeek of 2026-05-17: 20 commitsWeek of 2026-05-24: 31 commitsWeek of 2026-05-31: 61 commitsWeek of 2026-06-07: 306 commitsWeek of 2026-06-14: 116 commitsWeek of 2026-06-21: 77 commitsWeek of 2026-06-28: 71 commitsWeek of 2026-07-05: 62 commitsWeek of 2026-07-12: 98 commitsWeek of 2026-07-19: 69 commitsWeek of 2026-07-26: 35 commitsWeek of 2026-08-02: 58 commitsWeek of 2026-08-09: 170 commitsWeek of 2026-08-16: 158 commitsWeek of 2026-08-23: 173 commitsWeek of 2026-08-30: 205 commitsWeek of 2026-09-06: 245 commitsWeek of 2026-09-13: 187 commitsWeek of 2026-09-20: 343 commitsWeek of 2026-09-27: 652 commitsWeek of 2026-10-04: 716 commitsWeek of 2026-10-11: 511 commitsWeek of 2026-10-18: 400 commitsWeek of 2026-10-25: 825 commitsWeek of 2026-11-01: 385 commitsWeek of 2026-11-08: 274 commitsNov 16, 2025Nov 8, 2026
6.4K commits in the last 52 weeks.

When work happens

weekday and hour
SunMonTueWedThuFriSat036912151821Sun 0:00 — 42 commitsSun 1:00 — 44 commitsSun 2:00 — 34 commitsSun 3:00 — 35 commitsSun 4:00 — 44 commitsSun 5:00 — 47 commitsSun 6:00 — 44 commitsSun 7:00 — 22 commitsSun 8:00 — 14 commitsSun 9:00 — 10 commitsSun 10:00 — 20 commitsSun 11:00 — 28 commitsSun 12:00 — 22 commitsSun 13:00 — 32 commitsSun 14:00 — 47 commitsSun 15:00 — 37 commitsSun 16:00 — 55 commitsSun 17:00 — 39 commitsSun 18:00 — 44 commitsSun 19:00 — 39 commitsSun 20:00 — 58 commitsSun 21:00 — 73 commitsSun 22:00 — 68 commitsSun 23:00 — 60 commitsMon 0:00 — 57 commitsMon 1:00 — 57 commitsMon 2:00 — 59 commitsMon 3:00 — 32 commitsMon 4:00 — 39 commitsMon 5:00 — 51 commitsMon 6:00 — 29 commitsMon 7:00 — 11 commitsMon 8:00 — 10 commitsMon 9:00 — 20 commitsMon 10:00 — 25 commitsMon 11:00 — 27 commitsMon 12:00 — 30 commitsMon 13:00 — 31 commitsMon 14:00 — 32 commitsMon 15:00 — 35 commitsMon 16:00 — 60 commitsMon 17:00 — 43 commitsMon 18:00 — 41 commitsMon 19:00 — 28 commitsMon 20:00 — 33 commitsMon 21:00 — 48 commitsMon 22:00 — 37 commitsMon 23:00 — 24 commitsTue 0:00 — 30 commitsTue 1:00 — 54 commitsTue 2:00 — 37 commitsTue 3:00 — 38 commitsTue 4:00 — 31 commitsTue 5:00 — 59 commitsTue 6:00 — 45 commitsTue 7:00 — 32 commitsTue 8:00 — 14 commitsTue 9:00 — 24 commitsTue 10:00 — 33 commitsTue 11:00 — 24 commitsTue 12:00 — 44 commitsTue 13:00 — 37 commitsTue 14:00 — 46 commitsTue 15:00 — 100 commitsTue 16:00 — 65 commitsTue 17:00 — 58 commitsTue 18:00 — 41 commitsTue 19:00 — 29 commitsTue 20:00 — 34 commitsTue 21:00 — 70 commitsTue 22:00 — 65 commitsTue 23:00 — 38 commitsWed 0:00 — 45 commitsWed 1:00 — 31 commitsWed 2:00 — 35 commitsWed 3:00 — 70 commitsWed 4:00 — 42 commitsWed 5:00 — 22 commitsWed 6:00 — 18 commitsWed 7:00 — 10 commitsWed 8:00 — 12 commitsWed 9:00 — 19 commitsWed 10:00 — 32 commitsWed 11:00 — 22 commitsWed 12:00 — 24 commitsWed 13:00 — 37 commitsWed 14:00 — 35 commitsWed 15:00 — 63 commitsWed 16:00 — 58 commitsWed 17:00 — 62 commitsWed 18:00 — 69 commitsWed 19:00 — 59 commitsWed 20:00 — 47 commitsWed 21:00 — 44 commitsWed 22:00 — 54 commitsWed 23:00 — 24 commitsThu 0:00 — 29 commitsThu 1:00 — 28 commitsThu 2:00 — 29 commitsThu 3:00 — 39 commitsThu 4:00 — 60 commitsThu 5:00 — 46 commitsThu 6:00 — 41 commitsThu 7:00 — 41 commitsThu 8:00 — 23 commitsThu 9:00 — 27 commitsThu 10:00 — 12 commitsThu 11:00 — 35 commitsThu 12:00 — 59 commitsThu 13:00 — 38 commitsThu 14:00 — 46 commitsThu 15:00 — 39 commitsThu 16:00 — 60 commitsThu 17:00 — 67 commitsThu 18:00 — 49 commitsThu 19:00 — 38 commitsThu 20:00 — 39 commitsThu 21:00 — 68 commitsThu 22:00 — 50 commitsThu 23:00 — 43 commitsFri 0:00 — 44 commitsFri 1:00 — 35 commitsFri 2:00 — 52 commitsFri 3:00 — 51 commitsFri 4:00 — 69 commitsFri 5:00 — 42 commitsFri 6:00 — 27 commitsFri 7:00 — 14 commitsFri 8:00 — 18 commitsFri 9:00 — 14 commitsFri 10:00 — 12 commitsFri 11:00 — 23 commitsFri 12:00 — 31 commitsFri 13:00 — 50 commitsFri 14:00 — 57 commitsFri 15:00 — 38 commitsFri 16:00 — 33 commitsFri 17:00 — 39 commitsFri 18:00 — 31 commitsFri 19:00 — 35 commitsFri 20:00 — 20 commitsFri 21:00 — 27 commitsFri 22:00 — 28 commitsFri 23:00 — 34 commitsSat 0:00 — 39 commitsSat 1:00 — 35 commitsSat 2:00 — 36 commitsSat 3:00 — 39 commitsSat 4:00 — 30 commitsSat 5:00 — 26 commitsSat 6:00 — 15 commitsSat 7:00 — 20 commitsSat 8:00 — 7 commitsSat 9:00 — 17 commitsSat 10:00 — 18 commitsSat 11:00 — 25 commitsSat 12:00 — 30 commitsSat 13:00 — 24 commitsSat 14:00 — 37 commitsSat 15:00 — 38 commitsSat 16:00 — 43 commitsSat 17:00 — 21 commitsSat 18:00 — 22 commitsSat 19:00 — 30 commitsSat 20:00 — 45 commitsSat 21:00 — 30 commitsSat 22:00 — 48 commitsSat 23:00 — 58 commits
Commit volume by weekday and hour (UTC). Larger dots mean more commits.
DateListRankStars gained
May 7, 2026daily#13+66
  • morluto/rea

    Reverse engineer anything with agents, from app behavior down to native binaries.

    471.6K stars · TypeScript

  • freeCodeCamp/freeCodeCamp

    freeCodeCamp.org's open-source codebase and curriculum. Learn math, programming, and computer science for free.

    459.4K stars · TypeScript

  • openclaw/openclaw

    The AI that really does things. Any OS. Any Platform. The lobster way. 🦞

    394.9K stars · TypeScript

  • donnemartin/system-design-primer

    Learn how to design large-scale systems. Prep for the system design interview. Includes Anki flashcards.

    378.7K stars · Python

  • affaan-m/ECC

    The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

    307.9K stars · JavaScript

  • practical-tutorials/project-based-learning

    Curated list of project-based tutorials

    290.1K stars · Python