Run the server

Coming from 1.4

Update a 1.4 install to the current release without losing the database, act on the changes that need it, and go back to 1.4 if the update goes wrong.

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.

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" -V prints the Python. The embeddings line of kraft admin health says unavailable (the 'vector' extra is not installed when you don't have the extra.
  • sqlite3 or python3 is on your PATH, 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:

  1. 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.
  2. 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 or enabled: false (Items and repos).
    • On a repo whose sandbox: has no network:, add one, or set unrestricted_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).
  3. Pause the running items, or wait until none run: 1.4 ends its agents when it stops. See A restart leaves local steps running.
  4. Install the newest release with the tool you installed Kraft with:
    • uv or install.sh: run uv tool install --force --python 3.X "kraft-sdlc[vector]==<version>", with the Python you installed Kraft with for 3.X and the release for <version>: the number without the v, as the newest tag on the releases page shows it (tag v2.5.0 is 2.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 leaves uv tool upgrade pointing at a file it has deleted.
    • Homebrew: run brew update, then brew info kraft. It shows the version the tap offers, and brew info alone doesn't refresh the tap.
      • If it still shows 1.4, the tap has no newer release yet, and brew upgrade kraft changes nothing: wait, or run brew uninstall kraft and install with uv as above.
      • Otherwise run brew upgrade kraft. 1.4's kraft admin update runs the same command, and loses nothing: the formula has no [vector] extra.
    • pipx: run pipx install --force --python python3.X "kraft-sdlc[vector]==<version>", with <version> as above. 1.4's kraft admin update doesn't update a pipx install: it puts a second Kraft beside it with uv.
  5. Restart the server with kraft admin restart. With an item still active, a restart onto a new major version exits 1 and names --when-free and kraft 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 --version and kraft admin health print the release you installed, as step 5 of Upgrade shows.
  • kraft admin doctor has a keys, moved keys, tests and config row. 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:

  1. Run kraft admin restart as soon as the update finishes.
  2. Reinstall [vector] with the uv command above, if you use vector search. Without it, vector search stops working: see Add vector search.
  3. If you reinstalled the extra, run kraft admin restart once 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. The embeddings line of kraft admin health then says available.

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's restart row warns that the server runs a release older than the one installed.
  • Internal Server Error instead 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 Host a browser uses. 1.4 skipped the check over plain HTTP, so a name missing from allowed_hosts may have worked. Before you update, add each exact name you use (no wildcards) on Settings › Access, or to allowed_hosts in access.yaml. kraft admin doctor warns when the bind is off loopback and the list is empty.
  • A loopback bind answers 403 to a request whose Host isn't localhost, 127.0.0.1 or [::1], webhooks to POST /api/triggers and GET /api/health included. 1.4 checked only browser requests, and allowed_hosts doesn'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 Host to localhost. Read Put a proxy in front of Kraft first, because it also changes who has to sign 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 a network: policy, or set unrestricted_network: true to run as 1.4 did. Both keys together are refused, and kraft admin doctor fails the egress row of each such repo.
  • test_command: "" means the repo has no tests. Its items pass verify without running one, where 1.4 stopped every item there. Before you update, set a real test command on such an entry, or enabled: false. Afterwards the tests row of kraft admin doctor names each one.
  • kraft repo connect on 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, --json or no terminal. A script that re-runs connect to check a repo should run kraft repo list.
  • kraft repo connect refuses a repo with no commit yet. Commit its files first. kraft admin doctor names 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 (and DELETE /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_overrides is an object, not JSON text, in every --json answer that carries the item, the MCP tools' results and GET /api/work-items/{id}, and so are node_overrides and policy_override in the answers to an action. A script that runs json.loads on one reads it as an object instead. Setting the override works as in 1.4.
  • budget_cap.cap_usd in kraft view show --json is the lower of the item's own cap and its policy's budget_usd. Read budget_cap.key to tell which.
  • kraft view events -f --json prints 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_id of its own. A gate's events from before the update keep null: read their node from gate.
  • 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, resolve and reopen, and kraft item review approve or request-changes at a pending gate. A script that read the fields should use --json, which is unchanged.
  • kraft admin restart with no server running exits 1, where 1.4 exited 0. A script under set -e stops 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 tool add_review_comment and POST /api/work-items/{id}/threads answer an absolute --file path, or one with .., with 422, and --suggest with --side old exits 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", by kraft item set-overrides, set-node-override, PATCH /api/work-items/{id} and a retry that changes task_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 escalate answers 409 on an item any spend cap stopped, the daily cap included, and kraft item raise-budget with a cap at or below the spend answers 422. Raise the cap above the spend.
  • A work item title is one line of plain text, and not blank. kraft item create, the MCP tool create_work_item, POST /api/triggers and PATCH /api/work-items/{id} answer a title that is empty, only whitespace, holds a line break or holds a control character with 422.
    • 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.

Chains are named chain, not template, in commands, tools and the API. The old names that still work need nothing:

BeforeNowWhat to do
The MCP tool set_chain_templateset_chain, with chain for template; the old tool name no longer existsChange an agent prompt or skill that names it.
chain_template in the MCP tool create_work_itemchainUse chain.
default_chain_template in the answers of kraft repo list --json, kraft repo connect --json, the MCP tool ensure_repo and GET /api/reposdefault_chainRead 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/, not templates/. The first start renames yours, every file as it was, and leaves templates as 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 --json names the row config, not templates.
    • KRAFT_CONFIG_DIR names it, and KRAFT_TEMPLATES_DIR is 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 in templates/, and the config row names both until you merge them. If a unit or shell also sets KRAFT_TEMPLATES_DIR to the old default, the server refuses to start until you merge templates/ into config/ and remove it.
    • A directory you point at elsewhere is never renamed. A templates that is a link (a dotfiles repo) isn't renamed, merged or read, except its harnesses/ until a config/harnesses exists. The start warns, naming the target: set KRAFT_CONFIG_DIR to it.
  • A schedule's day of week 7 is Sunday, as in cron. 1.4 accepted 7 and never fired it, so a 0 9 * * 7 trigger 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 into library.yaml. On a 0.x home updated straight to the new release, copy those files' text into library.yaml's steering: by hand.
  • Keys moved, and every old place is still read. kraft admin doctor's moved keys row names each old place you still have. The first start moves triggers: from policy.yaml to schedules: in intake.yaml, and max_concurrent from intake.yaml to policy.yaml unless that already sets one. Until it does, the server ignores an intake.yaml max_concurrent, with a warning. A repo's default_chain_template is read as default_chain, and board.group_by: template as chain.
    • 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 above triggers: that sits over the next key stays in policy.yaml: delete it by hand. A comment on the max_concurrent line is dropped.
    • A trigger the schedule format refuses (1.4 ignored an extra key such as enabled: false), or one whose cron is outside its field (0 24 * * *, 0 9 * * 8) or uses digits other than 0-9, stays in policy.yaml, still read and fired or skipped with a warning. Doctor's moved keys row names the key.
  • Four repos.yaml keys aren't read. A repo still carrying one loads, the log names it once, and the keys row warns, naming what replaced it. Replace default_model with a model per harness profile under models:, submodules with an entry per submodule, and default_root_merge_policy with a workspace's root_pointer_default. Remove allow_cross_repo. gitlab_project is still read as forge: gitlab and project:.

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.yaml once so the look you had stays, and keeps the original as theme.yaml.pre-2.0. The palette row of theme.yaml says 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.
BeforeNow
Settings › Chains, and the old Templates pageTemplates › Chains (/templates/chains)
Settings › Library and SteeringTemplates › 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.

  1. 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 backup to 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 the sqlite3 command, 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.
  2. 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 prints kraft: stopped (pid N) or kraft: no server running. If it prints kraft: pid N did not stop within 15s and exits 1, the server still runs: don't touch the database.
  3. 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 --version
    
    kraft 1.4.0
    

    If it prints another version, 1.4 isn't what your shell runs: read the error the install printed, and run command -v kraft to see which kraft comes first on PATH. If you skipped step 2, the web UI says An older Kraft is installed and points to Pin or roll back a version.
  4. Restore the database from step 1: follow steps 2 and 3 of Restore a backup, with backup set 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 the sqlite3 command, 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.
  5. Put the config files back as 1.4 reads them: follow Put the config files back below, then return here for step 6.
  6. Start Kraft with kraft admin start --detach, or with kraft admin install-service if 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.

  1. Check the directory. 1.4 reads templates under $KRAFT_HOME, which is ~/.kraft unless 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 if templates exists, because mv would put config/ 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's config row named both). Move what templates/ still holds into config/, keeping the copy you want of each, then set templates/ aside and link it. Nothing is deleted: delete templates.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_DIR points elsewhere: the directory was never renamed. Point 1.4's KRAFT_TEMPLATES_DIR at it instead.
  2. Edit each file in this table:
    FileWhat to change for 1.4If you skip it
    intake.yamlWrite each schedule's cron as * or a comma list of numbers: 1-5 as 1,2,3,4,5, */15 as 0,15,30,45, day 7 as 0A cron with day 7 never fires
    intake.yaml and policy.yamlMove the schedules: list under a triggers: key in policy.yaml, then delete the schedules: key, even schedules: []Auto-intake stays off while health says ok
    policy.yamlAdd the triggers: key yourself: a seeded # triggers: is a comment, so pasting under it breaks the file. If a triggers: key is already there, paste under it. Delete forge_poll_s. max_concurrent needs nothingEvery new item is refused (policy config invalid, refusing work)
    repos.yamlRename each default_chain: to default_chain_template:. Where an entry has both, keep the value of default_chain and delete that lineDoctor's keys row fails and the repo files on default
    harnesses.yamlRewrite each providers: profile as one model: map by provider and one effort:, as in step 31.4 refuses the whole file
    theme.yamlRestore the theme, as in step 4The board shows default colours, or no theme
  3. Rewrite a providers: profile in 1.4's shape. 1.4 has one effort per profile: where the providers set different ones, pick one. A profile already in the model: 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
    
  4. Restore the theme. 1.4 takes its colours from palette, which the newer release removed. Copy the file kept beside theme.yaml over it: theme.yaml.pre-2.0, or the copy a 1.5.0 release candidate made (theme.yaml.pre-1.5, or theme.yaml.pre-ux2 from rc5 to rc9) if one converted the theme first. The block moves the current theme.yaml aside as theme.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, open theme.yaml, change group_by: chain to group_by: template and delete an editor: 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's worktrees row 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 -readonly makes 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 the sqlite3 command:
    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 update follows the release-candidate channel. kraft admin update --channel stable waits for the next stable release.
  • 1.5.0rc13: kraft admin update installs without [vector], as 1.4's does. Use the uv tool install command from Update from 1.4, then kraft admin restart.
  • An earlier candidate: kraft admin update says you are up to date. Use the same uv tool install command.

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.

  1. 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.
  2. Install the newest release with the tool you installed Kraft with, as Install shows.
  3. Run kraft admin update, and answer y to Replace it? [y/N], or pass -y. With no terminal and no -y it 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.
  4. Run kraft admin start --detach, or kraft admin restart if a server runs: it still holds its degraded state. kraft admin reload loads the new configuration with no restart.
  5. Run kraft --version and kraft admin health. It worked when --version prints a 2.x release and status says ok. A degraded server with an invalid template row 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

Copyright © 2026