> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
uv add mirage-ai
```

If you are not using uv:

```bash theme={null}
pip install mirage-ai
```

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

```bash theme={null}
uv add "mirage-ai[s3]"
```

## Create a Workspace

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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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](/home/yaml#command-limits).

## Workspace documents and sessions

See [Workspace](/home/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](/python/install) for VFS extras and the `uv` workflow.
* Browse [Python Agents](/python/agents/index) to wire Mirage into the OpenAI Agents SDK, LangChain, Pydantic AI, and OpenHands.
* Pick a real backend from [VFS Docs](/python/vfs/index), such as [S3](/python/vfs/s3), [Slack](/python/vfs/slack), or [GitHub](/python/vfs/github).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.