Skip to main content
Back up the Podium state directory before changing versions. Database migrations run forward when the new server starts, so an older binary may not be able to reopen upgraded state.

​
Back up state

The default instance stores server state in ~/.podium. Named instances use ${XDG_STATE_HOME:-$HOME/.local/state}/podium/instance_name, and PODIUM_STATE_DIR overrides either location. Stop Podium before copying the applicable state root:
Do not make a filesystem copy while the server is running. Podium uses SQLite write-ahead logging, and copying the database and its sidecars independently does not guarantee one consistent point in time. Before applying pending database migrations, Podium checkpoints SQLite and creates a database-only snapshot beside podium.db. It retains three migration snapshots. These snapshots do not include artifacts, transcripts, uploads, configuration, or secrets, so they do not replace a stopped copy of the full state root.
The state directory can contain issue history, transcripts, uploads, pairing credentials, and secrets. Protect backups as you protect the live instance.

​
Update a headless installation

Check or select the channel, then update:
Stable follows the latest stable release. Edge follows the rolling prerelease. Switch only when you intend to accept prerelease behavior:
The updater verifies the release signature before swapping the installed bundle. A supervised headless installation accepts the update through its supervisor and manages restart and health confirmation; use podium status to follow progress. A legacy installation without a persistent supervisor prints restart podium to apply and exits with code 10 after swapping in the new bundle, so restart only when that message appears. The desktop app uses its packaged updater instead of podium update.

​
Recover after an upgrade problem

Do not start an older binary against upgraded state. Stop Podium and preserve both the failed state root and the verified pre-upgrade copy. The reviewed build contains an epoch-safe database restore implementation, but it is not wired to a shipped podium command. A bare file-copy restore does not re-mint the synchronization epoch and can leave connected clients with stale state. Rehearse and validate the recovery procedure for your deployment before relying on rollback, and see troubleshooting before collecting logs or changing configuration.
Last modified on September 16, 2026