Run the server

Upgrade Kraft

Back up, upgrade and check an installed Kraft, pin it to a version, and roll back to an earlier 2.x release, with pointers to the 1.4 upgrade and rollback.

You will run a newer Kraft release, with a backup of your database taken first, and kraft admin health names the new version. The page also says how to go back to the version you had.

Coming from 1.4? Do not follow the steps on this page: 1.4's own kraft admin update mishandles the install. Follow Upgrade from 1.4 instead. What's new in 2.0 says what you get.

Before you start

You know how Kraft was installed: with uv or install.sh, with Homebrew, with pipx or pip, or from a source checkout. The update step differs for each.
You can pick a moment when no agent is running, or you will pause the running items first. Step 4 restarts the server, and a restart ends running agents.
sqlite3 or python3 is on your PATH, for the backup.

Upgrade

Back up the database. A newer Kraft can migrate run/orchestrator.db forward when it starts, and there is no way back: the version you had then refuses to start on it (database schema vN is newer than code vM). The backup is what lets you roll back.
This copy is safe while the server runs. The file is named for the second you run the command, so a backup taken at another time never replaces this one, and a rollback to 1.4 needs the backup from before the first upgrade. The command prints the name: write it down, and keep the file.
-readonly opens the database you copy from read-only, so a wrong path fails instead of making an empty backup. run follows KRAFT_RUN_DIR, then KRAFT_HOME, as Kraft does:
```
run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}"
backup="$HOME/kraft-backup-$(date +%Y%m%d-%H%M%S).db"
sqlite3 -readonly "$run/orchestrator.db" ".backup '$backup'" && chmod 600 "$backup" && echo "$backup"
```
```
/home/you/kraft-backup-20261002-093015.db
```
The chmod keeps the copy readable by you alone, as the database is.
Back up and restore the database has the form for a machine without sqlite3, and how to check the copy and put it back. Kraft also copies the database itself before it migrates it, as The copy Kraft makes before an upgrade says. Take your own anyway: you know when you made it, and it does not depend on the version you upgrade to.
Pause the running items, or wait until none run. The restart in step 4 ends every running agent. The commands are in A restart ends running agents.
Install the newest release. On 1.4, do not run this command: follow Update from 1.4.
```
kraft admin update
```
It prints the release it installs:
```
kraft 2.0.0 -> v2.0.1
kraft v2.0.1 installed.
Restart a running server: kraft admin restart
```
What it runs depends on how Kraft was installed:
- uv or script install: uv tool install --force --python 3.X "kraft-sdlc[vector]==X.Y.Z". The vector extra (when you have it) and a Python you chose with --python stay. With no --python recorded, it asks for the minor version Kraft runs on now, such as 3.13, so a later uv python upgrade still carries Kraft along.
- Homebrew: brew upgrade kraft.
- pipx, pip or a source checkout: nothing, because a uv copy would sit beside the kraft you run and change nothing. It prints the command that updates the install you have instead, such as pipx install --force --python /path/to/python "kraft-sdlc==X.Y.Z".
On a uv install, uv records the exact version, so uv tool upgrade leaves Kraft where it is: update with kraft admin update. In the few minutes after a release, before PyPI has it, kraft admin update installs the release's wheel from GitHub instead.
A Kraft add-on runs on one major version of Kraft. Before kraft admin update installs a release of another major, it lists the loaded add-ons that release would leave out, and asks:
```
kraft 3.0.0 would stop loading these add-ons until each publishes a version for it:
  release@acme 1.0.0 needs Kraft 2.x
Install it anyway? [y/N]
```
A no installs nothing. After a yes, or -y, each listed add-on stays installed and stops loading, and a chain that extends it stops resolving. kraft admin addon update brings it back once its author publishes a version for the new major.
Restart the server so it runs the new release. Either run kraft admin restart, or give step 3 --restart (kraft admin update --restart) to do both.
Without a restart, a running server keeps running the old release, the board shows a page saying to restart instead of the interface, and kraft admin doctor warns on its restart row. The page does not appear when you update from 1.4 or from a 1.5.0 release candidate before rc14: see If you used 1.4's update anyway.
Check the result:
```
kraft --version
kraft admin health
```
--version prints kraft and the release, such as kraft 2.0.1. health prints the same release on its version row, and no installed row that says restart pending:
```
status         ok
version        2.0.1
```
The restart row of kraft admin doctor reads the server (pid N) runs the installed version (2.0.1).

