How to Upgrade

This guide walks you through upgrading your self-hosted Agenta instance and applying any necessary database schema migrations. Choose the section that matches your deployment method.

Understanding Agenta Versioning

Agenta follows semantic versioning with new releases every week. Stay updated by:

Following our GitHub repository releases
Reading our changelog for detailed updates

Standard Upgrade Process

For most upgrades, follow these steps to update your Agenta instance:

1. Pull the Latest Images

Download the newest version of all Agenta Docker images:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml pull

2. Restart Services

Restart all services with the updated images:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web --profile with-traefik up -d

info

This method will cause a brief downtime while services restart. For production environments, consider the zero-downtime upgrade approach below.

Zero-Downtime Upgrade

For production environments where uptime is critical, use this approach to upgrade without service interruption.

Prerequisites

Install docker rollout for rolling updates

Upgrade Steps

1. Pull Latest Images

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml pull

2. Apply Database Migrations

Before updating services, apply any database schema changes:

docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core <api-container-name> alembic -c alembic.ini upgrade head

Replace <api-container-name> with your actual API container name (e.g., agenta-oss-gh-api-1).

3. Rolling Update Services

Update each service individually to maintain availability:

# Update core services one by one
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh api
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh worker
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh web
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh completion
docker rollout -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh chat

Each command will:

Scale the service to double the current instances
Wait for new containers to be ready
Remove old containers once new ones are healthy

Helm Chart Upgrade

One-time migration from pre-v0.100.3 to v0.100.3

v0.100.3 relocated the Helm chart (from hosting/helm/agenta-oss/ to hosting/kubernetes/helm/), reshaped the values.yaml keys, and renamed many env vars. If you are upgrading across that boundary, follow Migrate to v0.100.3 (Helm chart relocation + config reshape) once, then resume using this section for subsequent upgrades.

If you deployed Agenta on Kubernetes using the Helm chart, upgrade with:

helm upgrade agenta hosting/kubernetes/helm \
  --namespace agenta \
  -f hosting/kubernetes/oss/.values.oss.yaml

Database migrations run automatically as a post-upgrade hook. Check the migration job status:

kubectl -n agenta get jobs -l app.kubernetes.io/component=alembic
kubectl -n agenta logs job/agenta-alembic

To pin to a specific version, set the image tags in your values.yaml:

api:
  image:
    tag: "v0.86.8"
web:
  image:
    tag: "v0.86.8"
services:
  image:
    tag: "v0.86.8"

For full details, see the Deploy on Kubernetes guide.

Database Schema Migrations

PostgreSQL 17 to 18

Agenta's Docker Compose and Helm deployments pin PostgreSQL to major version 18. If your existing Docker Compose deployment was created with postgres:17, do not upgrade by only changing the image tag while reusing the same Postgres data volume.

PostgreSQL data directories are tied to the major version that created them. A Postgres 18 container can fail to start against a Postgres 17 data directory. Use a backup and restore flow instead.

Docker Compose

These commands use the default OSS Compose files from the self-host quick start.

Check the current Postgres version and continue only if it shows PostgreSQL 17:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh exec postgres \
  psql -U username -d postgres -c "SHOW server_version;"

Create a logical backup and confirm the file is not empty:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh exec -T postgres \
  pg_dumpall -U username > agenta-postgres-17-backup.sql
ls -lh agenta-postgres-17-backup.sql

Stop the stack:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh down

Find the existing Postgres volume, keep a copy, then remove the original so Compose can create a fresh Postgres 18 volume:

docker volume ls | grep postgres

POSTGRES_VOLUME=<postgres-volume-name>
POSTGRES_VOLUME_BACKUP="${POSTGRES_VOLUME}-pg17-backup"

docker volume create "$POSTGRES_VOLUME_BACKUP"
docker run --rm \
  -v "$POSTGRES_VOLUME":/from:ro \
  -v "$POSTGRES_VOLUME_BACKUP":/to \
  alpine:3 sh -c 'cd /from && cp -a . /to'

docker volume rm "$POSTGRES_VOLUME"

Do not remove the backup volume until the upgrade is verified. Start Postgres 18 and restore the dump:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh up -d postgres

cat agenta-postgres-17-backup.sql | docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh exec -T postgres \
  psql -U username -d postgres

Verify the restore:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh exec postgres \
  psql -U username -d postgres -c "SHOW server_version;"

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh exec postgres \
  psql -U username -d postgres -c "\l"

Start the full stack, then run Agenta migrations if your release requires them:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web --profile with-traefik up -d

docker ps | grep api
docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core <api-container-name> \
  alembic -c alembic.ini upgrade head

Verify the stack:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh ps
docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh logs --tail=100 api

Open the Agenta web UI and confirm that existing projects, prompts, traces, and evaluations are present before deleting any backup files or backup volumes.

