Upgrade
Upgrade a self-hosted Skilder to a later release, switch to the enterprise image and back, and back up before you do.
Pilot release. Self-hosting Skilder is a pilot.
An upgrade checks out a later release of the skilder-ai/self-hosted repository, runs that release's database migrations, and starts Skilder again. .env and the data directory stay where they are.
Versions
A release has a version X.Y.Z. The repository tags its files vX.Y.Z, and the backend, remote-mcp, runtime and frontend images carry the same version without the v. Run the four images from one release: IMAGE_TAG in .env names it. Release notes says what each release changes.
One upgrade can skip releases: the migrations of every release in between run in order. Skilder does not go back to an earlier release on the same database: to undo an upgrade, restore the backup taken before it.
Find the running version
The app shows it on the last line of the Help menu in the sidebar: Skilder v1.0.0. Find the same version, heading its entry, in the release notes.
From the skilder directory:
grep '^IMAGE_TAG=' .env # the release Compose runs
docker compose images # the image of each container
git describe --tags # the release files checked outThe three name the same release, v aside: in docker compose images, read the tag of the backend, remote-mcp, runtime and frontend images. It lists the containers that exist, so it is empty while Skilder is stopped.
Upgrade
The upgrade stops Skilder for as long as the migrations take: members see an error page and agents lose their MCP connection until it starts again. Read the release notes of every release you skip first.
Check out the release
git fetch --tags
git checkout v<version>The fetch uses the credential you cloned with (Credentials). The checkout refuses when a file you changed differs in the new release: git status lists your changes.
Set the release in .env
Set IMAGE_TAG to the new version, without the v:
IMAGE_TAG=0.15.5Then run ./init-env.sh. It generates any secret the new release adds and leaves the others alone. To see the settings a release adds, compare the two releases' .env.example:
git diff v<old version> v<version> -- .env.examplePull the images
docker compose pullPulling before you stop Skilder keeps the stop short. A pull that is refused needs a new registry login.
Stop Skilder
docker compose downIt removes the containers and the network. .env and the data directory stay.
Back up (optional)
A migration changes the database in place and has no undo, so the backup is your way back. Skilder does not take one for you:
sudo tar -czpf skilder-backup-<old version>.tgz .env dataWith an absolute SKILDER_DATA_DIR, Back up and restore shows the command.
Run the migrations
docker compose run --rm backend node packages/backend/dist/migrate.js runIt runs the new backend image with the backend's settings from .env, after starting what it needs: NATS, Dgraph and the object store. It applies the database schema, then every migration the database has not completed, in order, and stops at the first that fails. With nothing to migrate it logs No pending migrations. A failure is in If a migration fails.
To list each migration and its state, run the same command with status in place of run.
Start Skilder
docker compose up -ddocker compose ps shows every service running, and healthy once its check passes. remote-mcp and the runtime start only once the backend is healthy. When the backend does not start, up ends with dependency failed to start: container <name> is unhealthy naming the backend container, and remote-mcp and the runtime stay stopped: see If the backend does not start.
Switch to the enterprise image and back
The enterprise backend image adds single sign-on. Both backend images read the same data, so a switch either way runs no migration and keeps every account, workspace and its history. The other three images do not change.
Set the image and the SSO variables
In .env, set SKILDER_BACKEND_IMAGE=backend-ee and the SSO variables (Single sign-on). With SKILDER_REGISTRY set, copy backend-ee to your mirror first.
Register the redirect URI
With an OIDC provider, register the redirect URI the backend logs.
What people see
The first start with SSO variables applies them before the backend serves anyone. Workspace and account ids, memberships and history stay as they were.
- People on
SSO_DOMAINSbecome managed. With enforcement on, every session they had ends, and their agents' MCP OAuth tokens are revoked, so each agent signs in again. Their API keys keep working. Their next sign-in is Continue with SSO, which links to their account by email: same account, same workspaces. Their password, emailed codes and links are refused. - People off the domains notice nothing: their sessions, agents and sign-in stay as they were.
- For everyone: only a platform administrator creates workspaces. A newcomer joins by SSO only while the install holds one workspace, and an install where people created workspaces of their own holds several, so newcomers need an invitation. The invite link admits only addresses on your domains. An email invitation admits anyone.
Back to the default image
Set SKILDER_BACKEND_IMAGE=backend, or remove the line, then run docker compose pull and docker compose up -d. The default image ignores the SSO variables: Continue with SSO disappears and nothing enforces SSO. Managed people sign in with a password or an emailed code or link. A session opened through SSO lasts until it expires.
Two things stay:
- Managed accounts, platform administrators included, cannot create a workspace and get none of their own. People off your domains create workspaces again.
- The invite link of each workspace that ran on the enterprise image still admits only addresses on your domains. A workspace created meanwhile admits anyone through its link until the next start on the enterprise image, and no managed person can join it, by link or by invitation.
Back on the enterprise image
With the same SSO variables, the connection is unchanged, so every SSO sign-in keeps working. The start signs managed people out of the sessions they opened meanwhile.
The MCP OAuth tokens their agents got meanwhile survive. To revoke them, start once with enforcement off, then once with it on:
- Add
SSO_ENFORCED=falseto.envand rundocker compose up -d backend. - Remove that line and run
docker compose up -d backendagain.
If the backend does not start
On every start, the backend compares the migrations the database has completed with those its release has, and exits when they differ. Docker restarts it, so docker compose ps shows it restarting. Its log says why, in a line with backend_start_refused_migrations:
docker compose logs backend | grep backend_start_refused_migrations| The log says | Why | What to do |
|---|---|---|
| The database has migrations this build needs that have not run | The migrations were not run, or one failed or was interrupted. | Stop Skilder, run the migrations and start it again. A migration named (RUNNING) needs A migration left running first: the run refuses it. |
| The database has completed migrations this build does not know | IMAGE_TAG names an earlier release than the one that migrated the database. | Check out the release you migrated with and set IMAGE_TAG to it, or restore the backup. |
The message names each migration by its version, and its state.
If a migration fails
The command ends with Migration failed: and the reason. A migration that failed while it ran is recorded as FAILED. The migrations before it stay completed, and the backend refuses to start until the failed one completes.
- When the reason is in your hands, for example a full disk, fix it and run the migrations again. The run starts over at the failed migration.
- Otherwise, restore the backup and send Skilder the command's output. Add
--verboseafterrunfor the detail.
A migration left running
A run that is interrupted, by Ctrl-C or a host restart, leaves its migration RUNNING. The next run refuses it, and the backend's log names it (RUNNING). The migration may have changed part of the data, so restore the backup.
Without a backup, and once no migrate.js is running, mark it FAILED and run the migrations again. With <version> the version the log names, for example 099:
docker compose up -d --wait dgraph-alpha
docker compose exec dgraph-alpha curl -s localhost:8080/graphql \
-H 'Content-Type: application/json' \
-d '{"query":"mutation { updateMigration(input: { filter: { version: { eq: \"<version>\" } }, set: { status: FAILED } }) { numUids } }"}'numUids counts the records it marked: 0 means no migration has that version. The migration then runs again on data it may have changed in part.
A refused message cleanup
Garbage collection deletes chat messages that no conversation holds. From 100 messages up, it refuses to delete any when more than half read as orphaned, because a database still loading looks the same. The orphaned messages stay in the database until you act, or until new messages bring their share back under half.
The log says why, every run:
docker compose logs backend | grep gc_message_mass_orphan_refusedCheck that no restore is running and that orphanTotal and total in the line match what you expect. A live conversation's messages are never orphaned, so if nearly every message reads as orphaned on an install in active use, stop and investigate. A deleted message comes back only from a backup, so take one first. Then clear the orphaned messages:
- Add
GC_MESSAGE_MAX_ORPHAN_RATIO=1to.env. - Run
docker compose up -d backend. The cleanup runs 30 seconds after the backend starts. Wait untildocker compose logs backend | grep gc_run_completeprints a line. - Run
docker compose logs backend | grep gc_collector_result | grep MessageCollector.countis how many messages it deleted. No line means it deleted none, and the next run refuses again. - Remove the line from
.envand rundocker compose up -d backend.
Back up and restore
A backup is the data directory and .env, archived with Skilder stopped. .env holds the keys: restored without them, an install cannot read its passwords, sessions and stored secrets. Keys you keep in a secrets manager are backed up there.
The files in the data directory belong to root, so archiving and restoring take sudo. From the skilder directory, with <version> the running release:
docker compose down
sudo tar -czpf skilder-backup-<version>.tgz .env data
docker compose up -dWith an absolute SKILDER_DATA_DIR, for example /srv/skilder-data, archive that directory in place of data. tar drops the leading / of a path, so name the directory by its parent with -C:
sudo tar -czpf skilder-backup-<version>.tgz .env -C /srv skilder-dataRestore a backup
Move the current data directory aside, rather than extracting over it, and check out the release the backup was taken with:
docker compose down
sudo mv data data.before-restore
sudo tar -xzpf skilder-backup-<old version>.tgz
git checkout v<old version><old version> is the release the backup was taken with. A backup taken during an upgrade holds the new IMAGE_TAG: set it back to the old version in .env, then start Skilder with docker compose up -d. Once it runs as before, delete data.before-restore.
With an absolute SKILDER_DATA_DIR, move that directory aside and extract .env and the directory separately:
sudo mv /srv/skilder-data /srv/skilder-data.before-restore
sudo tar -xzpf skilder-backup-<old version>.tgz .env
sudo tar -xzpf skilder-backup-<old version>.tgz -C /srv skilder-dataThe same archive moves Skilder to another host: clone the release there (Get the compose files), extract the archive in the clone, and start it. Keep PUBLIC_URL unless members and agents reach the new host by a new name.

