Python Quickstart

Installation

Install Mirage:

uv add mirage-ai

If you are not using uv:

pip install mirage-ai

For VFS types with extra dependencies, install the matching extra:

uv add "mirage-ai[s3]"

Create a Workspace

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

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 "hello mirage" | tee /data/hello.txt')
    result = await ws.shell("cat /data/hello.txt")
    print(await result.stdout_str())

    await ws.close()

asyncio.run(main())

Run Commands

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

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"}\' | tee /data/user.json')

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

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

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

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

    await ws.close()


asyncio.run(main())

Output Limits

To keep huge reads from flooding an agent, cat, grep, rg, head, and tail cap their output at 2000 lines, and every command stops after 600 seconds. When a cap fires, the agent sees the truncated output plus a stderr notice (cat: output truncated at limit (2000 lines); ...). Set your own limits in three places. A mount’s third tuple element covers commands that run on it, command_limits is the default for every session, and a profile’s command_limits applies to sessions created with it:

from mirage import MountMode, Workspace
from mirage.types import Limit, OnExceed
from mirage.vfs.ram import RAMVFS

ws = Workspace(
    {
        "/data": (RAMVFS(), MountMode.WRITE, {
            "grep": Limit(max_lines=50, on_exceed=OnExceed.ERROR),
        }),
    },
    mode=MountMode.WRITE,
    command_limits={"head": Limit(max_lines=500, timeout_seconds=30)},
    profiles={
        "researcher": {"command_limits": {"head": Limit(max_lines=5000)}},
    },
)
ws.create_session("research", profile="researcher")

A command’s limit comes from the first place that names it: the session’s profile, the mount the command runs on, the workspace, then the built-in default. An entry replaces that command’s whole limit, so restate timeout_seconds if you still want a deadline; commands it does not name keep their defaults.

max_lines / max_bytes cap the output; None means no cap.
timeout_seconds is a deadline; a command that runs past it exits 124.
on_exceed=TRUNCATE (default) keeps the capped output, adds a stderr notice, and leaves the exit code alone. ERROR drops the output and exits 1, so && and || see the failure.

Caps apply to what each command prints, one command at a time: cat big.txt; echo end still prints end. Data going into a pipe, a redirect, or $(...) is never cut, so cat big.txt | wc -l counts every line. The workspace YAML takes the same fields under command_limits; see Command limits.

Workspace documents and sessions

See Workspace to expose optional, profile-aware /VFS.md and /SKILL.md files and change a session’s profile through the application API, CLI or HTTP.

Next Steps

See Python Installation for VFS extras and the uv workflow.
Browse Python Agents to wire Mirage into the OpenAI Agents SDK, LangChain, Pydantic AI, and OpenHands.
Pick a real backend from VFS Docs, such as S3, Slack, or GitHub.

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Python Quickstart

Installation

Create a Workspace

Run Commands

Output Limits

Workspace documents and sessions

Next Steps

​Installation

​Create a Workspace

​Run Commands

​Output Limits

​Workspace documents and sessions

​Next Steps

Installation

Create a Workspace

Run Commands

Output Limits

Workspace documents and sessions

Next Steps