Mirage is a virtual terminal for AI Agents, with the goal of unifying the file system, command-line tools, and runtime to provide Agents with a consistent, sandboxable operating environment across local and cloud.
[Purpose and Positioning] Mirage mounts multiple data sources as a virtual file system under the same root directory, allowing Agents to access different services through unified POSIX semantics. It also virtualizes command-line tools and runtime, so Agents can drive services without actually installing the relevant programs on the machine, and binds the file system, CLI, and runtime into a single virtual terminal command line.
[Main Capabilities]
- Unified virtual file system: Services such as S3, Google Drive, Slack, Gmail, and Redis are mounted side by side under a single root directory, and the backend follows the same file system semantics, so Agents can operate them with Unix tools such as ls, grep, find, and jq. Agents can access them through the Python and TypeScript SDKs, the mirage CLI, or real mount points via FUSE and FSKit.
- Virtual command-line tools: git, slack, ntn, etc. are responded to by Mirage itself, so Agents can drive services without installing the corresponding programs, and can do so across runtimes and machines. The same tool can be virtualized as multiple instances under different names, each using independent credentials.
- Dynamically routed runtime: Python, JavaScript, and any other commands can be sent to a configured runtime (in-process, sandboxed, or remote). Computation and storage are decoupled, and the two can be changed independently. A scripted runtime router can be used to decide which runtime handles a given line.
- Virtual Shell: Binds the file system, CLI, and runtime into a single command line, and pipes, redirection, variables, tasks, and history all work across the three.
- Agent-oriented Profiles: allow, ask, and deny control commands and CLIs; hide and show control files and folders; hidden paths are not only unreadable but completely disappear from the file system as seen by the Agent.
- Scriptable policy engine: Policy scripts can prohibit dangerous operations before they are executed; the same policy stack checks every VFS operation and session write to prevent leakage of files or environment variables. Policies can only restrict, not grant, permissions.
- Notification mechanism: External changes become an event stream on the mount point, for examplea new Slack reply appears as a change to a chat file in the virtual file system, and the Agent can react accordingly without rescanning the directory tree.
[How to Use] The official README gives an example of starting Mirage in an application, but does not provide the complete code content, and the specific startup steps are not yet provided. The known installation and environment requirements are: the mirage-ai package and the mirage CLI require Python ≥ 3.11; the TypeScript SDK requires Node.js ≥ 20. Both runtime packages automatically bring in @struktoai/mirage-core. Credentials and authentication can integrate with existing secret stores such as AWS Secrets Manager, 1Password, Auth0, and dotenv, so that environment variables in Mirage can resolve directly to the credentials stored there.
[Applicable Scenarios] Scenarios that require allowing Agents to access data uniformly across multiple data sources, control what operations Agents can perform and what they can see with scripted policies, and route command execution to different runtimes.
[Limitations and Information Not Provided] The project uses the Apache-2.0 license. The materials do not provide specific pricing, charging model, performance data, limitation items, or a list of supported platforms; this information is not yet provided.
