strukto-ai--mirage/docs/python/quickstart.mdx

---
title: Python Quickstart
icon: /images/python-logo.svg
description: Create a Mirage Python workspace, mount RAM as a virtual filesystem, and run shell commands that read, write, search, and transform files.
keywords: ["Mirage Python quickstart", "mirage-ai", "virtual filesystem", "AI agents", "shell commands"]
---

## Installation

Install Mirage:

```bash
uv add mirage-ai
```

If you are not using uv:

```bash
pip install mirage-ai
```

For resources with extra dependencies, install the matching extra:

```bash
uv add "mirage-ai[s3]"
```

## Create a Workspace

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

```python
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:

```python
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.

```python
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](/home/cli#5-dry-run-with-provision).

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

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