Coming from 1.4
By the end you run the current release, coming from 1.4, and you have acted on each change that needs something from you. An update between 2.x releases needs only Upgrade Kraft. A 1.5.0 release candidate or a 0.x home follows From a release candidate or 0.x.
- On 1.4: follow Update from 1.4, then read Changes that need action.
- Already ran 1.4's own update: go to If you used 1.4's update anyway.
- Update went wrong: go to Roll back to 1.4.
Before you start
- You know how Kraft was installed: with uv or
install.sh, with Homebrew, or with pipx. Step 4 differs for each. - On uv or pipx, you know the Python Kraft runs on and whether you use vector search.
"$(uv tool dir)/kraft-sdlc/bin/python" -Vprints the Python. Theembeddingsline ofkraft admin healthsaysunavailable (the 'vector' extra is not installedwhen you don't have the extra. sqlite3orpython3is on yourPATH, for the backup in step 1.- You can pick a moment when no agent runs, or you pause the running items first (step 3).
Update from 1.4
Don't update with 1.4's own kraft admin update. That command runs in the release you have installed, and 1.4's mishandles a uv install and a pipx install, as step 4 says. Use your package manager:
- Back up the database, as step 1 of Upgrade says. 1.4 can't open the database the new release migrates. Keep the file name that step prints: a rollback to 1.4 needs it, and a later upgrade's backup never replaces it.
- Do what has to come first. Each item names its change below:
- On a network bind, add each name you use to
allowed_hosts(Network access). - Behind a tunnel or reverse proxy on a loopback bind, make it send a loopback
Host(Network access). - On a repo entry with
test_command: "", set a real test command orenabled: false(Items and repos). - On a repo whose
sandbox:has nonetwork:, add one, or setunrestricted_network: true(Items and repos). - On a schedule with day of week
7, change or remove it unless you want it to fire on Sundays (Config directory and files).
- On a network bind, add each name you use to
- Pause the running items, or wait until none run: 1.4 ends its agents when it stops. See A restart leaves local steps running.
- Install the newest release with the tool you installed Kraft with:
- uv or
install.sh: runuv tool install --force --python 3.X "kraft-sdlc[vector]==<version>", with the Python you installed Kraft with for3.Xand the release for<version>: the number without thev, as the newest tag on the releases page shows it (tagv2.5.0is2.5.0). For example,uv tool install --force --python 3.13 "kraft-sdlc[vector]==2.5.0". Leave out[vector]if you don't use vector search.
1.4's update installs the new release without the[vector]extra and on uv's default Python, and leavesuv tool upgradepointing at a file it has deleted. - Homebrew: run
brew update, thenbrew info kraft. It shows the version the tap offers, andbrew infoalone doesn't refresh the tap.- If it still shows 1.4, the tap has no newer release yet, and
brew upgrade kraftchanges nothing: wait, or runbrew uninstall kraftand install with uv as above. - Otherwise run
brew upgrade kraft. 1.4'skraft admin updateruns the same command, and loses nothing: the formula has no[vector]extra.
- If it still shows 1.4, the tap has no newer release yet, and
- pipx: run
pipx install --force --python python3.X "kraft-sdlc[vector]==<version>", with<version>as above. 1.4'skraft admin updatedoesn't update a pipx install: it puts a second Kraft beside it with uv.
- uv or
- Restart the server with
kraft admin restart. With an item still active, a restart onto a new major version exits 1 and names--when-freeandkraft admin stop --now: wait for the item, or end its steps with the second. Otherwise it asks before it ends agents.
Check it worked
kraft --versionandkraft admin healthprint the release you installed, as step 5 of Upgrade shows.kraft admin doctorhas akeys,moved keys,testsandconfigrow. Each names what the new release found in your files: Changes that need action says what to do about it.
If you used 1.4's update anyway
On a uv install, an update run by 1.4 drops the vector extra and moves Kraft to uv's default Python. Restart right after it, and don't act on the board before:
- Run
kraft admin restartas soon as the update finishes. - Reinstall
[vector]with the uv command above, if you use vector search. Without it, vector search stops working: see Add vector search. - If you reinstalled the extra, run
kraft admin restartonce more, to be safe. The reinstall replaced files under the server you just restarted, as any update does, and a restarted server reads them fresh. Theembeddingsline ofkraft admin healththen saysavailable.
Before the restart you may see:
- Items under the wrong heading, and a footer that names the new release. 1.4's server keeps running and serves the new interface, which misreads its board.
- A banner over the board saying so.
kraft admin doctor'srestartrow warns that the server runs a release older than the one installed. Internal Server Errorinstead of the board, if Kraft ran on a Python other than uv's default. 1.4's update moved Kraft to another Python and deleted the files the running server serves, though its API still answers.
If you ran kraft admin update --restart (or restarted a service), 1.4 restarted the server without asking, which ended the agents of running items. Pause them first next time.
Changes that need action
The new release changes some 1.4 behaviour that the stability policy covers, such as --json fields and exit codes, which is why it is a major release. Your chains, library and other config files carry over as they are, apart from the changes here. Each item says what 1.4 did and what you do.
Network access
- A network bind checks the
Hosta browser uses. 1.4 skipped the check over plain HTTP, so a name missing fromallowed_hostsmay have worked. Before you update, add each exact name you use (no wildcards) on Settings › Access, or toallowed_hostsinaccess.yaml.kraft admin doctorwarns when the bind is off loopback and the list is empty. - A loopback bind answers 403 to a request whose
Hostisn'tlocalhost,127.0.0.1or[::1], webhooks toPOST /api/triggersandGET /api/healthincluded. 1.4 checked only browser requests, andallowed_hostsdoesn't apply on a loopback bind. See Who may call.- For the board behind cloudflared, ngrok, Caddy or nginx: bind beyond loopback, with a password, and list the name in
allowed_hosts. Serve the board behind a reverse proxy says what the proxy must pass. - For webhooks and scripts alone: have the proxy rewrite
Hosttolocalhost. Read Put a proxy in front of Kraft first, because it also changes who has to sign in.
- For the board behind cloudflared, ngrok, Caddy or nginx: bind beyond loopback, with a password, and list the name in
Items and repos
- A sandbox with no
network:is refused. Every agent launch into it stops the item as a configuration error. 1.4 ran a Codex or Cursor task with the worker's network unrestricted and no channel to Kraft, so gates weren't enforced. A repo that runs only Claude needs nothing. Otherwise add anetwork:policy, or setunrestricted_network: trueto run as 1.4 did. Both keys together are refused, andkraft admin doctorfails theegressrow of each such repo. test_command: ""means the repo has no tests. Its items passverifywithout running one, where 1.4 stopped every item there. Before you update, set a real test command on such an entry, orenabled: false. Afterwards thetestsrow ofkraft admin doctornames each one.kraft repo connecton a connected repo saves what its entry left undecided: a test command where it has none and no test scopes, and a setup command where none is declared. That can enable a repo saved disabled. It asks first in a terminal, and saves without asking with-y,--jsonor no terminal. A script that re-runs connect to check a repo should runkraft repo list.kraft repo connectrefuses a repo with no commit yet. Commit its files first.kraft admin doctornames each entry 1.4 left without a test or setup command where the new release finds one, with the connect command that saves it.- A repo with open items can't be disconnected.
kraft repo disconnect(andDELETE /api/repos) answers 409 until each item is done, cancelled or abandoned, paused and never-started ones included. Finish, cancel or abandon them first. - Cancel keeps the branch and worktree, and a merge request closed without merging stops its item. 1.4 deleted the first and kept waiting on the second. To delete them, run
kraft item abandon ID --reason "..." --yes. For the merge request, reopen it from the item's page, retry or cancel.
Scripts, JSON output and the API
agent_overridesis an object, not JSON text, in every--jsonanswer that carries the item, the MCP tools' results andGET /api/work-items/{id}, and so arenode_overridesandpolicy_overridein the answers to an action. A script that runsjson.loadson one reads it as an object instead. Setting the override works as in 1.4.budget_cap.cap_usdinkraft view show --jsonis the lower of the item's own cap and its policy'sbudget_usd. Readbudget_cap.keyto tell which.kraft view events -f --jsonprints one JSON object per line from the first line on, where 1.4 printed the backlog as an indented array. Read it line by line.- An event has a
node_idof its own. A gate's events from before the update keepnull: read their node fromgate. - Action commands print one line, not the item's fields. That covers
kraft item approve,reject,pause,resume,retry,raise-budget,skip,complete,cancel,escalate,set-chain,resolveandreopen, andkraft item review approveorrequest-changesat a pending gate. A script that read the fields should use--json, which is unchanged. kraft admin restartwith no server running exits 1, where 1.4 exited 0. A script underset -estops there: start the server first.- A review comment names a file inside the repository, and a suggestion goes on new-side lines.
kraft item comment, the MCP tooladd_review_commentandPOST /api/work-items/{id}/threadsanswer an absolute--filepath, or one with.., with422, and--suggestwith--side oldexits 2. Use a repository-relative path and--side new. - A model override that isn't a model ID is refused with
422, such as--model "my model", bykraft item set-overrides,set-node-override,PATCH /api/work-items/{id}and a retry that changestask_config.model. 1.4 stored any text. One already stored stops its item at the next launch, and the reason names the command that clears it: run it. - A spend cap that stopped an item can't be escalated past, or raised to what the item spent.
kraft item escalateanswers409on an item any spend cap stopped, the daily cap included, andkraft item raise-budgetwith a cap at or below the spend answers422. Raise the cap above the spend. - A work item title is one line of plain text, and not blank.
kraft item create, the MCP toolcreate_work_item,POST /api/triggersandPATCH /api/work-items/{id}answer a title that is empty, only whitespace, holds a line break or holds a control character with422.- A webhook or script that builds the title from text that can be empty or run over several lines needs a fallback and the first line, with the rest in
description. - A schedule's title and Duplicate of an older item are cleaned up instead: the first line is the title, and the rest goes to the top of the description.
- A webhook or script that builds the title from text that can be empty or run over several lines needs a fallback and the first line, with the rest in
Chains are named chain, not template, in commands, tools and the API. The old names that still work need nothing:
| Before | Now | What to do |
|---|---|---|
The MCP tool set_chain_template | set_chain, with chain for template; the old tool name no longer exists | Change an agent prompt or skill that names it. |
chain_template in the MCP tool create_work_item | chain | Use chain. |
default_chain_template in the answers of kraft repo list --json, kraft repo connect --json, the MCP tool ensure_repo and GET /api/repos | default_chain | Read default_chain in a script that uses the key. |
kraft item set-chain --template, chain_template in POST /api/triggers, and default_chain_template in POST and PATCH /api/repos are still read.
Config directory and files
- The config directory is
$KRAFT_HOME/config/, nottemplates/. The first start renames yours, every file as it was, and leavestemplatesas a link, so a 1.4 process still running and a path in a script keep working. Started while the 1.4 server is still up, it exits "already running" and touches nothing.kraft admin doctor --jsonnames the rowconfig, nottemplates.KRAFT_CONFIG_DIRnames it, andKRAFT_TEMPLATES_DIRis still read when the new one is unset.- A
config/you made before the first start gets what it lacks moved in. What both hold stays intemplates/, and theconfigrow names both until you merge them. If a unit or shell also setsKRAFT_TEMPLATES_DIRto the old default, the server refuses to start until you mergetemplates/intoconfig/and remove it. - A directory you point at elsewhere is never renamed. A
templatesthat is a link (a dotfiles repo) isn't renamed, merged or read, except itsharnesses/until aconfig/harnessesexists. The start warns, naming the target: setKRAFT_CONFIG_DIRto it.
- A schedule's day of week
7is Sunday, as in cron. 1.4 accepted7and never fired it, so a0 9 * * 7trigger fires every Sunday after the update: change or remove it first if that isn't what you want. Ranges (1-5) and steps (*/15) work now. - A
steering/directory is no longer read. Every 1.x start folded it intolibrary.yaml. On a 0.x home updated straight to the new release, copy those files' text intolibrary.yaml'ssteering:by hand. - Keys moved, and every old place is still read.
kraft admin doctor'smoved keysrow names each old place you still have. The first start movestriggers:frompolicy.yamltoschedules:inintake.yaml, andmax_concurrentfromintake.yamltopolicy.yamlunless that already sets one. Until it does, the server ignores anintake.yamlmax_concurrent, with a warning. A repo'sdefault_chain_templateis read asdefault_chain, andboard.group_by: templateaschain.- Each file a key moves between is rewritten, readable by you alone (
0600). A moved trigger takes its comments with it, and a comment line abovetriggers:that sits over the next key stays inpolicy.yaml: delete it by hand. A comment on themax_concurrentline is dropped. - A trigger the schedule format refuses (1.4 ignored an extra key such as
enabled: false), or one whosecronis outside its field (0 24 * * *,0 9 * * 8) or uses digits other than 0-9, stays inpolicy.yaml, still read and fired or skipped with a warning. Doctor'smoved keysrow names the key.
- Each file a key moves between is rewritten, readable by you alone (
- Four
repos.yamlkeys aren't read. A repo still carrying one loads, the log names it once, and thekeysrow warns, naming what replaced it. Replacedefault_modelwith a model per harness profile undermodels:,submoduleswith an entry per submodule, anddefault_root_merge_policywith a workspace'sroot_pointer_default. Removeallow_cross_repo.gitlab_projectis still read asforge: gitlabandproject:.
The interface
- The new interface replaced the old one, and some pages moved. Old addresses open the right page and keep their query string. No action: the table below lists the moves.
- The first start rewrites
theme.yamlonce so the look you had stays, and keeps the original astheme.yaml.pre-2.0. Thepaletterow oftheme.yamlsays how an old key loads. If it looks wrong, pick the surface, accent and amount of colour on Settings › Appearance. - The VS Code extension needs the same major version as Kraft. Against a 1.4 server it shows the board but disables every action, and a 1.4 extension is read-only against a newer server. Update Kraft and the extension together: the messages are in VS Code.
| Before | Now |
|---|---|
| Settings › Chains, and the old Templates page | Templates › Chains (/templates/chains) |
| Settings › Library and Steering | Templates › Library (/templates/library); steering profiles are library components |
Settings › Notifications and Auto-intake (/settings/notify, /settings/intake) | Same names, at /settings/notifications and /settings/auto-intake |
The Search page (/search) | The board, with the search box on ⌘K (Ctrl+K) from any page |
A bookmark that began with /ng, or an item's tab address (/work-items/ID#tab=changes, #node=NAME) | /ng drops its prefix. A tab address opens the item's review page, and #node=NAME opens that node |
The phone layout (under 768 pixels wide), Cursor's -I hook entry, and agent profiles written as providers: in harnesses.yaml (the older model: map still loads) need nothing.
Roll back to 1.4
Starting a newer Kraft migrates run/orchestrator.db forward in place, and there is no downgrade migration: 1.4 refuses a database a newer release migrated (database schema vN is newer than code vM, in run/logs/server.log). A rollback puts back the release, the database as 1.4 left it (schema 44) and the config files the newer release changed. It loses everything done since that backup: items filed, runs, approvals and their history.
You need the database as 1.4 left it: a backup you took before the update, or the copy Kraft made when you first left 1.4. That copy isn't always the newest, because a later upgrade adds a newer one that 1.4 refuses. A 1.5.0 release candidate before 1.5.0rc12 made no copy, and only your own backup rolls back.
The commands that name your Kraft home set home or run themselves, so each block works in a new terminal. Step 1 only checks: if it finds no database you stop there and stay on the new release.
- Pick a database that prints schema 44, before you stop anything. For Kraft's copy, follow Find the copy to restore and take the newest one that prints 44. For your own backup, set
backupto its path and read its schema (a backup taken after the update doesn't print 44).backup="$HOME/kraft-backup-20261002-093015.db" sqlite3 -readonly "$backup" 'PRAGMA user_version'44
Without thesqlite3command, Python prints the same:backup="$HOME/kraft-backup-20261002-093015.db" python3 -c "import sqlite3, sys; print(sqlite3.connect('file:' + sys.argv[1] + '?mode=ro', uri=True).execute('PRAGMA user_version').fetchone()[0])" "$backup"
Write down the path: step 4 uses it. If no copy prints 44 and you have no backup of your own, stop here. - Stop Kraft with
kraft admin stop, or as Stop a service says when Kraft runs as a service: the service manager starts a stopped server again. Go on only when it printskraft: stopped (pid N)orkraft: no server running. If it printskraft: pid N did not stop within 15sand exits 1, the server still runs: don't touch the database. - Install 1.4 with the Python you run Kraft on and the extra you have. On Homebrew, which can't install an older release, see Pin a version. Leave out
[vector]if you don't use vector search:uv tool install --force --python 3.X "kraft-sdlc[vector]==1.4.0" kraft --versionkraft 1.4.0
If it prints another version, 1.4 isn't what your shell runs: read the error the install printed, and runcommand -v kraftto see whichkraftcomes first onPATH. If you skipped step 2, the web UI says An older Kraft is installed and points to Pin or roll back a version. - Restore the database from step 1: follow steps 2 and 3 of Restore a backup, with
backupset to the file from step 1. Skip its step 1, because step 2 here stopped Kraft, and its steps 4 and 5, because steps 5 and 6 here handle the config directory and start Kraft. Then check the restored database:run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}" sqlite3 -readonly "$run/orchestrator.db" 'PRAGMA user_version'44
Without thesqlite3command, Python prints the same:run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}" python3 -c "import sqlite3, sys; print(sqlite3.connect('file:' + sys.argv[1] + '?mode=ro', uri=True).execute('PRAGMA user_version').fetchone()[0])" "$run/orchestrator.db"
If it prints another number, repeat steps 1 and 4 with a copy that prints 44. If it prints an error, no database is in place: read the message the restore printed, and run it again. - Put the config files back as 1.4 reads them: follow Put the config files back below, then return here for step 6.
- Start Kraft with
kraft admin start --detach, or withkraft admin install-serviceif it ran as a service.
Put the config files back
A rollback doesn't undo what the newer release changed in $KRAFT_HOME/config/. Do these four steps with Kraft stopped, then go on to step 6 above.
- Check the directory. 1.4 reads
templatesunder$KRAFT_HOME, which is~/.kraftunless you set it. If you skip this, 1.4 seeds a fresh default home beside yours, with no repos:home="${KRAFT_HOME:-$HOME/.kraft}" ls -ld "$home/templates"- A link (
templates -> config): nothing to do. No such file or directory: the link is gone. This moves nothing iftemplatesexists, becausemvwould putconfig/inside it:home="${KRAFT_HOME:-$HOME/.kraft}" if [ -e "$home/templates" ] || [ -L "$home/templates" ]; then echo "$home/templates exists: nothing moved" else mv "$home/config" "$home/templates" fi- A real directory, not a link: the first start found a
config/you had made and couldn't merge the two (kraft admin doctor'sconfigrow named both). Move whattemplates/still holds intoconfig/, keeping the copy you want of each, then settemplates/aside and link it. Nothing is deleted: deletetemplates.old-<time>once 1.4 runs and Check the rollback passes:home="${KRAFT_HOME:-$HOME/.kraft}" old="$home/templates.old-$(date +%Y%m%d-%H%M%S)" if [ -L "$home/templates" ] || [ ! -d "$home/templates" ]; then echo "$home/templates is not a real folder: nothing moved" elif [ ! -d "$home/config" ]; then echo "$home/config is not a folder: nothing moved" elif [ -e "$old" ]; then echo "$old is already there: run this again" else mv "$home/templates" "$old" && ln -s config "$home/templates" && ls -ld "$home/templates" fi KRAFT_CONFIG_DIRpoints elsewhere: the directory was never renamed. Point 1.4'sKRAFT_TEMPLATES_DIRat it instead.
- A link (
- Edit each file in this table:
File What to change for 1.4 If you skip it intake.yamlWrite each schedule's cronas*or a comma list of numbers:1-5as1,2,3,4,5,*/15as0,15,30,45, day7as0A cronwith day7never firesintake.yamlandpolicy.yamlMove the schedules:list under atriggers:key inpolicy.yaml, then delete theschedules:key, evenschedules: []Auto-intake stays off while healthsaysokpolicy.yamlAdd the triggers:key yourself: a seeded# triggers:is a comment, so pasting under it breaks the file. If atriggers:key is already there, paste under it. Deleteforge_poll_s.max_concurrentneeds nothingEvery new item is refused ( policy config invalid, refusing work)repos.yamlRename each default_chain:todefault_chain_template:. Where an entry has both, keep the value ofdefault_chainand delete that lineDoctor's keysrow fails and the repo files ondefaultharnesses.yamlRewrite each providers:profile as onemodel:map by provider and oneeffort:, as in step 31.4 refuses the whole file theme.yamlRestore the theme, as in step 4 The board shows default colours, or no theme - Rewrite a
providers:profile in 1.4's shape. 1.4 has oneeffortper profile: where the providers set different ones, pick one. A profile already in themodel:shape needs nothing:# newer release strong: providers: claude: { model: sonnet, effort: high } codex: { model: gpt-5.6-terra, effort: high } # 1.4 strong: model: { claude: sonnet, codex: gpt-5.6-terra } effort: high - Restore the theme. 1.4 takes its colours from
palette, which the newer release removed. Copy the file kept besidetheme.yamlover it:theme.yaml.pre-2.0, or the copy a 1.5.0 release candidate made (theme.yaml.pre-1.5, ortheme.yaml.pre-ux2from rc5 to rc9) if one converted the theme first. The block moves the currenttheme.yamlaside astheme.yaml.before-rollback-<time>and copies only when the source exists. Delete the dated file once 1.4 shows the theme you want:home="${KRAFT_HOME:-$HOME/.kraft}" copy="$home/templates/theme.yaml.pre-2.0" saved="$home/templates/theme.yaml.before-rollback-$(date +%Y%m%d-%H%M%S)" if [ ! -f "$copy" ]; then echo "$copy is not a file: nothing changed. Set copy to the right file, or edit theme.yaml by hand" elif [ -e "$saved" ]; then echo "$saved is already there: run this again" elif [ -e "$home/templates/theme.yaml" ] && ! mv "$home/templates/theme.yaml" "$saved"; then echo "could not move theme.yaml aside: nothing changed" else cp "$copy" "$home/templates/theme.yaml" && ls -l "$home/templates/theme.yaml" || echo "the copy failed: the theme you had is at $saved, if there was one" fi
With no copy, opentheme.yaml, changegroup_by: chaintogroup_by: templateand delete aneditor:line, or delete the file. 1.4 refuses both, and its board then loads no theme.
Check the rollback
Run kraft --version, then kraft admin templates lint and kraft admin doctor. It worked when --version prints kraft 1.4.0, the board loads, templates lint exits 0, and doctor shows no failing templates row (1.4's name for the config directory row) or keys row.
Each row of the table in Put the config files back names its symptom: a database schema vN is newer than code vM line means the database isn't the one 1.4 left, so repeat steps 1 and 4.
What the restore leaves behind
Restoring loses everything done on the newer release since the backup. It doesn't remove what those runs made outside the database: their worktrees under run/worktrees/, their branches, and any merge requests they opened. 1.4 knows nothing about them.
kraft admin doctor'sworktreesrow lists a worktree with no work item. Delete the ones you don't need, and close any merge request yourself. 1.4's row also lists the worktrees of items you cancelled on 1.4, which its board doesn't show.- A worktree made after the update is one whose ID isn't in the database you restored. This lists the IDs that are, and
-readonlymakes a wrong path an error, not an empty database where Kraft is about to start:run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}" sqlite3 -readonly "$run/orchestrator.db" "select id from work_items"
Without thesqlite3command:run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}" python3 -c "import sqlite3, sys; [print(r[0]) for r in sqlite3.connect('file:' + sys.argv[1] + '?mode=ro', uri=True).execute('select id from work_items')]" "$run/orchestrator.db"
From a release candidate or 0.x
In each case, back up the database first, as step 1 of Upgrade says, and keep the file name: a rollback to 1.4 needs it.
A 1.5.0 release candidate
Pause the running items first, or wait until none run.
- 1.5.0rc14:
kraft admin updatefollows the release-candidate channel.kraft admin update --channel stablewaits for the next stable release. - 1.5.0rc13:
kraft admin updateinstalls without[vector], as 1.4's does. Use theuv tool installcommand from Update from 1.4, thenkraft admin restart. - An earlier candidate:
kraft admin updatesays you are up to date. Use the sameuv tool installcommand.
Restart with kraft admin restart unless the update did, then check kraft --version and kraft admin health. If vector search stopped, reinstall the extra as in Add vector search.
A uv.lock an open item's setup wrote under rc14 was recorded without a digest, so a rebase can stop on it: Git wouldn't start the rebase has the steps, ending in kraft item retry ID. Items started on the new release record a digest.
An update run by rc14 pins one Python patch release where uv recorded none. Run grep python "$(uv tool dir)/kraft-sdlc/uv-receipt.toml", and if it shows a path, run the uv tool install --force --python 3.X … command once.
An install from before the kraft-sdlc rename
If kraft admin update stops and names two commands, a kraft uv tool still sits beside kraft-sdlc. Run both:
uv tool uninstall kraft
uv tool install --force --reinstall kraft-sdlc
A 0.x home
A 0.x home holds a registry.yaml and no library.yaml. The server starts degraded and refuses new work until kraft admin update replaces the configuration. Read the 1.0.0 changelog first.
- Finish or abandon in-flight items, then stop the old server with
kraft admin stop. Before 0.6.0, stop it in its own terminal. Back up the database as above. - Install the newest release with the tool you installed Kraft with, as Install shows.
- Run
kraft admin update, and answerytoReplace it? [y/N], or pass-y. With no terminal and no-yit exits 1. If the release feed is unreachable afterwards, it exits 1 with the configuration already replaced: running it again changes nothing, because no 0.x files are left. - Run
kraft admin start --detach, orkraft admin restartif a server runs: it still holds its degraded state.kraft admin reloadloads the new configuration with no restart. - Run
kraft --versionandkraft admin health. It worked when--versionprints a 2.x release andstatussaysok. Adegradedserver with aninvalid templaterow needs step 4.
The old configuration stays whole in config.pre-v1-<time> (templates.pre-v1-<time> before a 2.x server has started). Most files carry across, and policy.yaml keeps each key the format still has, printing the rest. Chains, the registry and steering/ stay only in the backup: copy the steering text into library.yaml's steering: by hand.
Next steps
- Upgrade Kraft: the backup, the update and the check that every upgrade uses
- Back up and restore the database: take the backup 1.4 needs and find the copy to roll back to
- What's new: what you get for these changes
Move onto kraft-default
Replace the full copies of Kraft's chains in your config with thin chains that extend the built-in kraft-default, so each upgrade brings you its changes and your edits stay.
Free disk space
See what the worktrees use, make room by archiving or abandoning items or from Settings › Storage, and set a limit with automatic clean-up.