← Back to News and Blogs
Open SourceVirtual TerminalAI AgentVFSCLIMachine

Mirage: A Virtual Terminal for AI Agents

Mirage is a virtual terminal for AI agents. It virtualizes the terminal environment, so AI agents can use a terminal everywhere.

Mirage: A Virtual Terminal for AI Agents

LLMs are post-trained in terminal environments, so AI agents are most familiar with the terminal interface. But a terminal today is bound to a single machine and its operating system kernel, with its files and its computation on that same machine.

Today we officially release Mirage, a lightweight virtual terminal which separates the terminal interface from the data storage and the computing machines. It virtualizes the shell, the filesystem, the CLIs and the machines.

With Mirage, each virtual terminal starts with only KBs of memory, so AI agents can use terminal environments everywhere, inside an application, a mobile app, a browser tab, a FastAPI or Express server, and even an edge device such as a Raspberry Pi.

The Mirage architecture

Unified Virtual Filesystem

The base of the virtual terminal is a unified virtual filesystem. As LLMs are post-trained heavily on the terminal, Unix-like tools such as ls, cat, grep, find and jq are already in their memory. Mirage virtualizes about 60 data stores, such as S3, Google Drive, Slack, Gmail, Notion, GitHub, Postgres, Redis and local disk, into one virtual filesystem where each appears as files. One command line from an agent then works across services, such as grep -rl invoice /slack /gmail > /s3/hits.txt.

Mirage also integrates each service's own cloud features into Unix command semantics. For example, grep -r uses the service's cloud search, such as Google Drive, Slack or Gmail search.

VFS1
/github
GitHubstrukto-ai/mirage
read
token
Commands7
grep
-r-R-l-w-i
allow
cdechowhoamiwhichmanclear

A real Mirage Virtual Terminal, running in browser?

The strukto-ai/mirage repository on GitHub as a read-only VFS, where only grep's -r, -R, -l, -w and -i and a few builtins are allowed. A GitHub token in Settings lets grep ask GitHub's code search first.

Virtual CLIs

Beyond the Unix-like commands, Mirage virtualizes agent tools as CLIs, such as gh for GitHub, slack, ntn for Notion and linear, without system installation. Each CLI is embedded in the virtual terminal and stays virtualized, yet --help, man and which treat it like an installed program. One tool can be virtualized several times under different profiles, each with its own credentials, and any other tool can be registered as a custom CLI.

As CLIs, the tools are exposed progressively. An agent reads a CLI's --help for its subcommands only when it needs that tool, then one subcommand's --help for its options, so only what it needs enters its context instead of every tool's schema up front. One shell instead of a tool per service also saves tokens, up to 90% fewer than MCP tools in the AgentVFS evaluation. Mirage can also document the installed CLIs in a SKILL.md, each with its top-level help, leaving out anything the session's profile denies.

An MCP tool can become a command of a virtual CLI too, used the same way as any other CLI. Its --help prints the tool's description and the JSON schema of its arguments, and it takes those arguments as one JSON object.

CLIs1
Model Context Protocolmcp.deepwiki.com
mcp

A real Mirage Virtual Terminal, running in browser?

The DeepWiki MCP server installed as deepwiki-mcp, following the MCP documentation. The name can be changed in Settings.

Policies

Policies give fine-grained control over how the terminal is used, based on the commands, the virtual filesystem and other metadata of each session. Every session runs under a profile. allow, ask and deny rules accept or reject each command and CLI, hide and show rules decide which files a session sees, and each VFS's mode decides where it may write. A hidden file is missing from listings and fails to open as if it never existed.

The policy layer is scriptable too. A policy script runs in a small sandbox inside the process and gets the command, its arguments, the paths it touches, the working directory and the session's variables, and can read files through the virtual filesystem before it decides. It can refuse the command, hold it for a person to approve, or pick the machine it runs on, and the same engine is asked before every network connection.

