Python Quickstart

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

Estimate Before You Run

execute(..., provision=True) returns a ProvisionResult instead of running the command: network/cache bytes, read ops, and a precision telling you how much to trust the numbers (exact, range, unknown — totals under unknown are floors). Pipelines, &&/||, if/case, loops, and subshells aggregate automatically.

plan = await ws.execute("cat /data/user.json | wc -l", provision=True)
print(plan.network_read, plan.read_ops, plan.precision)

Read commands are estimated out of the box on every backend. When you register your own command, pass provision= to the @command decorator (reuse a helper like make_file_read_provision(my_stat) or default_provision(name, my_stat) from mirage.commands.builtin.generic_bind), or omit it and the planner reports unknown. Full semantics live in the CLI provision docs.

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 Python Installation for resource extras and the uv workflow.
Browse Python Agents to wire Mirage into the OpenAI Agents SDK, LangChain, Pydantic AI, CAMEL, and OpenHands.
Pick a real backend from Resource Docs, such as S3, Slack, or GitHub.

Getting Started

Agents

Resources

Runtimes

Python Quickstart

Installation

Create a Workspace

Run Commands

Estimate Before You Run

Output Safeguards

Configure per mount

Next Steps

​Installation

​Create a Workspace

​Run Commands

​Estimate Before You Run

​Output Safeguards

​Configure per mount

​Next Steps

Installation

Create a Workspace

Run Commands

Estimate Before You Run

Output Safeguards

Configure per mount

Next Steps