Upgrades and backups
Moving to a new version of Personal Agent Proxy, and keeping a copy of its database.
Versions
The image is published to ghcr.io/personalagentproxy/proxy with these tags:
| Tag | What it is |
|---|---|
main | The latest commit on the main branch. The compose file's default. |
sha-<commit> | One commit, which never changes. |
1.2.3, 1.2, 1, latest | A release, and the newest release in its line, once there are releases. |
Set PROXY_VERSION in .env to run a tag other than main, such as sha-c613dc6, to choose
when you move to a new version.
Upgrade
Back up the database first, then pull the new image and restart:
docker compose pull
docker compose up -dPersonal Agent Proxy applies any new database migrations as it starts, before it accepts requests. If one fails, Personal Agent Proxy does not start, and its log says why.
Personal Agent Proxy needs a place for the bytes of Files and uploads, FILES_DIR or
FILES_S3_BUCKET, and doesn't start without one. The docker-compose.yml from before Files were
required has neither: download it again, which keeps them on a volume of their own, or set
FILES_S3_BUCKET and its keys in .env.
Backups
Personal Agent Proxy keeps everything in Postgres, but for the bytes of Files, which are on the
files_data volume with Docker Compose, or in the bucket FILES_S3_BUCKET names. Copy the database
out with pg_dump:
docker compose exec -T postgres pg_dump -U proxy proxy > proxy-$(date +%F).sqlAnd the bytes of Files, from their volume, into an archive beside it:
docker compose run --rm --no-deps --user root -v "$PWD":/backup --entrypoint tar proxy czf /backup/files-$(date +%F).tar.gz -C /data filesA backup is only readable with the ENCRYPTION_KEY it was made with: connections' credentials
and vault entries are encrypted with it. Keep a copy of the key apart from the backups.
To restore, load the backup into a new, empty database before Personal Agent Proxy starts on it.
With Docker Compose, on a new server or after docker compose down --volumes, which deletes the old
database:
docker compose up -d postgres
docker compose exec -T postgres psql -U proxy proxy < proxy-2026-10-07.sql
docker compose up -d