What an upgrade leaves in config

An upgrade never changes $KRAFT_HOME/config/, with three exceptions:

An install still on Kraft 0.x's template format (a registry.yaml, no library.yaml) is migrated, after a prompt. See Migrating a home from 0.x.
The first start of 2.0 or later rewrites theme.yaml once if it still has palette. See Your theme.
The first start of 2.0 or later renames a 1.4 templates/ to config/ and moves two keys between policy.yaml and intake.yaml, rewriting the files it moves a key between. See Config directory and files.

To take new shipped chains and library tasks, see Upgrade your configuration.

Pin or roll back a version

kraft admin update only installs the newest release on a channel; it cannot target a version. Install a specific version with the package manager instead.

To go back to 1.4 after an upgrade, see Roll back to 1.4. To go back to an earlier 2.x release, pin it, as below, then follow Roll back to an earlier 2.x release.

Pin a version

uv or script install. Name the version, and the Python you run Kraft on ("$(uv tool dir)/kraft-sdlc/bin/python" -V prints it):
```
uv tool install --force --python 3.X "kraft-sdlc==X.Y.Z"
```
Without --python, uv moves Kraft to its default Python. Add the extra if you use vector search: "kraft-sdlc[vector]==X.Y.Z". To stay on that version, do not run kraft admin update; it moves you to the newest release again.
Homebrew. The tap has one formula, which each release rewrites to the newest version, so Homebrew cannot install an older one. brew pin kraft stops brew upgrade, and with it kraft admin update, from moving the version you have. To go back to an older release, brew uninstall kraft and install that version with uv.

Roll back to an earlier 2.x release

Pinning the older release is not enough when the upgrade migrated the database. A migration is one way: an older release refuses a database a newer one migrated, and Kraft copied the database before it migrated it.

Stop the server: kraft admin stop, or as Stop a service says when Kraft runs as a service. That removes the service: run kraft admin install-service once the older release runs, as the restore in Back up and restore the database does.
Pin the earlier release, as above.
Start it with kraft admin start --detach. If it starts, the upgrade changed no schema, so Kraft made no copy and the database needs no restore.
If it exits with database schema vN is newer than code vM, which kraft admin start --detach prints and run/logs/server.log records, the earlier release runs schema M, and going back loses everything done since the upgrade. Restore the newest of Kraft's copies whose own schema is M: Find the copy to restore shows how to read it, and Restore a backup puts it in place, with backup set to that copy's path.
If no copy holds schema M, check the backup you took in step 1 of the upgrade, the file that step printed. Set backup to it; the command prints its schema, as Find the copy to restore does for Kraft's copies:
```
backup="$HOME/kraft-backup-20261002-093015.db"
sqlite3 -readonly "$backup" 'PRAGMA user_version'
```
If it is M, restore it the same way. If it is not M either, there is no way back to that release: pin the newer release again and stay on it.

Next steps

Back up and restore the database: take the backup, and find the copy to roll back to.
Upgrade your configuration: take the new shipped chains and library tasks.
Run Kraft as a service: update and restart a service.
Troubleshooting: when an item stops after an upgrade.

Edit this pageorReport an issue

Run Kraft as a service

Start Kraft at login and restart it if it exits, set its environment, stop or remove the service, and run a second instance beside the first.

Upgrade your configuration

Pick up new shipped chains, library tasks and policy after a Kraft upgrade, without losing your own edits.