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
Node.js (for building the player web client frontend)
Optional: Prometheus/Grafana for monitoring dashboards

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¶

Note: uv sync is the supported installation method for workspace development. A root pip install -e . installs only the root virtual package and may not install all workspace packages. Use uv sync for the full development environment.

If you prefer pip for a minimal install:

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_DATABASE__HOST=localhost
MAID_DATABASE__PORT=5432
MAID_DATABASE__NAME=maid
MAID_DATABASE__USER=maid
MAID_DATABASE__PASSWORD=secret

See the Configuration Reference for all available options.

Env var forms and how .env is read

These examples use the nested __ delimiter, which addresses a settings group by its field name on the root Settings object — note the database group's field is database, so it is MAID_DATABASE__* (not MAID_DB__*). This nested form is read directly from .env. The alternative single-underscore group prefixes (MAID_DB_*, MAID_AI_*, …) are read from the process environment rather than a plain .env, so use them with uv run --env-file .env …, or export them first with set -a; source .env; set +a.

Starting the server on a clean install also requires MAID_DEBUG=true (development) or a secure MAID_ADMIN_SECRET_KEY of 32+ characters (production), because the admin secret-key check reads the real environment.

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.