> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A composable, scriptable and durable virtual terminal for AI agents.

Mirage is a virtual terminal for AI agents, with a unified virtual filesystem,
virtual CLIs and a router that picks where each command runs.

* **Composable.** The filesystem, CLIs, shell and compute are separate parts you
  put together. Run the terminal in your app or a FastAPI or Fastify server, and
  send programs to a microVM or sandbox.
* **Scriptable.** A scriptable policy engine, written in code or as scripts, hides files per
  agent profile, refuses commands, asks for approval, caps output and routes
  commands to machines.
* **Durable.** Each part can live in your own storage: sessions in RAM, each
  shell job's output in Redis, and the history of every command on disk.

## Architecture

![Mirage connects agents to files, tools, machines and runtimes, with access controls and notifications](https://mintcdn.com/struktoai/DFcmqNyceJW-5m2z/images/mirage-overview-light.svg?fit=max\&auto=format\&n=DFcmqNyceJW-5m2z\&q=85\&s=924ce92bc557439868d62e838557ca0e)

* **[Virtual filesystem](https://docs.mirage.strukto.ai/home/setup/vfs.md).** Virtualize S3, Drive, Slack, databases and more under one root, accessible with `ls`, `cat`, `grep` and `find`.
* **[Virtual CLIs](https://docs.mirage.strukto.ai/home/setup/clis.md).** Give agents commands such as `git`, `slack` and `ntn`, with credentials configured per tool.
* **[Mirage shell](https://docs.mirage.strukto.ai/home/core/shell.md).** Compose files, CLIs and machines with pipes, redirects, variables and jobs.
* **[Agent profiles](https://docs.mirage.strukto.ai/home/profiles.md).** Choose what each agent can run and which files and folders it can see.
* **[Policy engine](https://docs.mirage.strukto.ai/home/policy/policies.md).** Apply rules to commands, file operations and connections before they run.
* **[Machines](https://docs.mirage.strukto.ai/home/setup/machine/overview.md).** Run programs on a container, microVM, cloud sandbox or SSH host.
* **[Runtimes](https://docs.mirage.strukto.ai/home/setup/runtime/overview.md).** Run code in the workspace or on your host.
* **[Service credentials](https://docs.mirage.strukto.ai/home/authentication.md).** Connect credentials from environment variables, dotenv, AWS Secrets Manager or 1Password.
* **[Notifications](https://docs.mirage.strukto.ai/home/notifications.md).** Notify agents about external file or directory changes in the virtual filesystem.

## Benefits

* **Fewer tokens.** One shell interface replaces a tool per service. Across 200
  tasks, it used 52% fewer tokens per task than MCP tools
  ([AgentVFS](https://agentvfs.org/blogs/agentvfs-1)).
* **Cloud search through shell commands.** With Chroma at `/knowledge/`,
  `grep -r refund /knowledge/` asks Chroma which documents match, then reads
  only those. A backend without search reads its files. See
  [Search](https://docs.mirage.strukto.ai/home/integration/search.md).
* **Full control.** Choose which files each agent can see and which commands it
  can run with [agent profiles](https://docs.mirage.strukto.ai/home/profiles.md) and
  [policies](https://docs.mirage.strukto.ai/home/policy/overview.md).

## Try Mirage

[Install Mirage](https://docs.mirage.strukto.ai/home/install.md), 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.

> [tab] Python
>
> ```python theme={null}
> import asyncio
>
> from mirage import MountMode, RAMVFS, Workspace
>
>
> async def main() -> None:
>     ws = Workspace({"/data": RAMVFS()}, mode=MountMode.WRITE)
>     await ws.vfs.write("/data/hello.txt", b"hello mirage\n")
>     result = await ws.shell("grep -n hello /data/hello.txt")
>     print(await result.stdout_str(), end="")
>     await ws.close()
>
>
> asyncio.run(main())
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace({ '/data': new RAMVFS() }, { mode: MountMode.WRITE })
> await ws.vfs.write('/data/hello.txt', new TextEncoder().encode('hello mirage\n'))
> const result = await ws.shell('grep -n hello /data/hello.txt')
> process.stdout.write(result.stdoutText)
> await ws.close()
> ```

> [tab] CLI
>
> [Install the CLI](https://docs.mirage.strukto.ai/home/install.md#cli), then run:
>
> ```bash theme={null}
> cat > workspace.yaml <<'EOF'
> mounts:
>   /data:
>     vfs: ram
>     mode: write
> EOF
>
> mirage workspace create workspace.yaml --id hello
> echo "hello mirage" | mirage workspace vfs write /data/hello.txt -w hello
> mirage shell -w hello -c 'grep -n hello /data/hello.txt'
> ```

The search prints:

```text theme={null}
1:hello mirage
```

`/data` is a path inside Mirage. Replace RAM with a [supported VFS](https://docs.mirage.strukto.ai/home/setup/vfs.md)
to use the same commands on your own data. Continue with the
[Python](https://docs.mirage.strukto.ai/python/quickstart.md) or [TypeScript](https://docs.mirage.strukto.ai/typescript/quickstart.md) quickstart.

## Example Use Cases

* **Respond to changes.** React to Slack replies or GitHub pushes through file notifications.
* **Search connected data.** Use `grep` for text search and `search` for semantic matches in vector stores.
* **Investigate traces.** Query Langfuse and Jaeger traces with `grep` and `jq`.

## FAQ

> [accordion] Do I need FUSE?
>
> No. Agents can use workspace files through Mirage directly. Use [FUSE](https://docs.mirage.strukto.ai/home/setup/fuse.md) when host tools, such as editors or language servers, need to open those files.

> [accordion] 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](https://docs.mirage.strukto.ai/home/core/shell.md) for supported behavior and differences from Bash.

> [accordion] Is it sandboxed?
>
> The shell sees the files you mount. The Monty and QuickJS runtimes cannot access host files or the network. Other runtimes have different access; see [runtime file and network access](https://docs.mirage.strukto.ai/home/setup/runtime/overview.md#files) before choosing one.

> [accordion] What about latency and cost?
>
> Operations use the APIs of the services you connect, so their latency and usage charges apply.

> [accordion] Hosted or self-hosted?
>
> Self-hosted. Run Mirage in your own application, server or sandbox, and connect the services you need.

> [accordion] Which agent frameworks are supported?
>
> Any agent that can call a shell tool can use Mirage. See the [agent integrations](https://docs.mirage.strukto.ai/home/agents.md) for setup guides.

> [accordion] Python or TypeScript?
>
> Both SDKs provide workspaces, shell commands and service integrations. Runtime availability differs; see the [runtime comparison](https://docs.mirage.strukto.ai/home/setup/runtime/overview.md). Start with the [Python](https://docs.mirage.strukto.ai/python/quickstart.md) or [TypeScript](https://docs.mirage.strukto.ai/typescript/quickstart.md) quickstart.

> [accordion] What if a VFS I want isn't supported yet?
>
> You can add a custom filesystem. See [Add a VFS](https://docs.mirage.strukto.ai/python/vfs/new.md) for the required API and examples.

## Explore Mirage

> [card] [Python Quickstart](https://docs.mirage.strukto.ai/python/quickstart.md)
>
> Create a workspace, mount your sources, and run shell commands in minutes.

> [card] [TypeScript Quickstart](https://docs.mirage.strukto.ai/typescript/quickstart.md)
>
> Same Workspace API in Node, browser, and edge runtimes.

> [card] [CLI](https://docs.mirage.strukto.ai/home/access/cli.md)
>
> Drive workspaces from the shell: create, run shell lines, snapshot, and restore.

> [card] [Supported VFS](https://docs.mirage.strukto.ai/home/setup/vfs.md)
>
> 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 at `https://docs.mirage.strukto.ai/mcp`.

> [card] [Need Help?](https://docs.mirage.strukto.ai/home/troubleshooting.md)
>
> Setup failures, credential issues, and FUSE gotchas.

> [card] [Book a Call](https://cal.com/strukto/30min)
>
> Talk to the team directly if you are blocked.

> [card] [Join our Discord](https://discord.gg/u8BPQ65KsS)
>
> Chat with the community and get help from the team.

> [card] [GitHub Issues](https://github.com/strukto-ai/mirage/issues)
>
> Report bugs, request features, or ask questions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.