- 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.
Architecture
- Virtual filesystem. Virtualize S3, Drive, Slack, databases and more under one root, accessible with
ls,cat,grepandfind. - Virtual CLIs. Give agents commands such as
git,slackandntn, with credentials configured per tool. - Mirage Shell. Compose files, CLIs and machines with pipes, redirects, variables and jobs.
- Session profiles. Choose what each agent can run and which files and folders it can see.
- Policy engine. Apply rules to commands, file operations and connections before they run.
- Machines. Run programs in the workspace, on your host, or on a container, microVM, cloud sandbox or SSH host.
- Runtimes. Run Python and JavaScript on an interpreter inside a machine.
- Service credentials. Connect credentials from environment variables, dotenv, AWS Secrets Manager or 1Password.
- Notifications. Notify agents about external file or directory changes in the virtual filesystem.
Benefits
- Fewer tokens. One shell interface replaces a tool per service, so agents use up to 90% fewer tokens than with MCP tools (AgentVFS).
- Low cost. A sandbox reserves memory for every agent, busy or idle. An idle Mirage terminal is a record of about 10 KB in your server’s memory, so one server holds thousands. See the comparison.
- Deep integration with each service. The virtual filesystem translates
Unix commands into each service’s own features, so
greporrgruns as the service’s search instead of reading every file. See Search. - Full control and safety. Choose which files each agent can see and which commands it can run with session profiles and policies. Agents use credentials without seeing them: keys stay in the server’s memory, never in a file or variable an agent can read, so an agent cannot leak them.
Try Mirage
Install Mirage, then create a workspace with an in-memory filesystem, write a file with a POSIX-style call, and search it with the shell. No credentials or services are needed.- Python
- TypeScript
- CLI
/data is a path inside Mirage. Replace RAM with a supported VFS
to use the same commands on your own data. Continue with the
Python or TypeScript quickstart.
Example Use Cases
See the examples.FAQ
Do I need FUSE?
Do I need FUSE?
It is not required, but use FUSE where the platform supports it. Without it, agents use workspace files through Mirage. With it, the workspace is a real folder on the host, so host tools such as editors and language servers can open those files too.
Where does the shell run? Is it really bash?
Where does the shell run? Is it really bash?
Mirage provides a Bash-compatible shell in your application. It supports common commands, pipes, redirects, variables and jobs. See the shell guide for supported behavior and differences from Bash.
Is it sandboxed?
Is it sandboxed?
The shell sees only the virtual filesystems in its workspace, and a session profile can narrow that further. A program sent to a machine gets that machine’s file and network access, so check machine file and network access before choosing one.
What about latency and cost?
What about latency and cost?
Operations use the APIs of the services you connect, so their latency and usage charges apply.
Which agent frameworks are supported?
Which agent frameworks are supported?
Any agent that can call a shell tool can use Mirage. See the agent integrations for setup guides.
Python or TypeScript?
Python or TypeScript?
TypeScript is recommended. It runs in Node, the browser and Cloudflare Workers. Both SDKs provide workspaces, shell commands and service integrations, and the runtime comparison shows where their runtimes differ. Start with the TypeScript or Python quickstart.
What if a VFS I want isn't supported yet?
What if a VFS I want isn't supported yet?
You can add a custom filesystem. See Add a VFS for the required API and examples.
Explore Mirage
Python Quickstart
Create a workspace, add virtual filesystems, and run shell commands in minutes.
TypeScript Quickstart
Same Workspace API in Node, browser, and edge runtimes.
CLI
Drive workspaces from the shell: create, run shell lines, snapshot, and restore.
Supported VFS
Compare supported VFS types and connect S3, Drive, Slack and more.
Community & Support
To let your coding agent search these docs, connect it to the docs MCP server athttps://docs.mirage.strukto.ai/mcp.
Need Help?
Setup failures, credential issues, and FUSE gotchas.
Book a Call
Talk to the team directly if you are blocked.
Join our Discord
Chat with the community and get help from the team.
GitHub Issues
Report bugs, request features, or ask questions.