> ## Documentation Index
> Fetch the complete documentation index at: https://podium.do/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update and back up Podium

> Protect local state, update a headless installation, and recover from migration failures.

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:

```bash theme={"system"}
podium stop
cp -a "$HOME/.podium" "$HOME/podium-backup"
```

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.

<Warning>
  The state directory can contain issue history, transcripts, uploads, pairing credentials, and secrets. Protect backups as you protect the live instance.
</Warning>

## Update a headless installation

Check or select the channel, then update:

```bash theme={"system"}
podium channel
podium update
```

Stable follows the latest stable release. Edge follows the rolling prerelease. Switch only when you intend to accept prerelease behavior:

```bash theme={"system"}
podium channel edge
podium update
```

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](/docs/troubleshooting) before collecting logs or changing configuration.