Installation¶

This guide covers how to install MAID and its dependencies.

Prerequisites¶

Before installing MAID, ensure you have:

Python 3.12 or higher - MAID uses modern Python features
uv (recommended) or pip - For package management

Installing Python 3.12+¶

Ubuntu/DebianmacOS (Homebrew)Windows

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv

brew install python@3.12

Download and install from python.org

Installing uv (Recommended)¶

uv is a fast Python package manager that MAID uses for development:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or with pip:

pip install uv

Installation Methods¶

Using uv (Recommended)¶

Clone the repository and install dependencies:

git clone https://github.com/Qworg/MAID.git
cd MAID
uv sync

This creates a virtual environment and installs all dependencies, including the default Anthropic AI provider.

With Optional AI Providers¶

MAID supports multiple AI providers. Install the ones you need:

# OpenAI support
uv sync --extra openai

# Ollama support (local AI)
uv sync --extra ollama

# All AI providers
uv sync --all-extras

Using pip¶

If you prefer pip:

git clone https://github.com/Qworg/MAID.git
cd MAID
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Verifying Installation¶

After installation, verify MAID is working:

# Check version
uv run maid version

# View available commands
uv run maid --help

# Show system information
uv run maid dev info

You should see output similar to:

MAID Engine version 0.1.0

Development Installation¶

For contributing to MAID, install with development dependencies:

uv sync

This includes:

pytest - Testing framework
pytest-asyncio - Async test support
pytest-cov - Coverage reporting
ruff - Linting
mypy - Type checking

Run the test suite to verify everything works:

uv run pytest packages/

Configuration¶

MAID uses environment variables for configuration. Create a .env file in your project root:

# AI Configuration (required for AI features)
MAID_AI__DEFAULT_PROVIDER=anthropic
MAID_AI__ANTHROPIC_API_KEY=sk-ant-...

# Server Configuration (optional)
MAID_TELNET__PORT=4000
MAID_WEB__PORT=8080
MAID_GAME__TICK_RATE=4.0

# Database Configuration (optional, defaults to in-memory)
MAID_DB__HOST=localhost
MAID_DB__PORT=5432
MAID_DB__NAME=maid
MAID_DB__USER=maid
MAID_DB__PASSWORD=secret

See the Configuration Reference for all available options.

Troubleshooting¶

Python Version Issues¶

If you see errors about Python version:

# Check your Python version
python --version

# Use a specific Python version with uv
uv python install 3.12
uv sync

Missing Dependencies¶

If imports fail:

# Reinstall dependencies
uv sync --reinstall

Permission Issues¶

On Linux/macOS, you may need to adjust permissions:

# Make sure you own the project directory
sudo chown -R $USER:$USER MAID/

Next Steps¶

Now that MAID is installed, continue to the Quickstart Guide to start your first server.