Mirage

What it is

Mirage is a Python and TypeScript library, with a mirage CLI, that gives an AI agent one virtual shell over mounted services (S3, Google Drive, Slack, Gmail, Redis), virtualized CLIs (git, slack, ntn) and routed runtimes. A Workspace maps mount paths to backends, each with a MountMode. The example on the page uses EXEC for /tmp and /slack, and WRITE for /redis. Agents reach it through the SDKs, the CLI, or a real mountpoint over FUSE and FSKit.

How it works

The security controls sit in the shell layer, so they apply to everything mounted under it.

• Commands and CLIs are governed by allow, ask and deny rules. Paths are governed by hide and show. A hidden path is absent from the filesystem the agent sees, not just unreadable.
• A profile can name a policy script that runs at the gate on every command and answers allow, deny or ask. Like every rule, it can only restrict and never grant.
• A host can also register policies on an ordered policy engine stack. The workspace consults it on every command, VFS operation and session write. The page says this keeps both files and environment variables from leaking.
• The same CLI can be installed under several names, each with its own credentials (ws.register_cli("slack", SLACK, {"token": ...})), so each agent holds only the accounts it is given.
• Environment variables can resolve to secrets in AWS Secrets Manager, 1Password, Auth0 or dotenv.
• Commands can be routed to a runtime. Python can run in-process under MontyRuntime(captures=["python", "python3"]), while another command such as kubectl goes to a remote machine over SSH. A scripted runtime router makes that choice.

Preconditions / Affected

• Python 3.11 or later for mirage-ai and the CLI.
• Node.js 22.20 or later on Node 22, 24.12 or later on Node 24, or Node 25 or later for the TypeScript SDK.
• Each agent framework has its own adapter, such as the openai extra or @struktoai/mirage-vercel.

What to do

To try it:

uv add mirage-ai
npm install @struktoai/mirage-node

CLI install options listed on the page:

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

A workspace can be created and used from the CLI, and snapshotted for restore:

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

For least privilege, mount sensitive backends without EXEC or WRITE where possible, hide paths the agent does not need, and register separate CLI instances per credential.

Caveats

The page gives no policy script syntax, rule file format or default profile. It does not describe a threat model, an audit log, or what isolation Monty or the remote runtimes actually enforce. It also gives no maturity or version information, so the policy docs it links to need checking before relying on any of these controls.