Installation

Quick Install

Install the base package into your project:

uv add mirage-ai

This is enough to start with local workflows such as the RAM VFS and to understand the Mirage execution model. If you are not using uv:

pip install mirage-ai

If you only want the mirage CLI (not the library), there are two convenient paths. One-shot run with uvx, no install, just runs:

uvx mirage-ai --help
uvx mirage-ai workspace create workspace.yaml --id demo

Persistent install with uv tool install, drops mirage on your PATH globally:

uv tool install mirage-ai
mirage --help

To upgrade later:

uv tool install --upgrade mirage-ai

Install extras when a VFS needs optional dependencies:

uv add "mirage-ai[s3]"
uv add "mirage-ai[r2]"
uv add "mirage-ai[redis]"
uv add "mirage-ai[fuse]"

Use the VFS docs in the Python section when you are ready to connect real systems.

If you are contributing to Mirage or want the full local development setup:

git clone https://github.com/strukto-ai/mirage.git
cd mirage/python
uv sync --all-extras --no-extra camel

The camel extra conflicts with the openai stack, so excluding it keeps everything else installable in one shot.

Install the base package.
Follow the Python Quickstart with the RAM VFS.
Add the VFS extras and follow the FUSE setup if you need to expose mounts as a real filesystem.