Kraft
nextv2.0.0
Run the server

Upgrade from 0.x or a release candidate

Upgrade to 2.0 from a 1.5.0 release candidate, from an install made before the kraft-sdlc rename, or from a Kraft 0.x home that holds the old template configuration.

You will be on 2.0, coming from a 1.5.0 release candidate, an install from before the kraft-sdlc rename, or a Kraft 0.x home. A 1.4 install follows Upgrade from 1.4, and an upgrade between 2.x releases needs only Upgrade Kraft.

Before you start

  • You know which release you run: kraft --version prints it.
  • You know how Kraft was installed: with uv or install.sh, with Homebrew, or with pipx. The install command differs for each.
  • You can pick a moment when no agent runs, or you will pause the running items first. See A restart ends running agents.

Upgrading from a 1.5.0 release candidate

The 1.5.0 release candidates, 1.5.0rc1 to 1.5.0rc14, were the pre-releases of 2.0. No 1.5.0 was released.

  1. Back up the database, as step 1 of Upgrade says. Keep the file name it prints: a rollback to 1.4 needs it.
  2. Update or install, by the candidate you run. Pause the running items first, or wait until none run. Which command updates you depends on the candidate:
    • 1.5.0rc14: kraft admin update follows the release-candidate channel, so it moves to 2.0's candidates, and to 2.0.0 once that is out, and keeps [vector] and your Python. kraft admin update --channel stable waits for 2.0.0.
    • 1.5.0rc13: kraft admin update follows the release-candidate channel too, but installs without [vector] and on uv's default Python, as 1.4's does. Use the uv tool install command from Update from 1.4 instead, naming the release you want (such as 2.0.0). Then run kraft admin restart.
    • An earlier candidate: kraft admin update compares against stable releases and says you are up to date. Use the same uv tool install command. Its kraft admin update --channel rc installs the candidate too, but drops [vector] and the Python as rc13's does.
  3. Restart the server with kraft admin restart, unless step 2 already did. It lists the running items and asks before it ends their agents.
  4. Check the result with kraft --version and kraft admin health. Both print the release you installed, as step 5 of Upgrade shows.

After an update run by rc14 or earlier, vector search may have stopped. Reinstall the extra as in Enable vector search.

An update run by rc14 keeps the extra, but where uv had recorded no Python for Kraft (an install without --python, install.sh, or one that 1.4 or an earlier candidate updated), it records the exact interpreter it ran on, one Python patch release (…/cpython-3.13.12-…/bin/python3.13). Every later kraft admin update keeps it, so uv python upgrade leaves Kraft behind, and removing that patch release breaks kraft.

To fix that, run grep python "$(uv tool dir)/kraft-sdlc/uv-receipt.toml" to see what uv recorded. If it is a path, run the uv tool install --force --python 3.X … command once to tie Kraft to the minor version.

The VS Code extension on the Marketplace stays at 1.4 until 2.0.0 ships, and is read-only against a 2.0 release candidate. Install the kraft-<version>.vsix attached to the candidate's GitHub release with code --install-extension kraft-<version>.vsix.

What a candidate already did stays done:

  • 2.0 migrates the database from the schema the candidate left. It copies the database first as any upgrade does, unless the candidate already ran 2.0's schema 52 (2.0.0rc9 and later), when it makes none.
  • A theme the candidate converted keeps its theme.yaml.pre-1.5 (theme.yaml.pre-ux2 from rc5 to rc9).
  • A uv.lock that an open item's setup command wrote under 1.5.0rc14 was recorded without a digest. When the item rebases, Kraft sets aside a lockfile the setup wrote and nobody changed, but keeps one with no digest in place, in case the agent edited it. The rebase can then stop on it: see Git would not start the rebase. No action; items started on 2.0 are recorded with a digest.

To roll back to 1.4 from there, you need the database as 1.4 left it, schema 44: your own backup, or the copy Kraft made when you first left 1.4, which is not the newest one. See Find the copy to restore. Which copy holds it depends on the first release you ran after 1.4:

  • 1.5.0rc1 to rc11: no copy. These made none, so only your own backup rolls back.
  • 1.5.0rc12 or rc13: pre-v50-*.
  • 1.5.0rc14, or 2.0.0rc1 to rc8: pre-v51-*.
  • 2.0.0rc9 or later, 2.0 included: pre-v52-*.

Any later upgrade adds a newer copy that holds the schema before it, which 1.4 refuses.

Upgrading from older releases

An install from before the kraft-sdlc rename

An older install can still hold a kraft uv tool next to kraft-sdlc. kraft admin update then stops and names the two commands that clear it:

uv tool uninstall kraft
uv tool install --force --reinstall kraft-sdlc

