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

# Upgrade and rollback

> Replace an airmux release safely, verify the new deployment, and restore a consistent recovery point when rollback is necessary.

`airmux` is pre-1.0. It does not promise cross-version compatibility between the control plane, gateways, configuration,
or database schema. Use the same release for every component unless its release notes explicitly document a
rolling-compatible path.

<Warning>
  The Compose migration job applies the forward database migration before starting the new release. The CLI has no
  operator-facing downgrade command. Do not run an older release against a database migrated by a newer release.
</Warning>

## Prepare a recovery point

Before replacing any process:

1. Read the [target release notes](https://github.com/michel-tricot/airmux/releases) and configuration changes
2. Record the current release or image digest
3. Stop new inference traffic and allow active streams to finish
4. Back up Postgres, runtime credentials, provider secrets, and every gateway state directory together
5. Confirm that the database backup and state snapshot can be restored on isolated infrastructure

Include each gateway's identity, accepted bundle, and SQLite usage outbox in the state snapshot. Restoring only the
database or only `/state` can leave credential metadata, secret values, bundles, and pending usage out of sync.

Set `AIRMUX_IMAGE` to the target `ghcr.io/michel-tricot/airmux` digest before replacing either topology.

## Upgrade the full platform

Follow the [Docker Compose](/docs/deployment/docker) replacement procedure. Preserve the public origin, database, and state mounts.

Run the documented `docker compose up -d --wait` command. Compose completes the migration and catalog jobs before it replaces
the serving stack.

For a split deployment:

1. Remove every gateway from public traffic and stop it after active streams finish
2. Set `AIRMUX_IMAGE` to the new digest and run `docker compose -p airmux-split -f docker-compose.split.yml up -d --wait`;
   Compose runs the migration and catalog jobs before replacing the services
3. Wait for the control plane health check and each gateway's `/readyz` response before restoring traffic

## Verify the release

Check the public route and management context:

```bash theme={null}
curl --fail https://llm.example.com/healthz
curl --fail https://llm.example.com/readyz
airmux doctor --control-plane-url https://llm.example.com --gateway-url https://llm.example.com
airmux gateways list
```

Send one [buffered request](/docs/quickstart) and one [streaming request](/docs/reference/chat-completions#streaming). Confirm that the
requests appear in `airmux events list`, then verify that `airmux_data_plane_metering_outbox_pending` and
`airmux_data_plane_metering_outbox_oldest_age_seconds` return to their normal ranges on the internal metrics listener.

## Roll back

After a failed post-migration verification:

1. Stop the new release and all inference traffic
2. Restore Postgres and every state directory from the same recovery point
3. Redeploy the recorded previous release
4. Repeat the health, readiness, buffered, streaming, and usage checks

Do not roll back only the application against the newer database schema. Use a forward fix without restoration only
when the newer release notes explicitly say the database and bundle contracts remain compatible.

## Upgrade a gateway-only installation

Back up the standalone directory, replace the installed tool, and validate before serving:

```bash theme={null}
VERSION=X.Y.Z
cp -a .airmux ".airmux-backup-$VERSION"
uv tool install --reinstall "airmux==$VERSION"
airmux gateway validate --config .airmux/airmux.yml
airmux gateway serve --config .airmux/airmux.yml
```

Before removing the backup, make a real buffered and streaming request. To roll back, reinstall the previous package
version and restore its matching standalone directory.