Upgrading
How upgrades work
Section titled “How upgrades work”The server runs pending migrations at startup, before it accepts traffic. There is no separate migration step.
A migration can lock a table while it runs. On a large registry, stop the server for the upgrade, and use Backup & restore to rehearse the timing on a copy of production.
The release notes state what each version changes.
What stays compatible
Section titled “What stays compatible”Within 0.x minor releases, skael keeps these promises:
- Every prior release upgrades in place. Migrations run from any earlier release’s schema, and a test upgrades a v0.18.0 database with data in it on every change.
- Environment variable names keep working. A variable that moves to the Settings page still wins over the page and locks its field, so a deploy that sets it changes nothing. A variable that is removed or renamed gets a deprecation note in the release notes first.
- API paths keep working. A path that changes gets a deprecation note first. A new request field is optional, so an older CLI or worker keeps working against a newer server.
- Archives stay where they are. An install that started with archives on the filesystem keeps them there, even though a new install now stores them in Postgres.
Upgrading to 0.23
Section titled “Upgrading to 0.23”- Three migrations run at start. Upgrade the server first, then the workers.
- A worker older than 0.23.0 keeps running plain evals. It never claims a job whose suite has checks or that installs a set.
- A skill whose folder has
evals/at its root gets one new version on its next publish or git sync, because the bundle no longer includes that folder. The folder becomes the skill’s authored suite. - Only an owner of a skill or an admin can upload its suite with
POST /api/eval/suites. A script that pushes suites with another member’s key gets 403. - A publish queues an eval at the deepest tier the suite reaches, not always
full. A suite that reaches no tier queues nothing. - Run
skael initin a project to add the skael-evals skill. - External scanner rule names now use the command’s base name. Stored reports keep the old full path until the version is rescanned. Instance settings → Security scanning → Rescan all released versions rewrites them. That rescan withdraws a released version that a newer rule catches as exfiltration or a secret.
Upgrading to 0.22
Section titled “Upgrading to 0.22”- Hooks run the skael binary instead of the bash scripts in
~/.skael/hooks. The first skael command after the upgrade rewrites the hooks you installed and deletes the scripts. Nothing to run by hand. - The Claude Code auto-sync hook had a shape Claude Code ignored. The rewrite fixes it, so auto-sync starts to run in Claude Code.
- Developer hashes do not change, so activation history stays attributed to the same developer.
Upgrading to 0.20
Section titled “Upgrading to 0.20”- Provider keys move from workers to the server. After the upgrade, Evaluation marks each provider “needs a key”, and readiness reports
evaluation: degraded, until you enter its key once. - A Claude subscription is no longer a provider. A subscription provider is removed, with any panel that used it; choose a new panel on Evaluation.
- An Anthropic-format gateway on OpenRouter becomes the OpenRouter type. Any other gateway becomes an Anthropic provider at its old URL.
- Workers stop reading
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_BASE_URL,LLM_MODELandCLAUDE_CODE_OAUTH_TOKEN. Remove them from worker Secrets. A worker needs onlySKAEL_ENDPOINTandSKAEL_API_KEY. - The panel runs in OpenCode on the new sandbox image
whetstone-base:2. Every skill’s first score after the upgrade starts a new trend.
Upgrading to 0.19
Section titled “Upgrading to 0.19”- The first start generates a master key file unless
SKAEL_MASTER_KEYSis set. Back it up with Postgres; see Backup & restore. - Server settings you set as environment variables stay in effect and show as locked on Instance settings. Unset them to manage them on the page.
- A worker with
ANTHROPIC_BASE_URLorLLM_MODELkeeps its environment configuration. Remove both to let the Evaluation page choose the judge and panel. Reports now record each member’s provider and the sandbox image, so the first score after you switch starts a new trend. - Run
skael hook installagain on developer machines so activations carry the model and the installed version.
Procedure
Section titled “Procedure”1. Back up first
Section titled “1. Back up first”Back up both Postgres and the archive store. See Backup & restore.
2. Stop the server
Section titled “2. Stop the server”# Bare-metal / systemdsystemctl stop skael
# Docker Composedocker compose stop server3. Upgrade the server
Section titled “3. Upgrade the server”Docker image. Pull the new image and replace the running container:
docker pull ghcr.io/skael-dev/skael:latestdocker compose up -d serverBinary. Download the skael-server archive for your platform and replace the binary. This example is for Linux on amd64:
VERSION=$(curl -fsSL https://api.github.com/repos/skael-dev/skael/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')curl -fsSL https://github.com/skael-dev/skael/releases/download/v${VERSION}/skael-server_${VERSION}_linux_amd64.tar.gz \ | tar xz skael-serversudo mv skael-server /usr/local/bin/skael-serverFrom source.
just build-server4. Start and verify
Section titled “4. Start and verify”# Bare-metal / systemdsystemctl start skael
# Docker Composedocker compose up -d serverConfirm readiness:
curl -sf http://localhost:8080/api/health/readyExpected response:
{"status":"ready","checks":{"database":"ok","storage":"ok"}}A 503 means a dependency check failed. Read the logs before you send traffic.
5. Upgrade the CLI
Section titled “5. Upgrade the CLI”On macOS with Homebrew:
brew upgrade --cask skael-dev/skael/skaelWith the install script:
curl -fsSL https://skael.dev/install.sh | shOn Windows:
scoop update skael# orirm https://skael.dev/install.ps1 | iexFrom source:
git clone https://github.com/skael-dev/skael.gitcd skael && go build -o skael ./cmd/skaelgo install <pkg>@latest does not work for any binary in this repo, because go.mod has a replace directive.
Verify that the CLI reaches the server:
skael doctor6. Install the hooks again
Section titled “6. Install the hooks again”From 0.22, any skael command rewrites the hooks you installed when they name an old script or another binary. Run skael hook status to confirm each agent shows hook installed. On an older CLI, run skael hook install after the upgrade.
Rollback
Section titled “Rollback”Restore the backup from step 1, then start the previous server version. See Backup & restore.
Down-migrations (just migrate-down) are a development tool. Do not use them on production data, because they can lose data.
Compatibility
Section titled “Compatibility”The CLI does no version negotiation with the server, and mixed versions generally work. Upgrade the server before the CLI, because a newer CLI can call endpoints that an older server does not have.