Updates

Mandala can update itself from signed releases, or you can install a build yourself. Either way, the previous version is kept and put back if the new one does not come up.

Self-update

Settings → Updates (off by default):

Check now looks at once.

How it stays safe

1. A release is an archive (bin/mandala and web/) and a manifest signed with your release key, which never sits on a server. A node accepts only a manifest signed by that key (MANDALA_UPDATE_PUBLIC_KEY in mandala.env, or pasted in Settings), for its own platform, and newer than what it runs.
2. The archive's SHA-256 must match the signed one; only bin/ and web/ are unpacked; the new binary must run and print the release's version before anything is swapped.
3. The running binary is kept as mandala.prev and the web app as web.prev; Mandala stops gracefully and the service manager starts the new one.
4. The new binary counts its starts: after 3 failed starts, or if /health has not answered within 180 seconds, the previous binary and web app are put back.

Your home node serves the release channel to your other nodes (linux-x86_64, linux-aarch64, and the Mac app's).

Publishing a release

mandala/deploy/release.sh build 2026.1011.1                      # on the build server: build, package, print the SHA-256
MANDALA_PLATFORM=linux-x86_64 mandala/deploy/release.sh sign 2026.1011.1 mandala-2026.1011.1-linux-x86_64.zip   # where the release key is
mandala/deploy/release.sh publish mandala-2026.1011.1-linux-x86_64.zip latest.json https://<home>.ts.net   # archive first, manifest last

Create the release key once with mandala sign-update --key <file> --generate (the same key as the Mac app's), keep the private half offline, and put the printed public key in each node's MANDALA_UPDATE_PUBLIC_KEY.

By hand, from source

cd mandala && git pull
cargo build --release -p mandala
(cd applications/workspace && npm ci && npm run build)
MANDALA_BIN=$PWD/target/release/mandala mandala/deploy/ship.sh

ship.sh runs the deploy in the background (log: ~/mandala-deploy.log): it keeps mandala.prev and web.prev, installs the new build into ~/.mandala, restarts mandala.service (with sudo systemctl), waits up to 60 seconds for /health, and puts the previous version back if it does not answer.

Before you update

• Back up (Backups and restore). Some releases change how records are written on disk; older versions then cannot read them, so going back after such an update means restoring the backup taken before it.
• Read the Changelog.

After you update

• The Docs vault refreshes with the new release's pages (The Docs vault).
• Built-in contracts with a new version upgrade your records at startup, under your delegation.
• The Mac app keeps its own updater (Install on a Mac).