Backups, Restore & Keys
Encrypted backups
Section titled “Encrypted backups”deploy/trioditis backup creates an atomic, encrypted snapshot while the server is briefly stopped:
deploy/trioditis backup ~/trioditis-backupsThe destination must live outside your git checkout (container image builds copy the checkout).
Each backup creates a 0700 directory named <project>-<date>-<time> (appending -2, -3, … rather than overwriting) containing three 0600 files:
archive.enc— Encrypted archive of every Docker volume belonging to this Compose project (including volumes for previously disabled networks), ending with a manifest of entry counts, byte sizes, version, and PostgreSQL major version.secrets.env.enc— Encrypted installer settings fromdeploy/install/env-names, excluding the server’s private keys andBACKUP_KEY.backup.info— Unencrypted metadata (format version, project name, git commit, timestamp) needed before restore starts.
Encryption & safety guarantees
Section titled “Encryption & safety guarantees”- Streamed AES-256-GCM encryption:
deploy/scripts/backup-crypt.mjs(running offline in the bundle’s Node image) encrypts volumes and settings directly into 64 KiB authenticated chunks under per-file keys derived fromBACKUP_KEY. Plaintext archives and secrets never touch the destination disk—staging happens in memory (/dev/shmor user runtime dir). - Atomic publish: Files stage privately and rename into place only after a second parser verifies
secrets.envmatches the allowlist and confirms no private key orBACKUP_KEYappears inside. An interrupted backup (Ctrl-C) leaves nothing behind. - Exact service restart: Only containers that were running beforehand are restarted (in dependency order, waiting up to two minutes per health check).
Restoring a backup
Section titled “Restoring a backup”deploy/trioditis restore ~/trioditis-backups/trioditis-20261120-040000Pass --yes to skip the interactive confirmation prompt. Before stopping anything, restore verifies that:
- The backup decrypts cleanly with this install’s
BACKUP_KEY. - It matches this install’s Compose project name and server public keys (
BRIDGE_PUBLIC_KEYandAGENT_ACCESS_PUBLIC_KEY). - Your git checkout is at the commit recorded in
backup.info(whose schema matches the backup’s data).
Restoring onto a brand-new server (where deploy/.env does not exist yet):
- Clone the repository and check out the exact commit listed in
backup.info. - Restore with
--keys, passing your previously exported key file—this imports the keys, restores all volumes and settings, and reruns the installer in one step:
deploy/trioditis restore --keys ~/trioditis-server-keys.env <backup-dir>Managing the server’s keys
Section titled “Managing the server’s keys”A Trioditis server keeps three critical keys in deploy/.env:
BRIDGE_PRIVATE_KEY— Unseals outbound messages, scheduled sends waiting for their send time, and encrypted login input.AGENT_ACCESS_PRIVATE_KEY— Unseals chats explicitly granted to AI agents over MCP.BACKUP_KEY— Encrypts and decryptsarchive.encandsecrets.env.encin backups.
Backups never contain any of these three keys, and no Docker volume stores them.
Exporting and importing keys
Section titled “Exporting and importing keys”Export all server keys once after installation (and again if upgrading from an older install before BACKUP_KEY existed), store the file separate from your backups (password manager or offline media), and delete the copy on the server:
deploy/trioditis keys export ~/trioditis-server-keys.envkeys export writes a new 0600 file, refuses to overwrite an existing file or write inside the checkout, and never prints key material.
To restore keys onto a replacement server:
deploy/trioditis keys import ~/trioditis-server-keys.envkeys import derives public keys offline in the bundle’s Node container and refuses malformed or mismatched key pairs.
If the server keys are lost
Section titled “If the server keys are lost”-
Lost
BACKUP_KEY: Encrypted backups created with that key cannot be decrypted. -
Lost bridge or agent-access keys: Regenerate missing private halves with:
Terminal window deploy/install/install.sh --new-server-keysThis is the only way the installer replaces a server key. In-flight or scheduled sends sealed to the old bridge key fail cleanly (
invalid_command) so members can resend them, and chats granted to agents must be re-granted. Stored message history sealed to each member’s own identity key is completely unaffected.
Encryption at rest
Section titled “Encryption at rest”While Trioditis seals stored messages, attachments, chat names, and contact profiles in Convex to each member’s identity key, upstream bridgev2 connectors keep operational state in PostgreSQL—some of which is plaintext (chat names, contact names, phone numbers, and pending history-sync batches).
Always run Trioditis on an encrypted disk (LUKS/dm-crypt, encrypted ZFS, or encrypted VM host storage). Backups are already encrypted with BACKUP_KEY by deploy/trioditis backup. The installer checks Docker’s block device for dm-crypt and prints a reminder if it cannot confirm encryption (note that host-level VM encryption or ZFS native encryption cannot be detected from inside a guest).