Python Quickstart - Mirage

Installation

Use Python 3.12 or newer. In a uv project, install Mirage with:

uv add mirage-ai

In another activated environment, install it with:

python -m pip install mirage-ai

Create a Workspace

Start with the RAM VFS so you can try Mirage without credentials.

quickstart.py

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.ram import RAMVFS


async def main() -> None:
    ws = Workspace({"/data": RAMVFS()}, mode=MountMode.WRITE)
    await ws.shell('echo \'{"name": "alice"}\' > /data/user.json')

    files = await ws.shell("ls /data")
    print(await files.stdout_str(), end="")

    name = await ws.shell('jq -r ".name" /data/user.json')
    print(await name.stdout_str(), end="")

    match = await ws.shell("grep alice /data/user.json")
    print(await match.stdout_str(), end="")

    await ws.close()


asyncio.run(main())

For a uv project, run uv run python quickstart.py. If you installed Mirage in another activated environment, run python quickstart.py. It lists user.json, prints alice, then prints the matching JSON document. Shell failures are returned in the result; check exit_code and stderr_str() when needed. See the in-app API reference.

Next Steps

See Python Installation for VFS extras and the uv workflow.
Configure command output limits for large files and long-running commands.
Browse Python Agents to wire Mirage into the OpenAI Agents SDK, LangChain, and Pydantic AI.
Pick a real backend from VFS Docs, such as S3, Slack, or GitHub.