Operations

The matilda.sh helper

scripts/matilda.sh wraps Docker Compose and detects whether it is on a server or a development machine.

Command	Where	What it does
scripts/matilda.sh up [instance]	Dev	Build from source, start, tail logs
scripts/matilda.sh start	Dev	Start without rebuilding
scripts/matilda.sh deploy	Server	Pull the pinned GHCR image and restart
scripts/matilda.sh pull	Server	Pull only
scripts/matilda.sh down	Both	Stop
scripts/matilda.sh logs	Both	Tail logs
scripts/matilda.sh ps	Both	Container status

Bare down and logs target the instance named in .env.

Backups

All state is under the data directory, ./data by default, or the Docker volume for the instance. Back up:

• matilda.db, the SQLite database
• sessions/, agent session state

Stop the container or use SQLite's online backup to get a consistent copy of the database.

Upgrading

On the server, set MATILDA_VERSION in .env to the new tag without the v, then:

scripts/matilda.sh deploy

Schema migrations run automatically on startup. Merges to main deploy automatically in the reference setup, so manual upgrades are only needed for pinned releases.

Rotating secrets

• Webhook token. Generate a new one on Setup, then update the URL in BlueBubbles.
• Worker key. Remove the Mac on Devices. The worker asks to be connected again, and Connect Follow Up Boss mints a new key.
• Session secrets. Change MATILDA_DASHBOARD_SECRET or MATILDA_CUSTOMER_SECRET and restart. Every existing session is invalidated.
• Integration keys. Save the new value on Setup. Owners only.

Troubleshooting

Symptom	Check
Matilda replies "getting set up"	No Kimi key. Add one on Setup and click Test.
Texts arrive but no reply	BlueBubbles URL or password wrong. Click Test on Setup. Check the Private API is on.
No texts arrive	Webhook not registered, or the token in the URL is stale. Regenerate and re-register.
Login codes never arrive	Resend not configured. Codes are printed to the log at the default customer secret.
Cannot sign in to the dashboard	No owner email seeded, or your IP is outside the allowlist.
Handoff email not sent	All three Resend values are required together, plus MATILDA_NOTIFY_EMAILS. Emails fire only once per lead.
Follow Up Boss stage not changing	Stage names must match exactly. Use Test to list them. Stages only move forward.
Worker shows offline	It has not checked in for 90 seconds. Make sure Matilda Worker is running on the Mac, and click Connect Follow Up Boss if it shows not connected.

Logs are the first place to look:

scripts/matilda.sh logs