VFS1
/project
ram
write
Paths3
hide
*.pem/project/secrets
show
/project/secrets/README.md
Commands4
allow
*
deny
rmmvcurl
Policy script1
policy.py
def pre_command(ctx):
for path in ctx["paths"]:
if path.startswith("/project/incoming/"):
if "| sh" in open(path).read():
return {"kind": "ask", "reason": "the file pipes a download into sh"}

A real Mirage Virtual Terminal, running in browser?

A profile over a project folder. *.pem files and the secrets folder are hidden while the folder's README is shown, rm, mv and curl are denied, and a policy script asks for approval before a command reads a file that pipes a download into sh.

Virtual Machines

Computation is separated from the terminal interface and the virtual filesystem. Each language interpreter and CLI can live on its own machine, such as a lightweight Python interpreter on an in-process virtual machine, a container, a cloud sandbox, a GPU instance or an SSH host.

A machine can be set to capture specific commands, and a route policy changes the machine line by line from its context, not only the command and its arguments but also what it reads on the virtual filesystem. A short script stays in process, a training job goes to a GPU, and each agent can get its own machine. The agent types the same commands either way, and its files do not move.

Machines2
monty
in process
python
pyodide
in process
python
VFS1
/jobs
ram
exec
Route policy1
route.py
PACKAGES = ("numpy", "pandas")
def source(ctx):
code = ctx["line"]
for command in ctx["commands"]:
for path in command["paths"]:
if path.endswith(".py"):
code += open(path).read()
return code
def pre_execute(ctx):
if not any(c["command"].startswith("python") for c in ctx["commands"]):
return None
if any(package in source(ctx) for package in PACKAGES):
return {"kind": "route", "machine": "pyodide"}
return {"kind": "route", "machine": "monty"}

A real Mirage Virtual Terminal, running in browser?

Two Python interpreters in the browser tab. The route policy reads each line and the scripts it runs from the VFS, sends code that imports numpy to pyodide and keeps the rest on monty.

Mirage Shell

The shell is rewritten in Rust, both the bash parser and the commands such as awk, cut, diff and cat, so one line works the same over every data store, CLI and machine behind the virtual terminal. Pipes, redirection, variables, functions, background jobs and history work across the virtual filesystem, the virtual CLIs and the machines, so gh pr list | grep fix > /s3/prs.txt reads a CLI, filters it and writes to S3 in one line.

Each part of the shell's state can be kept on one's own infrastructure. Sessions, with their working directory, variables and functions, are kept in RAM, on disk, in Redis or in S3, and background jobs with their output in RAM or Redis.

VFS2
/data
ram
read
/reports
ram
write
Machines1
monty
in process
python
Store1
execution
ram
jobs
url

A real Mirage Virtual Terminal, running in browser?

Logs on one RAM filesystem turned into reports on another with pipes, redirects and Python, and a background job tracked with jobs and wait. Job output stays in RAM until an Upstash Redis URL is set in Settings.

Mirage over three virtual filesystems (S3, Slack, Google Drive), three virtual CLIs (gh, linear, deepwiki-mcp), three machines (Monty, an E2B sandbox, an EC2 GPU) and a policy layer: one grep searches all three filesystems, the three CLIs feed one grep, one pipeline runs a stage on each machine, and policy refuses a line that reads a hidden .pem key, deletes from the read-only /s3 VFS and merges a PR.

In Summary

  • Controllable. Each agent gets only the files, commands, credentials and machines its profile allows.
  • Scriptable. The whole terminal is defined in code or one config file, from its filesystems, CLIs and machines to its rules.
  • Managed. State lives on infrastructure that already runs, such as RAM, disk, Redis or S3, and every command is recorded and can be exported as an OpenTelemetry trace.
  • Lightweight. Each workspace takes only KBs of memory and Mirage is async from the shell down to each service call, so one process serves many agents at once. It can be deployed almost everywhere, to a Python or TypeScript server, a browser tab, a Cloudflare Worker or a Raspberry Pi.
$uv add mirage-ai$npm install @struktoai/mirage-node$npm install -g @struktoai/mirage-cli

See the Mirage page for more details, the installation page for each package and its requirements, the documentation and the repository. More from Strukto is on the home page.