Upgrading

Kestrel is pre-1.0. Here's what that practically means for upgrades:

• Schema migrations run automatically on startup. Atlas tracks which migrations have been applied in a _kestrel_migrations table; out-of-order or hand-edited migrations will fail the drift check and the server will refuse to start. (We never publish hand-edited migrations.)
• Within a major (v0.x.y) any patch / minor bump is safe to drop in. The HTTP API, MCP tool surface, and SDK envelope schema are kept additive — new fields appear, old ones don't disappear without notice.
• Major bumps (v1.0.0 → v2.0.0) will list breaking changes in CHANGELOG.md under that release. Read it before upgrading.

Procedure

# 1. Take a backup. Always. (See the Backups page.)
kestrel backup /var/backups/before-upgrade-$(date +%F).tar.gz

# 2. Pull the new image / binary.
docker pull ghcr.io/wearzdk/kestrel:latest

# 3. Recreate the container. Migrations run on startup.
docker stop kestrel && docker rm kestrel
docker run -d --name kestrel \
  -p 8080:8080 \
  -v kestrel-data:/data \
  ghcr.io/wearzdk/kestrel:latest

If startup fails with a migration error, do not panic and do not delete _kestrel_migrations — restore from the backup taken in step 1, file an issue with the server log, and pin to the previous tag while we sort it out.

Pinning a version

For production, pin to a specific tag (ghcr.io/wearzdk/kestrel:v0.1.0) rather than :latest. The :edge tag is the rolling main branch — useful for trying unreleased fixes, not for production.

SDK upgrades

SDKs version independently from the server:

• JS SDK — npm update kestrel-sdk (or pin a version in package.json).
• Python SDK — pip install --upgrade kestrel-sdk.
• Go SDK — go get -u github.com/wearzdk/kestrel/sdks/go.

Server 0.x accepts envelopes from any 0.x SDK and vice versa. The envelope is versioned by the explicit schema_version: 1 field; the server rejects unknown versions instead of silently parsing them as v1.

What if I'm running a static binary?

# Take backup.
./kestrel backup /var/backups/before-upgrade-$(date +%F).tar.gz

# Replace the binary.
curl -sSL -o kestrel.tar.gz https://github.com/wearzdk/kestrel/releases/latest/download/kestrel_LATEST_linux_amd64.tar.gz
tar -xzf kestrel.tar.gz
mv kestrel /usr/local/bin/kestrel

# Restart the service.
systemctl restart kestrel

Same migration story — the new binary runs them on startup.