Skip to main content

Local development

From source​

Requires Python 3.11 or newer and Pango.

# macOS
brew install pango
# Ubuntu
sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 fonts-dejavu-core
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python run.py

Matilda serves http://localhost:8000. Chat is at /chat, the dashboard at /dashboard. State is written to ./data.

Set MATILDA_RELOAD=1 for auto-reload on file changes.

In Docker​

The same image used in production, with Python 3.14, Pango, and all dependencies baked in.

cp .env.example .env
scripts/matilda.sh up          # or: docker compose up --build

This builds from source and publishes on http://localhost:8000, bound to loopback because the dashboard shows lead PII.

scripts/matilda.sh ps          # container status
scripts/matilda.sh logs        # tail logs
scripts/matilda.sh down        # stop

Multiple instances​

To run a second instance side by side, copy .env to .env.<name>, set MATILDA_INSTANCE and a distinct MATILDA_HOST_PORT, and run:

scripts/matilda.sh up <name>

Each instance gets its own container, volume, and database.

Minimum useful configuration​

Nothing is required to boot, but for a useful local instance set:

KIMI_API_KEY=                          # without it Matilda replies "getting set up"
MATILDA_DASHBOARD_OWNER_EMAILS=you@example.com
MATILDA_DASHBOARD_SEED_PASSWORD=change-me-on-first-login
MATILDA_DASHBOARD_SECRET=<long-random>

Without a Resend key, web-chat login codes are printed to the log so you can still sign in.

Useful commands​

pip install -r requirements-dev.txt && pytest      # run the test suite
python -m matilda.seed [--reset] [--seed N]        # generate sample leads
python scripts/fub_provision_fields.py             # one-time Follow Up Boss field setup
python scripts/reset_lead.py                       # reset a single lead

Design system guardrails​

The design system in matilda/ui.py is inlined into every page so the lead PDF, handoff email, and offline PWA are self-contained. When contributing UI:

  • No new fonts or accent hues
  • No backdrop-filter or aurora effects in anything WeasyPrint or email renders
  • Glass text must stay above WCAG AA in both light and dark schemes