Updating

How you update depends on how you deployed. Every route preserves your secrets, applies any new database migrations, and redeploys the Worker together with its console.

CLI deployments

A gateway installed with agw deployment setup is updated by the CLI itself:

npm install -g @maxceem/agw
agw deployment update --dry-run
agw deployment update

Each CLI version installs exactly one gateway build, so picking up a new release means installing the newer CLI. It downloads that build once from the project's GitHub release, checks it against a SHA-256 built into the CLI, and caches it under ~/.cache/agw; --release-archive <path> uses a copy you downloaded yourself instead, for a machine with no route to GitHub. The dry run reports the version it would move to and changes nothing. The update applies any new migrations and then deploys.

Button deployments

The one-click flow forked the repository into your GitHub account and connected the fork to Workers Builds. Every push to the connected branch triggers a build and a deploy. The deploy command Workers Builds runs is the repository's deploy script, the same one a checkout uses, so migrations are applied as part of it. You can see and change it under the Worker's Settings → Build.

To pick up a new release, bring the upstream changes into your fork and push:

git clone https://github.com/YOUR-ACCOUNT/app-ai-gateway
cd app-ai-gateway
git remote add upstream https://github.com/maxceem/app-ai-gateway
git fetch upstream
git merge upstream/main
git push

Watch the build under the Worker's Deployments in the Cloudflare dashboard. When it finishes, check the health endpoint as after the first deployment:

curl https://YOUR-WORKER.workers.dev/v1/healthz

Plain variables changed only in Settings → Variables can be overwritten by the next deploy. Preserve them in the deployment configuration, or use Wrangler's keep_vars when you intentionally manage them in the dashboard. Existing secrets are kept.

Wrangler deployments

Pull the release into your checkout and deploy again:

git pull
pnpm install
pnpm run deploy

Add --profile <name> when the deployment uses a profile. To see what a release would change before deploying it, run the dry run first:

pnpm run deploy:dry-run --profile prod

The deploy script checks that the vault secret still exists, leaves JWT_SECRET and BETTER_AUTH_SECRET as they are, applies migrations, and deploys. App and provider configuration stays in the database. Plain Worker variables come from the deployment configuration, so preserve dashboard-only changes there before deploying.

Database migrations

Migrations live in the migrations directory and are applied by the deploy script through the DB binding, so a deployment does not depend on a particular database name. You can also apply them on their own:

pnpm run db:migrate
pnpm run db:migrate --profile prod

Applying is idempotent. A migration that has already run is skipped, so running the command twice is harmless.

A safe routine for a release that includes migrations:

1. Read the new files under migrations and confirm they only add what the release needs.
2. Deploy to a second gateway first if you run one, for example a staging profile with its own database.
3. Deploy to the gateway your apps use, then check /v1/healthz and send one request through an app.

Updating from v0.3.0 or earlier

v0.4.0 changed the database layout and cannot update an existing v0.3.0 or earlier gateway in place. agw deployment update refuses such an update and changes nothing. A button or Wrangler deployment has no such guard, so do not point one at v0.4.0. Deploy v0.4.0 as a fresh gateway instead, and recreate your apps, keys and provider credentials there. If you need help moving data from an existing installation, open an issue on GitHub.

For contributors

Change the schema definition, run pnpm run db:generate to produce the migration file, and commit both the schema change and the generated migration together. Never modify a migration that a deployment has already applied; add a new one instead.

Checking a checkout

Before deploying a change of your own, run the same checks the project runs:

pnpm run verify
pnpm run deploy:dry-run

verify type-checks every project, checks the generated OpenAPI document for drift, and runs the Worker, console, CLI and script tests. The dry run builds the console and resolves the Wrangler configuration without deploying anything.