Introduction

• 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 runtimes.
• 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

• Virtual filesystem. Virtualize S3, Drive, Slack, databases and more under one root, accessible with ls, cat, grep and find.
• Virtual CLIs. Give agents commands such as git, slack and ntn, with credentials configured per tool.
• Mirage shell. Compose files, CLIs and runtimes with pipes, redirects, variables and jobs.
• Agent profiles. Choose what each agent can run and which files and folders it can see.
• Policy engine. Apply rules to commands, file operations and session changes before they run.
• Runtimes. Run code in the workspace, on your host, in a sandbox or on a remote 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. Across 200 tasks, it used 52% fewer tokens per task than MCP tools (AgentVFS).
• 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.
• Full control. Choose which files each agent can see and which commands it can run with agent profiles and policies.

​

Try Mirage

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())

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()

cat > workspace.yaml <<'EOF'
mounts:
  /data:
    vfs: ram
    mode: write
EOF

mirage workspace create workspace.yaml --id hello
echo "hello mirage" | mirage vfs write /data/hello.txt -w hello
mirage shell -w hello -c 'grep -n hello /data/hello.txt'

1:hello mirage

​

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

​

Explore Mirage

​

Community & Support