Matilda reads configuration from the environment, normally a .env file copied from .env.example. Integration settings can also be saved live on the dashboard Setup page, where they are stored in the database and take precedence over the environment. No restart is needed for either.
Nothing is required to boot. On an https deployment, two conditions are fatal: a default MATILDA_DASHBOARD_SECRET or a default MATILDA_CUSTOMER_SECRET. A demo email that collides with an owner or admin is also refused. Everything else produces a warning at most.
Instance and Docker
| Variable | Default | Purpose |
|---|
MATILDA_INSTANCE | default | Namespaces the container, project, volume, and database |
MATILDA_HOST_PORT | 8000 | Host port published by Docker |
MATILDA_NETWORK_MODE | bridge | Set host on a Linux server to use the host's WireGuard route and see real client IPs |
MATILDA_VERSION | unset (tracks latest) | Pinned image tag, the git tag without the v |
MATILDA_IMAGE | ghcr.io/shafiqco/matilda | Image name |
MATILDA_SERVER_HOSTNAME, MATILDA_SSH_HOST, MATILDA_ROLE | unset | Only for the SSH-tunnel client/server setup in matilda.sh |
Kimi (Moonshot AI)
| Variable | Default | Purpose |
|---|
KIMI_API_KEY | unset | API key. MOONSHOT_API_KEY is accepted as a fallback name. |
KIMI_MODEL | kimi-k2.6 | Reply model |
KIMI_EXTRACT_MODEL | kimi-k2.6 | Post-turn extraction model |
KIMI_BASE_URL | https://api.moonshot.ai/v1 | API base |
KIMI_MAX_TOKENS | 2048 | Reply token budget, truncated gracefully |
BlueBubbles (iMessage)
| Variable | Default | Purpose |
|---|
BLUEBUBBLES_URL | unset | The Mac running BlueBubbles, a LAN IP or the WireGuard address |
BLUEBUBBLES_PASSWORD | unset | BlueBubbles server password |
MATILDA_WEBHOOK_TOKEN | unset | Token gating /webhook. Normally generated from Setup instead. |
Dashboard login and roles
| Variable | Default | Purpose |
|---|
MATILDA_DASHBOARD_OWNER_EMAILS | unset | Comma-separated owners seeded at startup |
MATILDA_DASHBOARD_ADMIN_EMAILS | unset | Comma-separated admins seeded at startup |
MATILDA_DASHBOARD_TEAM_NAME | unset | Default team the admins are filed on |
MATILDA_DASHBOARD_SEED_PASSWORD | unset | Password applied when an account is first created, stored hashed |
MATILDA_DASHBOARD_SECRET | well-known default | Signs the session cookie. Must be long and random in production. |
MATILDA_DASHBOARD_SESSION_MAX_AGE | 1209600 | Session lifetime in seconds, 14 days |
MATILDA_DASHBOARD_DEMO_EMAIL | unset | Enables the read-only demo login |
MATILDA_DASHBOARD_DEMO_PASSWORD | unset | Re-synced on every boot |
MATILDA_DASHBOARD_ALLOW_CIDRS | open | Optional IP allowlist layered under the login |
MATILDA_DASHBOARD_EMAILS | unset | Deprecated name for the owner list. Honored with a warning. |
Customer login (web chat)
| Variable | Default | Purpose |
|---|
MATILDA_CUSTOMER_SECRET | well-known default | Signs the customer cookie. At the default, codes are also printed to the log. |
MATILDA_LOGIN_CODE_TTL | 600 | Seconds a code is valid |
MATILDA_LOGIN_MAX_ATTEMPTS | 5 | Wrong guesses before a code is burned |
MATILDA_LOGIN_RATE_WINDOW | 900 | Rate-limit window in seconds |
MATILDA_LOGIN_MAX_PER_PHONE | 3 | Codes per phone per window |
MATILDA_LOGIN_MAX_PER_IP | 10 | Codes per IP per window |
Handoff email (Resend)
All three Resend values are required together. Blank disables email; the lead page and PDF still work.
| Variable | Default | Purpose |
|---|
MATILDA_PUBLIC_URL | unset | Absolute URL used only to build the link in the email |
RESEND_API_KEY | unset | Resend key |
RESEND_FROM | unset | From address, for example Matilda <matilda@yourdomain.com> |
MATILDA_NOTIFY_EMAILS | unset | Comma-separated notification list |
Follow Up Boss
| Variable | Default | Purpose |
|---|
FOLLOWUPBOSS_API_KEY | unset | Enables the integration. Unset is a silent no-op. |
FOLLOWUPBOSS_SYSTEM | unset | Registered system name for the X-System header |
FOLLOWUPBOSS_SYSTEM_KEY | unset | Registered system key |
FOLLOWUPBOSS_STAGE_MAP | {"qualified":"Hot Prospect","showing":"Active Client","nurture":"Nurture"} | JSON map from Matilda status to stage name. Empty object disables. |
MATILDA_LOCAL_TZ | unset | IANA timezone for appointment times when the lead's own timezone is unknown |
Server (non-Docker)
Fixed inside Docker. Only apply when running with python run.py.
| Variable | Default | Purpose |
|---|
MATILDA_HOST | 0.0.0.0 | Bind address |
MATILDA_PORT | 8000 | Bind port |
MATILDA_DATA_DIR | ./data | State directory |
MATILDA_DB_PATH | ./data/matilda.db | SQLite file |
MATILDA_SESSIONS_DIR | ./data/sessions | Agent session state |
MATILDA_FORWARDED_ALLOW_IPS | 127.0.0.1 | Proxies trusted for X-Forwarded-For |
MATILDA_COOKIE_SECURE | auto | Secure cookies when MATILDA_PUBLIC_URL is https |
MATILDA_RELOAD | unset | Set 1 for auto-reload in development |