Python Quickstart

Create a Mirage Python workspace, mount RAM as a virtual filesystem, and run shell commands that read, write, search, and transform files.

Installation

Install Mirage:

uv add mirage-ai

If you are not using uv:

pip install mirage-ai

For resources with extra dependencies, install the matching extra:

uv add "mirage-ai[s3]"

Create a Workspace

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

import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource


async def main() -> None:
    ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

    await ws.execute('echo "hello mirage" | tee /data/hello.txt')
    result = await ws.execute("cat /data/hello.txt")
    print(await result.stdout_str())

    await ws.close()


asyncio.run(main())

Run Commands

Once a resource is mounted, you can use Mirage like a shell over your virtual filesystem:

import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource


async def main() -> None:
    ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

    await ws.execute('echo \'{"name": "alice"}\' | tee /data/user.json')

    result = await ws.execute("ls /data/")
    print(await result.stdout_str())

    result = await ws.execute("cat /data/hello.txt")
    print(await result.stdout_str())

    result = await ws.execute('jq ".name" /data/user.json')
    print(await result.stdout_str())

    result = await ws.execute("grep hello /data/hello.txt")
    print(await result.stdout_str())

    await ws.close()


asyncio.run(main())

Output Safeguards

To keep huge reads from flooding an agent, cat, grep, rg, head, and tail cap their final output at 2000 lines by default. When a cap fires, the agent sees the truncated bytes plus a stderr notice (output truncated at safeguard limit (2000 lines); ...); exit code stays 0.

Caps fire only on the terminal command of a pipeline, so cat big.txt | head -n 30 still shows 30 lines.

Configure per mount

Limits are per-command and per-mount. Attach them when you mount a resource by passing a (resource, mode, {command: CommandSafeguard}) tuple. Each guard sets max_lines / max_bytes (output cap) and/or timeout_seconds (deadline); on_exceed is TRUNCATE (default, exit 0 plus notice) or ERROR (exit 1 plus notice):

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource
from mirage.types import CommandSafeguard, OnExceed

ws = Workspace(
    {
        "/data": (
            RAMResource(),
            MountMode.WRITE,
            {
                "head": CommandSafeguard(max_lines=100),  # cap, keep going
                "grep": CommandSafeguard(max_lines=50, on_exceed=OnExceed.ERROR),
                "rg": CommandSafeguard(timeout_seconds=30),  # deadline
            },
        ),
    },
    mode=MountMode.WRITE,
)

The same limits are available to the CLI as a command_safeguards block in the workspace YAML.

Next Steps

• See Resource Docs for the full list of supported data sources