Backups

Everything Wireface Chat stores is in its data directory (DATA_DIR; /data in Docker):

Path	What
wireface.db (with wireface.db-wal and wireface.db-shm while running)	The SQLite database: bots, conversations, visitors, leads, team, settings, encrypted keys and secrets
files/	Uploaded images, camera frames that are kept, custom faces, knowledge files, cached voice previews
master.key	The master key, unless you set WIREFACE_MASTER_KEY

Taking a backup

The database runs in WAL mode, so copying wireface.db while the server writes can give an inconsistent copy. The simple, safe way is a short stop:

docker compose -f docker/compose.yml stop wireface-chat
docker compose -f docker/compose.yml cp wireface-chat:/data ./wireface-backup-$(date +%F)
docker compose -f docker/compose.yml start wireface-chat

Or, while it runs, use SQLite's online backup for the database (sqlite3 wireface.db ".backup backup.db", or VACUUM INTO 'backup.db') and copy files/ alongside.

The master key

Provider API keys, webhook and identity secrets, tool secrets, and MCP headers and environment are encrypted (AES-256-GCM) with the master key. Without it they can't be decrypted: a restored database with the wrong key works, but every provider key and secret has to be entered again (the server logs "could not decrypt a stored secret").

• Keep a copy of the master key somewhere other than the data backups, e.g. a password manager. It is the contents of master.key (base64), or your WIREFACE_MASTER_KEY.
• To move from the file to an environment variable, set WIREFACE_MASTER_KEY to the file's contents.
• Changing the key:
  1. Back up the data directory.
  2. Set the new key as WIREFACE_MASTER_KEY and the current one as WIREFACE_MASTER_KEY_OLD, and restart.
  3. At startup the server re-encrypts every stored secret (provider keys, tool secrets, identity and webhook secrets, MCP headers and environment) with the new key, and logs how many it moved: "Master key rotation: sealed N stored secrets with the new key". Anything that opens with neither key is logged as an error, to be entered again in the admin panel.
  4. Once a start logs that every stored secret already uses the new key, remove WIREFACE_MASTER_KEY_OLD.

Restoring

Stop the server, put the backup in place of the data directory, and start it again with the same master key. In Docker, restoring into the volume (the server runs as the node user, so the files must belong to it):

docker compose -f docker/compose.yml stop wireface-chat
docker compose -f docker/compose.yml run --rm --user root -v "$PWD/wireface-backup-2026-10-07:/backup" wireface-chat \
  sh -c 'rm -rf /data/* && cp -a /backup/. /data/ && chown -R node:node /data'
docker compose -f docker/compose.yml start wireface-chat