For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Upgrade agentgateway to a new version in each installation method.

About

An upgrade replaces the agentgateway binary or image. It does not change your configuration, which lives in a file, a mounted volume, or a ConfigMap that the upgrade leaves alone. To change the configuration itself, see Update your configuration.

Every method requires a restart of the agentgateway process, because a new binary cannot replace a running one in place. Plan for a brief interruption in proxy traffic, or run more than one instance behind a load balancer.

Before you begin

1. Review the release notes highlights and GitHub release for the version that you are moving to.

2. Optional: Set the old version that you are on so that you can roll back to it, such as 1.5.0 in the following example.

   agentgateway --version

   {
     "version": "1.5.0",
     ...
   }

   export OLD_VERSION=1.5.0

3. Set the new version that you want to upgrade to as an environment variable, such as 0.0.0-latest-dev in the following example.

   export NEW_VERSION=0.0.0-latest-dev

Upgrade

The steps differ by installation method, because each method delivers the agentgateway binary in a different way.

Binary

Run the installation script again with the version that you want. The script detects the installed binary, replaces it, and leaves your configuration file untouched.

1. Check the version that you run today.

   agentgateway --version

   Example output:

   {
     "version": "1.5.0",
     "git_revision": "90f7b25855fb5f5fbefcc16855206040cba9b77d",
     "rust_version": "1.89.0",
     "build_profile": "release",
     "build_target": "x86_64-unknown-linux-musl"
   }

2. Stop the running agentgateway process.

3. Run the installation script with the target version. Replace <version> with any release tag from the agentgateway releases page, such as v1.5.0. The version must start with v, and the script adds it if you omit it.

   Specific versionLatestNon-default installation directory

   curl -sL https://agentgateway.dev/install | bash -s -- --version $NEW_VERSION

   With no --version flag, the script installs the highest stable release, skipping drafts and pre-releases.

   curl -sL https://agentgateway.dev/install | bash

   The script writes to /usr/local/bin by default, and uses sudo to do it. To install somewhere else, set AGENTGATEWAY_INSTALL_DIR, and pass --no-sudo when that directory is already writable by your user.

   curl -sL https://agentgateway.dev/install | \
     AGENTGATEWAY_INSTALL_DIR="$HOME/.local/bin" bash -s -- --no-sudo --version $NEW_VERSION

   Example output, where the script reports the change that it is about to make:

   agentgateway v1.5.0 is available. Changing from version 1.4.1.
   Downloading https://github.com/agentgateway/agentgateway/releases/download/v1.5.0/agentgateway-linux-amd64
   Verifying checksum... Done.
   Preparing to install agentgateway into /usr/local/bin
   agentgateway installed into /usr/local/bin/agentgateway

4. Verify the new version.

   agentgateway --version

5. Start agentgateway again with your configuration file.

   agentgateway -f config.yaml

Docker

Recreate the container from a new image tag, mounting the same configuration path. Your configuration file and any SQLite database in the mounted directory persist, because they live on the volume rather than in the container.

1. Pull the new image.

   docker pull cr.agentgateway.dev/agentgateway:latest-dev

2. Stop and remove the running container. The configuration in your mounted directory is not affected.

   docker rm -f agentgateway

3. Start a container from the new tag, with the same mount and published ports that you used before.

   docker run -d --name agentgateway \
     --user "$(id -u):$(id -g)" \
     -v "$PWD/agentgateway-config:/config" \
     -p 4000:4000 \
     cr.agentgateway.dev/agentgateway:latest-dev

4. Verify the version that the new container runs.

   docker exec agentgateway /app/agentgateway --version

5. Confirm that your configuration came through, such as by checking the effective configuration.

   curl -s http://localhost:4000/api/config/effective | jq

In Docker Compose, change the image tag in your compose.yaml file and recreate the service instead.

docker compose pull
docker compose up -d

Helm

Upgrade the chart version. The chart re-renders the ConfigMap from your Helm values and rolls the Deployment.

1. Check the chart version and app version that you run today.

   helm list -n agentgateway-system

   Example output:

   NAME                    NAMESPACE           REVISION  STATUS    CHART                          APP VERSION
   agentgateway-standalone agentgateway-system 3         deployed  agentgateway-standalone-1.5.0  1.5.0

2. Upgrade the release to the new chart version.

   Upgrade version, reuse valuesUpgrade version and values

   helm upgrade -i agentgateway-standalone \
     oci://cr.agentgateway.dev/charts/agentgateway-standalone \
     --namespace agentgateway-system \
     --reuse-values \
     --version 0.0.0-latest-dev

   helm upgrade -i agentgateway-standalone \
     oci://cr.agentgateway.dev/charts/agentgateway-standalone \
     --namespace agentgateway-system \
     --version 0.0.0-latest-dev \
     -f values.yaml

3. Watch the rollout.

   kubectl rollout status deploy/agentgateway-standalone \
     -n agentgateway-system

4. Verify the new version.

   helm list -n agentgateway-system

Because the default replicaCount is 1, expect a brief interruption in traffic during the rollout. To keep a pod serving traffic while the new pod starts, set replicaCount to a value greater than 1.

Rollback

Roll back to an earlier version.

curl -sL https://agentgateway.dev/install | bash -s -- --version v$OLD_VERSION

docker rm -f agentgateway
docker run -d --name agentgateway \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/agentgateway-config:/config" \
  -p 4000:4000 \
  cr.agentgateway.dev/agentgateway:v$OLD_VERSION

Next steps

• Update your configuration to change agentgateway settings rather than the agentgateway version.
• Inspect agentgateway configuration to confirm what the upgraded instance loaded.
• Debug agentgateway if the instance does not start after an upgrade.