The reinstall is needed because the uninstall removes the kraft command both packages share.

Migrating a home from 0.x

A Kraft home from 0.x holds a registry.yaml and no library.yaml. Kraft does not convert or overwrite it: the server starts degraded and refuses new work until kraft admin update replaces the configuration. Since 1.0, a template configuration is a library.yaml plus chains/*.yaml.

  1. Get ready.
    • Read the 1.0.0 changelog. Harness profile names and the template layout changed.
    • Finish or abandon in-flight items.
    • Stop the old server with kraft admin stop. It prints kraft: stopped (pid N), or kraft: no server running when none runs. The command exists from 0.6.0. On an older install, stop the server in the terminal it runs in, or end its process from your process list.
    • Back up the database, as step 1 of Upgrade says. The update keeps the old configuration whole in a backup folder of its own, so that needs no copy of yours.
  2. Install 2.0 with the tool you installed Kraft with, as Install shows. kraft --version prints kraft and a 2.x release.
  3. Run the update:
    kraft admin update

    It works on the directory that holds the 0.x files, whether or not a server has started since you installed. It says what will change, then asks:
    kraft: /home/you/.kraft/config holds a Kraft 0.x template configuration (a hook
registry and gate_after chains). It is not compatible with this Kraft, which
runs only the library.yaml format 1.0 introduced, and there is no migration:
replacing it installs the bundled configuration and moves the old one, whole,
to a backup at
  /home/you/.kraft/config.pre-v1-20261002-093015
Carried across unchanged: access.yaml, notify.yaml, theme.yaml, repos.yaml, intake.yaml, harnesses.
policy.yaml keeps your value for every key the current format still has; any
other key is dropped and listed. Your chains and registry.yaml are replaced.
All of it stays in the backup.
Replace it? [y/N]

    The backup folder sits beside the directory it replaces and takes its name: config.pre-v1-<time>, or templates.pre-v1-<time> when no 2.0 server has started yet. Answer y. With -y the command asks nothing. With no terminal and no -y, it prints kraft admin update: nothing changed. Answer y, or pass -y, to replace it. and exits 1.
    After you accept, it prints what it did:
    kraft: installed the bundled configuration in /home/you/.kraft/config; the old one is at /home/you/.kraft/config.pre-v1-20261002-093015
kraft: policy.yaml: dropped <key> = <old value> (the current format has no such key, or refuses the value)

    The dropped line appears once for each key the update drops. When the 0.x policy.yaml cannot be read, it prints kraft: policy.yaml: no readable 0.x policy; the default is installed instead.
    The update then goes on to check for a newer release. When there is none, it prints kraft 2.0.0 is up to date (v2.0.0 is the newest release) and ends, with no restart line. When a newer release exists, it installs it and prints Restart a running server: kraft admin restart; step 4 covers the restart either way.
    When the release feed is unreachable, the command exits 1 after the configuration was replaced. Running it again changes no configuration, because no 0.x files are left.
  4. Start the server, or restart the one that is running. A server that came up before the update still holds its degraded state, and the update does not tell it to reload.
    • No server is running: run kraft admin start --detach.
    • A server is running: run kraft admin restart, which ends the agent of every active item. See A restart ends running agents. kraft admin reload loads the new library, chains, policy.yaml and intake.yaml with no restart, and leaves every other file as the server read it when it started.
  5. Check the result, as Check it worked says.

What the update does to your files:

  • access.yaml, notify.yaml, theme.yaml, repos.yaml, intake.yaml and harnesses/ carry across.
  • A steering/ directory does not carry across: it stays in the config.pre-v1-<time> backup, and nothing folds it into library.yaml any more, so copy its text into library.yaml's steering: by hand.
  • policy.yaml starts from the shipped default and keeps your value for every key the current format still has. Kraft prints each key it drops, with its old value.
  • Your old chains and registry stay only in the backup. There is no migration helper.

An update interrupted mid-swap is finished by the next start or the next kraft admin update, which prints kraft: finished an interrupted update: installed the staged template configuration in <the directory>; the old one is at <the backup>.

Check it worked

kraft --version
kraft admin health

status         ok
version        2.0.0

You know it worked when --version prints a 2.x release and the status row of health says ok. A server that still refuses work reads degraded and adds an invalid template row that names the reason. If it names the 0.x configuration, the server has not read the new one yet: do step 4 of Migrating a home from 0.x.

Next steps

Upgrade from 1.4

What 2.0 changes from 1.4 and what to do about each change, and the steps to update from 1.4 without losing the database.

Roll back to 1.4

What a rollback does to the database and the config directory, and the steps that take an upgraded install from 2.0 back to 1.4.

Copyright © 2026