Kubernetes / Helm

The Helm chart uses the Bitnami PostgreSQL subchart. These commands use the default release and namespace from the Kubernetes guide: agenta.

Check the current Postgres version:

kubectl -n agenta exec agenta-postgresql-0 -- \
  psql -U agenta -d postgres -c "SHOW server_version;"

Create a logical backup and save the current Helm values:

kubectl -n agenta exec agenta-postgresql-0 -- \
  pg_dumpall -U agenta > agenta-postgres-backup.sql

ls -lh agenta-postgres-backup.sql
helm -n agenta get values agenta -o yaml > agenta-values-before-pg18.yaml
kubectl -n agenta get pvc

Create a fresh PostgreSQL 18 data volume. The exact storage operation depends on your cluster: use your storage provider's snapshot/restore workflow, restore into a new release, or delete the old bundled PostgreSQL PVC only after you have verified the logical backup. For a disposable local cluster, that last option looks like this:

kubectl -n agenta scale deploy --all --replicas=0
kubectl -n agenta delete statefulset agenta-postgresql --ignore-not-found
kubectl -n agenta delete pvc data-agenta-postgresql-0

Upgrade the chart so bundled PostgreSQL starts with the major-18 image. If you installed with --set values instead of a file, pass the same required secrets and settings again.

helm upgrade agenta hosting/kubernetes/helm \
  --namespace agenta \
  -f hosting/kubernetes/oss/.values.oss.yaml

Wait for PostgreSQL, restore the dump, and verify the databases:

kubectl -n agenta rollout status statefulset/agenta-postgresql

cat agenta-postgres-backup.sql | kubectl -n agenta exec -i agenta-postgresql-0 -- \
  psql -U agenta -d postgres

kubectl -n agenta exec agenta-postgresql-0 -- \
  psql -U agenta -d postgres -c "SHOW server_version;"

kubectl -n agenta exec agenta-postgresql-0 -- \
  psql -U agenta -d postgres -c "\l"

Run the Helm upgrade again to restart Agenta workloads and run the migration hook, then watch the rollout:

helm upgrade agenta hosting/kubernetes/helm \
  --namespace agenta \
  -f hosting/kubernetes/oss/.values.oss.yaml

kubectl -n agenta get jobs
kubectl -n agenta get pods -w

Open the Agenta web UI and confirm that existing data is present before deleting the backup file or any old storage snapshots.

If you use an external database, upgrade that database through your provider's supported PostgreSQL major-version process, then run the Agenta upgrade.

When Migrations Are Needed

Check the release notes to see if a version requires database migrations. Not all updates require schema changes.

Manual Migration Process

1. Find Your API Container Name

List running containers to identify your API container:

docker ps | grep api

2. Run the Migration Command

Apply all pending migrations:

docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core <api-container-name> alembic -c alembic.ini upgrade head

Command Breakdown:

docker exec: Runs commands inside an existing container
-e PYTHONPATH=/app: Sets the Python path for the application
-w /app/oss/databases/postgres/migrations/core: Sets the working directory to the migrations folder
<api-container-name>: Your actual API container name
alembic -c alembic.ini upgrade head: Runs all migrations to the latest version

Verifying Migrations

After running migrations:

Check Application Health: Access Agenta through your web browser
Verify Data Integrity: Ensure your projects, prompts, and evaluations are intact
Test Core Functions: Try creating a new prompt or running an evaluation
Check Logs: Review container logs for any error messages

Migration Troubleshooting

If you encounter issues after migration:

Check Migration Status:

docker exec <api-container-name> alembic -c alembic.ini current

Review Migration History:

docker exec <api-container-name> alembic -c alembic.ini history

Rollback if Necessary:

docker exec <api-container-name> alembic -c alembic.ini downgrade -1

Report Issues: Create a GitHub issue with details about the problem

Automatic Migration Configuration

warning

Use automatic migrations with caution in production environments. Always test migrations on staging environments first.

You can configure Agenta to run migrations automatically during container startup.

Enabling Automatic Migrations

Add this environment variable to your .env.oss.gh file:

ALEMBIC_AUTO_MIGRATIONS=true

With this setting enabled:

Migrations run automatically when the API container starts
No manual migration commands are needed
Container startup may take longer while migrations run

Understanding Agenta Versioning​

Standard Upgrade Process​

1. Pull the Latest Images​

2. Restart Services​

Zero-Downtime Upgrade​

Prerequisites​

Upgrade Steps​

Helm Chart Upgrade​

Database Schema Migrations​

PostgreSQL 17 to 18​

Docker Compose​

Kubernetes / Helm​

When Migrations Are Needed​

Manual Migration Process​

Verifying Migrations​

Migration Troubleshooting​

Automatic Migration Configuration​

Enabling Automatic Migrations​