MatCraft can run entirely on your local machine for development, testing, or air-gapped environments. There are two approaches: using just the Python core library, or running the full platform stack.
If you only need the optimization engine without the web dashboard:
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the core library
pip install matcraft
# Verify installation
materia --versionThis gives you the CLI, Python SDK, all domain plugins, and the surrogate/optimizer stack. No database or additional services are required — campaign state is stored in local SQLite by default.
To run the complete platform including the web dashboard, API server, and task queue:
# Clone the repository
git clone https://github.com/matcraft/matcraft.git
cd matcraft
# Backend
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env # Edit with your database credentials
# Run database migrations
materia db upgrade
# Start the API server
uvicorn materia.api:app --reload --port 8000
# In a separate terminal, start the Celery worker
celery -A materia.tasks worker --loglevel=info# Frontend (in another terminal)
cd frontend
pnpm install
pnpm dev # Starts on http://localhost:3000Key variables in your .env file:
DATABASE_URL=postgresql://user:pass@localhost:5432/matcraft
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-secret-key-here
MATCRAFT_ENV=developmentThe development server includes hot-reloading for both frontend and backend changes.