[{"data":1,"prerenderedAt":1344},["ShallowReactive",2],{"navigation_docs":3,"-guides-run-upgrade-kraft":504,"-guides-run-upgrade-kraft-surround":1339},[4,28,51,187,214,469],{"title":5,"path":6,"stem":7,"children":8},"Get started","\u002Fget-started","1.get-started",[9,12,16,20,24],{"title":10,"path":6,"stem":11},"Overview","1.get-started\u002Findex",{"title":13,"path":14,"stem":15},"Why Kraft","\u002Fget-started\u002Fwhy-kraft","1.get-started\u002F0.why-kraft",{"title":17,"path":18,"stem":19},"Install","\u002Fget-started\u002Finstall","1.get-started\u002F1.install",{"title":21,"path":22,"stem":23},"Your first work item","\u002Fget-started\u002Ffirst-work-item","1.get-started\u002F2.first-work-item",{"title":25,"path":26,"stem":27},"FAQ","\u002Fget-started\u002Ffaq","1.get-started\u002F3.faq",{"title":29,"path":30,"stem":31,"children":32},"Concepts","\u002Fconcepts","2.concepts",[33,35,39,43,47],{"title":10,"path":30,"stem":34},"2.concepts\u002Findex",{"title":36,"path":37,"stem":38},"How a work item runs","\u002Fconcepts\u002Fhow-a-work-item-runs","2.concepts\u002F1.how-a-work-item-runs",{"title":40,"path":41,"stem":42},"Caps and budgets","\u002Fconcepts\u002Fcaps-and-budgets","2.concepts\u002F2.caps-and-budgets",{"title":44,"path":45,"stem":46},"Why a permission gate","\u002Fconcepts\u002Fpermission-gate","2.concepts\u002F3.permission-gate",{"title":48,"path":49,"stem":50},"Vocabulary","\u002Fconcepts\u002Fvocabulary","2.concepts\u002F4.vocabulary",{"title":52,"path":53,"stem":54,"children":55},"Guides","\u002Fguides","3.guides",[56,58,96,113,134,183],{"title":10,"path":53,"stem":57},"3.guides\u002Findex",{"title":59,"path":60,"stem":61,"children":62,"page":95},"Day to day","\u002Fguides\u002Fday-to-day","3.guides\u002F1.day-to-day",[63,67,71,75,79,83,87,91],{"title":64,"path":65,"stem":66},"The setup wizard on first start","\u002Fguides\u002Fday-to-day\u002Ffirst-run","3.guides\u002F1.day-to-day\u002F2.first-run",{"title":68,"path":69,"stem":70},"File a work item","\u002Fguides\u002Fday-to-day\u002Ffile-a-work-item","3.guides\u002F1.day-to-day\u002F3.file-a-work-item",{"title":72,"path":73,"stem":74},"Use Kraft from your agent","\u002Fguides\u002Fday-to-day\u002Fagent-integration","3.guides\u002F1.day-to-day\u002F4.agent-integration",{"title":76,"path":77,"stem":78},"Reviewing a change","\u002Fguides\u002Fday-to-day\u002Freview-a-change","3.guides\u002F1.day-to-day\u002F5.review-a-change",{"title":80,"path":81,"stem":82},"Raise a cap on a stopped item","\u002Fguides\u002Fday-to-day\u002Fraise-a-cap","3.guides\u002F1.day-to-day\u002F6.raise-a-cap",{"title":84,"path":85,"stem":86},"Kraft for VS Code","\u002Fguides\u002Fday-to-day\u002Fvscode","3.guides\u002F1.day-to-day\u002F7.vscode",{"title":88,"path":89,"stem":90},"Kraft on a phone","\u002Fguides\u002Fday-to-day\u002Fkraft-on-a-phone","3.guides\u002F1.day-to-day\u002F8.kraft-on-a-phone",{"title":92,"path":93,"stem":94},"Get notified when an item needs you","\u002Fguides\u002Fday-to-day\u002Fnotifications","3.guides\u002F1.day-to-day\u002F9.notifications",false,{"title":97,"path":98,"stem":99,"children":100,"page":95},"Customize and automate","\u002Fguides\u002Fcustomize","3.guides\u002F2.customize",[101,105,109],{"title":102,"path":103,"stem":104},"Write your own chain","\u002Fguides\u002Fcustomize\u002Fwrite-your-own-chain","3.guides\u002F2.customize\u002F1.write-your-own-chain",{"title":106,"path":107,"stem":108},"Add a security review or a gate reviewer","\u002Fguides\u002Fcustomize\u002Fadd-review-agents","3.guides\u002F2.customize\u002F2.add-review-agents",{"title":110,"path":111,"stem":112},"Schedule or webhook work","\u002Fguides\u002Fcustomize\u002Fschedule-and-webhook-work","3.guides\u002F2.customize\u002F3.schedule-and-webhook-work",{"title":114,"path":115,"stem":116,"children":117,"page":95},"Agents and harnesses","\u002Fguides\u002Fharnesses","3.guides\u002F3.harnesses",[118,122,126,130],{"title":119,"path":120,"stem":121},"Switch a task to another harness","\u002Fguides\u002Fharnesses\u002Fswitch-harness","3.guides\u002F3.harnesses\u002F1.switch-harness",{"title":123,"path":124,"stem":125},"Add or override a harness","\u002Fguides\u002Fharnesses\u002Fadding-a-harness","3.guides\u002F3.harnesses\u002F2.adding-a-harness",{"title":127,"path":128,"stem":129},"Build a worker Kit","\u002Fguides\u002Fharnesses\u002Fworker-kit","3.guides\u002F3.harnesses\u002F3.worker-kit",{"title":131,"path":132,"stem":133},"Give a worker its login","\u002Fguides\u002Fharnesses\u002Fgive-a-worker-its-login","3.guides\u002F3.harnesses\u002F4.give-a-worker-its-login",{"title":135,"path":136,"stem":137,"children":138,"page":95},"Run the server","\u002Fguides\u002Frun","3.guides\u002F4.run",[139,143,147,151,155,159,163,167,171,175,179],{"title":140,"path":141,"stem":142},"Remote access","\u002Fguides\u002Frun\u002Fremote-access","3.guides\u002F4.run\u002F01.remote-access",{"title":144,"path":145,"stem":146},"Put a proxy in front of Kraft","\u002Fguides\u002Frun\u002Fput-a-proxy-in-front-of-kraft","3.guides\u002F4.run\u002F02.put-a-proxy-in-front-of-kraft",{"title":148,"path":149,"stem":150},"Restart Kraft without ending running agents","\u002Fguides\u002Frun\u002Frestart-kraft","3.guides\u002F4.run\u002F03.restart-kraft",{"title":152,"path":153,"stem":154},"Back up and restore the database","\u002Fguides\u002Frun\u002Fback-up-and-restore","3.guides\u002F4.run\u002F04.back-up-and-restore",{"title":156,"path":157,"stem":158},"Logs and disk space","\u002Fguides\u002Frun\u002Flogs-and-disk-space","3.guides\u002F4.run\u002F05.logs-and-disk-space",{"title":160,"path":161,"stem":162},"Run Kraft as a service","\u002Fguides\u002Frun\u002Frun-as-a-service","3.guides\u002F4.run\u002F06.run-as-a-service",{"title":164,"path":165,"stem":166},"Upgrade Kraft","\u002Fguides\u002Frun\u002Fupgrade-kraft","3.guides\u002F4.run\u002F07.upgrade-kraft",{"title":168,"path":169,"stem":170},"Upgrade your configuration","\u002Fguides\u002Frun\u002Fupgrade-your-configuration","3.guides\u002F4.run\u002F08.upgrade-your-configuration",{"title":172,"path":173,"stem":174},"Upgrade from 1.4","\u002Fguides\u002Frun\u002Fupgrade-from-1-4","3.guides\u002F4.run\u002F09.upgrade-from-1-4",{"title":176,"path":177,"stem":178},"Upgrade from 0.x or a release candidate","\u002Fguides\u002Frun\u002Fupgrade-from-0-x-or-a-release-candidate","3.guides\u002F4.run\u002F10.upgrade-from-0-x-or-a-release-candidate",{"title":180,"path":181,"stem":182},"Roll back to 1.4","\u002Fguides\u002Frun\u002Froll-back","3.guides\u002F4.run\u002F11.roll-back",{"title":184,"path":185,"stem":186},"Kraft Lite","\u002Fguides\u002Fkraft-lite","3.guides\u002F5.kraft-lite",{"title":188,"path":189,"stem":190,"children":191},"Troubleshooting","\u002Ftroubleshooting","4.troubleshooting",[192,194,198,202,206,210],{"title":10,"path":189,"stem":193},"4.troubleshooting\u002Findex",{"title":195,"path":196,"stem":197},"Why did my item stop?","\u002Ftroubleshooting\u002Fwhy-did-my-item-stop","4.troubleshooting\u002F1.why-did-my-item-stop",{"title":199,"path":200,"stem":201},"Stop reasons in detail","\u002Ftroubleshooting\u002Fstop-reasons-in-detail","4.troubleshooting\u002F2.stop-reasons-in-detail",{"title":203,"path":204,"stem":205},"Starting and reaching Kraft","\u002Ftroubleshooting\u002Fstarting-and-reaching-kraft","4.troubleshooting\u002F3.starting-and-reaching-kraft",{"title":207,"path":208,"stem":209},"Doctor failures","\u002Ftroubleshooting\u002Fdoctor-failures","4.troubleshooting\u002F4.doctor-failures",{"title":211,"path":212,"stem":213},"Sandbox and Kit stops","\u002Ftroubleshooting\u002Fsandbox-and-kit-stops","4.troubleshooting\u002F5.sandbox-and-kit-stops",{"title":215,"path":216,"stem":217,"children":218},"Reference","\u002Freference","5.reference",[219,221,259,281,285,375,393,419,423,427,461,465],{"title":10,"path":216,"stem":220},"5.reference\u002Findex",{"title":222,"path":223,"stem":224,"children":225},"Web UI","\u002Freference\u002Fweb-ui","5.reference\u002F00.web-ui\u002Findex",[226,227,231,235,239,243,247,251,255],{"title":10,"path":223,"stem":224},{"title":228,"path":229,"stem":230},"Sidebar, search, and keyboard","\u002Freference\u002Fweb-ui\u002Fsidebar-search-and-keyboard","5.reference\u002F00.web-ui\u002F0.sidebar-search-and-keyboard",{"title":232,"path":233,"stem":234},"The board","\u002Freference\u002Fweb-ui\u002Fboard","5.reference\u002F00.web-ui\u002F1.board",{"title":236,"path":237,"stem":238},"An item's page","\u002Freference\u002Fweb-ui\u002Fitem-page","5.reference\u002F00.web-ui\u002F2.item-page",{"title":240,"path":241,"stem":242},"Fix loops and test scopes","\u002Freference\u002Fweb-ui\u002Ffix-loops-and-test-scopes","5.reference\u002F00.web-ui\u002F3.fix-loops-and-test-scopes",{"title":244,"path":245,"stem":246},"Config before an item starts","\u002Freference\u002Fweb-ui\u002Fconfig-before-start","5.reference\u002F00.web-ui\u002F4.config-before-start",{"title":248,"path":249,"stem":250},"The review page","\u002Freference\u002Fweb-ui\u002Freview-page","5.reference\u002F00.web-ui\u002F5.review-page",{"title":252,"path":253,"stem":254},"Templates and Settings","\u002Freference\u002Fweb-ui\u002Ftemplates-and-settings","5.reference\u002F00.web-ui\u002F6.templates-and-settings",{"title":256,"path":257,"stem":258},"Analytics","\u002Freference\u002Fweb-ui\u002Fanalytics","5.reference\u002F00.web-ui\u002F7.analytics",{"title":260,"path":261,"stem":262,"children":263},"CLI","\u002Freference\u002Fcli","5.reference\u002F01.cli\u002Findex",[264,265,269,273,277],{"title":10,"path":261,"stem":262},{"title":266,"path":267,"stem":268},"Item verbs","\u002Freference\u002Fcli\u002Fitem","5.reference\u002F01.cli\u002F2.item",{"title":270,"path":271,"stem":272},"View verbs","\u002Freference\u002Fcli\u002Fview","5.reference\u002F01.cli\u002F3.view",{"title":274,"path":275,"stem":276},"Repo verbs","\u002Freference\u002Fcli\u002Frepo","5.reference\u002F01.cli\u002F4.repo",{"title":278,"path":279,"stem":280},"Admin verbs","\u002Freference\u002Fcli\u002Fadmin","5.reference\u002F01.cli\u002F5.admin",{"title":282,"path":283,"stem":284},"Work item statuses","\u002Freference\u002Fstatuses","5.reference\u002F02.statuses",{"title":286,"path":287,"stem":288,"children":289},"Configuration","\u002Freference\u002Fconfiguration","5.reference\u002F03.configuration\u002Findex",[290,291,309,313,317,321,325,329,333,337,371],{"title":10,"path":287,"stem":288},{"title":292,"path":293,"stem":294,"children":295},"repos.yaml","\u002Freference\u002Fconfiguration\u002Frepos","5.reference\u002F03.configuration\u002F02.repos\u002Findex",[296,297,301,305],{"title":10,"path":293,"stem":294},{"title":298,"path":299,"stem":300},"How connect proposes commands","\u002Freference\u002Fconfiguration\u002Frepos\u002Fconnect-proposals","5.reference\u002F03.configuration\u002F02.repos\u002F1.connect-proposals",{"title":302,"path":303,"stem":304},"detectors.yaml","\u002Freference\u002Fconfiguration\u002Frepos\u002Fdetectors","5.reference\u002F03.configuration\u002F02.repos\u002F2.detectors",{"title":306,"path":307,"stem":308},"Workspaces","\u002Freference\u002Fconfiguration\u002Frepos\u002Fworkspaces","5.reference\u002F03.configuration\u002F02.repos\u002F3.workspaces",{"title":310,"path":311,"stem":312},"policy.yaml","\u002Freference\u002Fconfiguration\u002Fpolicy","5.reference\u002F03.configuration\u002F03.policy",{"title":314,"path":315,"stem":316},"Library and chains","\u002Freference\u002Fconfiguration\u002Flibrary-and-chains","5.reference\u002F03.configuration\u002F04.library-and-chains",{"title":318,"path":319,"stem":320},"harnesses.yaml","\u002Freference\u002Fconfiguration\u002Fharnesses-file","5.reference\u002F03.configuration\u002F05.harnesses-file",{"title":322,"path":323,"stem":324},"access.yaml","\u002Freference\u002Fconfiguration\u002Faccess","5.reference\u002F03.configuration\u002F06.access",{"title":326,"path":327,"stem":328},"intake.yaml","\u002Freference\u002Fconfiguration\u002Fintake","5.reference\u002F03.configuration\u002F07.intake",{"title":330,"path":331,"stem":332},"notify.yaml","\u002Freference\u002Fconfiguration\u002Fnotify","5.reference\u002F03.configuration\u002F08.notify",{"title":334,"path":335,"stem":336},"theme.yaml","\u002Freference\u002Fconfiguration\u002Ftheme","5.reference\u002F03.configuration\u002F09.theme",{"title":338,"path":339,"stem":340,"children":341},"Sandboxed workers","\u002Freference\u002Fconfiguration\u002Fsandbox","5.reference\u002F03.configuration\u002F10.sandbox\u002Findex",[342,343,347,351,355,359,363,367],{"title":10,"path":339,"stem":340},{"title":344,"path":345,"stem":346},"Resource limits","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fresource-limits","5.reference\u002F03.configuration\u002F10.sandbox\u002F1.resource-limits",{"title":348,"path":349,"stem":350},"Callbacks from a sandbox","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fcallbacks","5.reference\u002F03.configuration\u002F10.sandbox\u002F2.callbacks",{"title":352,"path":353,"stem":354},"Network policy","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fnetwork-policy","5.reference\u002F03.configuration\u002F10.sandbox\u002F3.network-policy",{"title":356,"path":357,"stem":358},"Credentials","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fcredentials","5.reference\u002F03.configuration\u002F10.sandbox\u002F4.credentials",{"title":360,"path":361,"stem":362},"Kits","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fkits","5.reference\u002F03.configuration\u002F10.sandbox\u002F5.kits",{"title":364,"path":365,"stem":366},"sandbox.yaml","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fsandbox-yaml","5.reference\u002F03.configuration\u002F10.sandbox\u002F6.sandbox-yaml",{"title":368,"path":369,"stem":370},"Git in a sandbox","\u002Freference\u002Fconfiguration\u002Fsandbox\u002Fgit-in-a-sandbox","5.reference\u002F03.configuration\u002F10.sandbox\u002F7.git-in-a-sandbox",{"title":372,"path":373,"stem":374},"Environment variables","\u002Freference\u002Fconfiguration\u002Fenvironment-variables","5.reference\u002F03.configuration\u002F11.environment-variables",{"title":376,"path":377,"stem":378,"children":379},"Chain file keys","\u002Freference\u002Fchain-nodes","5.reference\u002F04.chain-nodes\u002Findex",[380,381,385,389],{"title":10,"path":377,"stem":378},{"title":382,"path":383,"stem":384},"Subprocess tasks","\u002Freference\u002Fchain-nodes\u002Fsubprocess-tasks","5.reference\u002F04.chain-nodes\u002F2.subprocess-tasks",{"title":386,"path":387,"stem":388},"Fix loop and judge","\u002Freference\u002Fchain-nodes\u002Ffix-loop","5.reference\u002F04.chain-nodes\u002F3.fix-loop",{"title":390,"path":391,"stem":392},"Result file","\u002Freference\u002Fchain-nodes\u002Fresult-file","5.reference\u002F04.chain-nodes\u002F4.result-file",{"title":394,"path":395,"stem":396,"children":397},"Agent harnesses","\u002Freference\u002Fharnesses","5.reference\u002F05.harnesses\u002Findex",[398,399,403,407,411,415],{"title":10,"path":395,"stem":396},{"title":400,"path":401,"stem":402},"Unattended runs","\u002Freference\u002Fharnesses\u002Funattended-runs","5.reference\u002F05.harnesses\u002F2.unattended-runs",{"title":404,"path":405,"stem":406},"Agent profiles","\u002Freference\u002Fharnesses\u002Fagent-profiles","5.reference\u002F05.harnesses\u002F3.agent-profiles",{"title":408,"path":409,"stem":410},"Harness definition files","\u002Freference\u002Fharnesses\u002Fharness-files","5.reference\u002F05.harnesses\u002F4.harness-files",{"title":412,"path":413,"stem":414},"Fallback and escalation","\u002Freference\u002Fharnesses\u002Ffallback-and-escalation","5.reference\u002F05.harnesses\u002F5.fallback-and-escalation",{"title":416,"path":417,"stem":418},"Cost reporting","\u002Freference\u002Fharnesses\u002Fcost-reporting","5.reference\u002F05.harnesses\u002F6.cost-reporting",{"title":420,"path":421,"stem":422},"Permission gate","\u002Freference\u002Fpermissions","5.reference\u002F06.permissions",{"title":424,"path":425,"stem":426},"Inbound triggers","\u002Freference\u002Ftriggers","5.reference\u002F07.triggers",{"title":428,"path":429,"stem":430,"children":431},"HTTP API","\u002Freference\u002Fhttp-api","5.reference\u002F08.http-api\u002Findex",[432,433,437,441,445,449,453,457],{"title":10,"path":429,"stem":430},{"title":434,"path":435,"stem":436},"Filing, reading and changing work items","\u002Freference\u002Fhttp-api\u002Fwork-items","5.reference\u002F08.http-api\u002F2.work-items",{"title":438,"path":439,"stem":440},"Gates, run control, ending and retry","\u002Freference\u002Fhttp-api\u002Fgates-run-control-and-ending","5.reference\u002F08.http-api\u002F3.gates-run-control-and-ending",{"title":442,"path":443,"stem":444},"The work item object","\u002Freference\u002Fhttp-api\u002Fwork-item-object","5.reference\u002F08.http-api\u002F4.work-item-object",{"title":446,"path":447,"stem":448},"Budget, events, diff and documents","\u002Freference\u002Fhttp-api\u002Fbudget-and-events","5.reference\u002F08.http-api\u002F5.budget-and-events",{"title":450,"path":451,"stem":452},"Repos, chains, harnesses and the server","\u002Freference\u002Fhttp-api\u002Frepos-chains-harnesses-and-server","5.reference\u002F08.http-api\u002F6.repos-chains-harnesses-and-server",{"title":454,"path":455,"stem":456},"Drafts","\u002Freference\u002Fhttp-api\u002Fdrafts","5.reference\u002F08.http-api\u002F7.drafts",{"title":458,"path":459,"stem":460},"Ops for each draft area","\u002Freference\u002Fhttp-api\u002Fdraft-ops","5.reference\u002F08.http-api\u002F8.draft-ops",{"title":462,"path":463,"stem":464},"MCP tools","\u002Freference\u002Fmcp-tools","5.reference\u002F09.mcp-tools",{"title":466,"path":467,"stem":468},"Events","\u002Freference\u002Fevents","5.reference\u002F10.events",{"title":470,"path":471,"stem":472,"children":473},"Security and project","\u002Fproject","6.project",[474,476,480,484,488,492,496,500],{"title":10,"path":471,"stem":475},"6.project\u002Findex",{"title":477,"path":478,"stem":479},"Security","\u002Fproject\u002Fsecurity","6.project\u002F1.security",{"title":481,"path":482,"stem":483},"Data and privacy","\u002Fproject\u002Fdata-and-privacy","6.project\u002F2.data-and-privacy",{"title":485,"path":486,"stem":487},"What's new in 2.0","\u002Fproject\u002Fwhats-new","6.project\u002F3.whats-new",{"title":489,"path":490,"stem":491},"Status and support","\u002Fproject\u002Fstatus-and-support","6.project\u002F4.status-and-support",{"title":493,"path":494,"stem":495},"Architecture","\u002Fproject\u002Farchitecture","6.project\u002F5.architecture",{"title":497,"path":498,"stem":499},"Source map","\u002Fproject\u002Fsource-map","6.project\u002F6.source-map",{"title":501,"path":502,"stem":503},"Contributing","\u002Fproject\u002Fcontributing","6.project\u002F7.contributing",{"id":505,"title":164,"body":506,"description":1332,"extension":1333,"links":1334,"meta":1335,"navigation":1336,"path":165,"seo":1337,"stem":166,"__hash__":1338},"docs\u002F3.guides\u002F4.run\u002F07.upgrade-kraft.md",{"type":507,"value":508,"toc":1321},"minimark",[509,518,533,538,566,570,1001,1005,1012,1064,1069,1073,1078,1088,1093,1167,1170,1173,1291,1295,1317],[510,511,512,513,517],"p",{},"You will run a newer Kraft release, with a backup of your database taken first,\nand ",[514,515,516],"code",{},"kraft admin health"," names the new version. The page also says how to go\nback to the version you had.",[510,519,520,521,524,525,529,530,532],{},"Coming from 1.4? Do not follow the steps on this page: 1.4's own\n",[514,522,523],{},"kraft admin update"," mishandles the install. Follow\n",[526,527,172],"a",{"href":528},"\u002Fguides\u002Frun\u002Fupgrade-from-1-4#update-from-14","\ninstead. ",[526,531,485],{"href":486}," says what you get.",[534,535,537],"h2",{"id":536},"before-you-start","Before you start",[539,540,541,549,552],"ul",{},[542,543,544,545,548],"li",{},"You know how Kraft was installed: with uv or ",[514,546,547],{},"install.sh",", with Homebrew, with\npipx or pip, or from a source checkout. The update step differs for each.",[542,550,551],{},"You can pick a moment when no agent is running, or you will pause the running\nitems first. Step 4 restarts the server, and a restart ends running agents.",[542,553,554,557,558,561,562,565],{},[514,555,556],{},"sqlite3"," or ",[514,559,560],{},"python3"," is on your ",[514,563,564],{},"PATH",", for the backup.",[534,567,569],{"id":568},"upgrade","Upgrade",[571,572,573,776,783,893,923],"ol",{},[542,574,575,576,579,580,583,584,588,589,592,593,595,598,599,602,603,606,607,610,611,746,757,759,760,762,763,765,767,768,770,771,775],{},"Back up the database. A newer Kraft can migrate ",[514,577,578],{},"run\u002Forchestrator.db","\nforward when it starts, and there is no way back: the version you had then\nrefuses to start on it (",[514,581,582],{},"database schema vN is newer than code vM","). The\nbackup is what lets you ",[526,585,587],{"href":586},"#pin-or-roll-back-a-version","roll back",".",[590,591],"br",{},"This copy is safe while the server runs. The file is named for the second you\nrun the command, so a backup taken at another time never replaces this one,\nand a rollback to 1.4 needs the backup from before the first upgrade. The\ncommand prints the name: write it down, and keep the file.",[590,594],{},[514,596,597],{},"-readonly"," opens the database you copy from read-only, so a wrong path fails\ninstead of making an empty backup. ",[514,600,601],{},"run"," follows ",[514,604,605],{},"KRAFT_RUN_DIR",", then\n",[514,608,609],{},"KRAFT_HOME",", as Kraft does:",[612,613,618],"pre",{"className":614,"code":615,"language":616,"meta":617,"style":617},"language-bash shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","run=\"${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME\u002F.kraft}\u002Frun}\"\nbackup=\"$HOME\u002Fkraft-backup-$(date +%Y%m%d-%H%M%S).db\"\nsqlite3 -readonly \"$run\u002Forchestrator.db\" \".backup '$backup'\" && chmod 600 \"$backup\" && echo \"$backup\"\n","bash","",[514,619,620,669,692],{"__ignoreMap":617},[621,622,625,628,632,636,638,641,644,646,648,651,654,656,659,662,664,666],"span",{"class":623,"line":624},"line",1,[621,626,601],{"class":627},"s7iLA",[621,629,631],{"class":630},"sklAV","=",[621,633,635],{"class":634},"semJd","\"${",[621,637,605],{"class":627},[621,639,640],{"class":630},":-",[621,642,643],{"class":634},"${",[621,645,609],{"class":627},[621,647,640],{"class":630},[621,649,650],{"class":627},"$HOME",[621,652,653],{"class":630},"\u002F",[621,655,588],{"class":634},[621,657,658],{"class":627},"kraft",[621,660,661],{"class":634},"}",[621,663,653],{"class":630},[621,665,601],{"class":627},[621,667,668],{"class":634},"}\"\n",[621,670,672,675,677,680,682,685,689],{"class":623,"line":671},2,[621,673,674],{"class":627},"backup",[621,676,631],{"class":630},[621,678,679],{"class":634},"\"",[621,681,650],{"class":627},[621,683,684],{"class":634},"\u002Fkraft-backup-$(",[621,686,688],{"class":687},"szw1H","date",[621,690,691],{"class":634}," +%Y%m%d-%H%M%S).db\"\n",[621,693,695,697,701,704,707,710,713,716,719,722,725,728,730,732,734,736,739,741,743],{"class":623,"line":694},3,[621,696,556],{"class":687},[621,698,700],{"class":699},"ssYy9"," -readonly",[621,702,703],{"class":634}," \"",[621,705,706],{"class":627},"$run",[621,708,709],{"class":634},"\u002Forchestrator.db\"",[621,711,712],{"class":634}," \".backup '",[621,714,715],{"class":627},"$backup",[621,717,718],{"class":634},"'\"",[621,720,721],{"class":627}," && ",[621,723,724],{"class":687},"chmod",[621,726,727],{"class":699}," 600",[621,729,703],{"class":634},[621,731,715],{"class":627},[621,733,679],{"class":634},[621,735,721],{"class":627},[621,737,738],{"class":699},"echo",[621,740,703],{"class":634},[621,742,715],{"class":627},[621,744,745],{"class":634},"\"\n",[612,747,752],{"className":748,"code":750,"language":751,"meta":617},[749],"language-text","\u002Fhome\u002Fyou\u002Fkraft-backup-20261002-093015.db\n","text",[514,753,754],{"__ignoreMap":617},[621,755,750],{"className":756},[623],[590,758],{},"The ",[514,761,724],{}," keeps the copy readable by you alone, as the database is.",[590,764],{},[526,766,152],{"href":153}," has the\nform for a machine without ",[514,769,556],{},", and how to check the copy and put it\nback. Kraft also copies the database itself before it migrates it, as\n",[526,772,774],{"href":773},"\u002Fguides\u002Frun\u002Fback-up-and-restore#the-copy-kraft-makes-before-an-upgrade","The copy Kraft makes before an upgrade","\nsays. Take your own anyway: you know when you made it, and it does not depend\non the version you upgrade to.",[542,777,778,779,588],{},"Pause the running items, or wait until none run. The restart in step 4 ends\nevery running agent. The commands are in\n",[526,780,782],{"href":781},"\u002Fguides\u002Frun\u002Frestart-kraft#a-restart-ends-running-agents","A restart ends running agents",[542,784,785,786,588,789,804,806,807,825,827,828,880,882,883,886,887,889,890,892],{},"Install the newest release. On 1.4, do not run this command: follow\n",[526,787,788],{"href":528},"Update from 1.4",[612,790,792],{"className":614,"code":791,"language":616,"meta":617,"style":617},"kraft admin update\n",[514,793,794],{"__ignoreMap":617},[621,795,796,798,801],{"class":623,"line":624},[621,797,658],{"class":687},[621,799,800],{"class":634}," admin",[621,802,803],{"class":634}," update\n",[590,805],{},"It prints the release it installs:",[612,808,811],{"className":809,"code":810,"language":751,"meta":617},[749],"kraft 2.0.0 -> v2.0.1\nkraft v2.0.1 installed.\nRestart a running server: kraft admin restart\n",[514,812,813,817,821],{"__ignoreMap":617},[621,814,816],{"className":815},[623],"kraft 2.0.0 -> v2.0.1\n",[621,818,820],{"className":819},[623],"kraft v2.0.1 installed.\n",[621,822,824],{"className":823},[623],"Restart a running server: kraft admin restart\n",[590,826],{},"What it runs depends on how Kraft was installed:",[539,829,830,860,868],{},[542,831,832,836,837,840,841,844,845,848,849,851,852,855,856,859],{},[833,834,835],"strong",{},"uv or script install:"," ",[514,838,839],{},"uv tool install --force --python 3.X \"kraft-sdlc[vector]==X.Y.Z\"",".\nThe ",[514,842,843],{},"vector"," extra (when you have it) and a Python you chose with\n",[514,846,847],{},"--python"," stay. With no ",[514,850,847],{}," recorded, it asks for the minor version\nKraft runs on now, such as ",[514,853,854],{},"3.13",", so a later ",[514,857,858],{},"uv python upgrade"," still\ncarries Kraft along.",[542,861,862,836,865,588],{},[833,863,864],{},"Homebrew:",[514,866,867],{},"brew upgrade kraft",[542,869,870,873,874,876,877,588],{},[833,871,872],{},"pipx, pip or a source checkout:"," nothing, because a uv copy would sit\nbeside the ",[514,875,658],{}," you run and change nothing. It prints the command that\nupdates the install you have instead, such as\n",[514,878,879],{},"pipx install --force --python \u002Fpath\u002Fto\u002Fpython \"kraft-sdlc==X.Y.Z\"",[590,881],{},"On a uv install, uv records the exact version, so ",[514,884,885],{},"uv tool upgrade"," leaves\nKraft where it is: update with ",[514,888,523],{},". In the few minutes after\na release, before PyPI has it, ",[514,891,523],{}," installs the release's\nwheel from GitHub instead.",[542,894,895,896,899,900,903,904,907,908,910,911,914,915,918,919,588],{},"Restart the server so it runs the new release. Either run\n",[514,897,898],{},"kraft admin restart",", or give step 3 ",[514,901,902],{},"--restart"," (",[514,905,906],{},"kraft admin update --restart",")\nto do both.",[590,909],{},"Without a restart, a running server keeps running the old release, the board\nshows a page saying to restart instead of the interface, and\n",[514,912,913],{},"kraft admin doctor"," warns on its ",[514,916,917],{},"restart"," row. The page does not appear\nwhen you update from 1.4 or from a 1.5.0 release candidate before rc14: see\n",[526,920,922],{"href":921},"\u002Fguides\u002Frun\u002Fupgrade-from-1-4#if-you-used-14s-update-anyway","If you used 1.4's update anyway",[542,924,925,926,947,949,952,953,955,956,959,960,963,964,967,968,971,972,975,976,990,759,992,994,995,997,998,588],{},"Check the result:",[612,927,929],{"className":614,"code":928,"language":616,"meta":617,"style":617},"kraft --version\nkraft admin health\n",[514,930,931,938],{"__ignoreMap":617},[621,932,933,935],{"class":623,"line":624},[621,934,658],{"class":687},[621,936,937],{"class":699}," --version\n",[621,939,940,942,944],{"class":623,"line":671},[621,941,658],{"class":687},[621,943,800],{"class":634},[621,945,946],{"class":634}," health\n",[590,948],{},[514,950,951],{},"--version"," prints ",[514,954,658],{}," and the release, such as ",[514,957,958],{},"kraft 2.0.1",". ",[514,961,962],{},"health","\nprints the same release on its ",[514,965,966],{},"version"," row, and no ",[514,969,970],{},"installed"," row that says\n",[514,973,974],{},"restart pending",":",[612,977,980],{"className":978,"code":979,"language":751,"meta":617},[749],"status         ok\nversion        2.0.1\n",[514,981,982,986],{"__ignoreMap":617},[621,983,985],{"className":984},[623],"status         ok\n",[621,987,989],{"className":988},[623],"version        2.0.1\n",[590,991],{},[514,993,917],{}," row of ",[514,996,913],{}," reads\n",[514,999,1000],{},"the server (pid N) runs the installed version (2.0.1)",[534,1002,1004],{"id":1003},"what-an-upgrade-leaves-in-config","What an upgrade leaves in config",[510,1006,1007,1008,1011],{},"An upgrade never changes ",[514,1009,1010],{},"$KRAFT_HOME\u002Fconfig\u002F",", with three exceptions:",[539,1013,1014,1029,1043],{},[542,1015,1016,1017,1020,1021,1024,1025,588],{},"An install still on Kraft 0.x's template format (a ",[514,1018,1019],{},"registry.yaml",", no\n",[514,1022,1023],{},"library.yaml",") is migrated, after a prompt. See\n",[526,1026,1028],{"href":1027},"\u002Fguides\u002Frun\u002Fupgrade-from-0-x-or-a-release-candidate#migrating-a-home-from-0x","Migrating a home from 0.x",[542,1030,1031,1032,1034,1035,1038,1039,588],{},"The first start of 2.0 or later rewrites ",[514,1033,334],{}," once if it still has\n",[514,1036,1037],{},"palette",". See ",[526,1040,1042],{"href":1041},"\u002Fguides\u002Frun\u002Fupgrade-from-1-4#your-theme","Your theme",[542,1044,1045,1046,1049,1050,1053,1054,1056,1057,1059,1060,588],{},"The first start of 2.0 or later renames a 1.4 ",[514,1047,1048],{},"templates\u002F"," to ",[514,1051,1052],{},"config\u002F"," and\nmoves two keys between ",[514,1055,310],{}," and ",[514,1058,326],{},", rewriting the files it\nmoves a key between. See\n",[526,1061,1063],{"href":1062},"\u002Fguides\u002Frun\u002Fupgrade-from-1-4#config-directory-and-files","Config directory and files",[510,1065,1066,1067,588],{},"To take new shipped chains and library tasks, see\n",[526,1068,168],{"href":169},[534,1070,1072],{"id":1071},"pin-or-roll-back-a-version","Pin or roll back a version",[510,1074,1075,1077],{},[514,1076,523],{}," only installs the newest release on a channel; it cannot\ntarget a version. Install a specific version with the package manager instead.",[510,1079,1080,1081,1083,1084,588],{},"To go back to 1.4 after an upgrade, see ",[526,1082,180],{"href":181},".\nTo go back to an earlier 2.x release, pin it, as below, then follow\n",[526,1085,1087],{"href":1086},"#roll-back-to-an-earlier-2x-release","Roll back to an earlier 2.x release",[1089,1090,1092],"h3",{"id":1091},"pin-a-version","Pin a version",[539,1094,1095,1146],{},[542,1096,1097,1100,1101,1104,1105,1133,1135,1136,1138,1139,1142,1143,1145],{},[833,1098,1099],{},"uv or script install."," Name the version, and the Python you run Kraft on\n(",[514,1102,1103],{},"\"$(uv tool dir)\u002Fkraft-sdlc\u002Fbin\u002Fpython\" -V"," prints it):",[612,1106,1108],{"className":614,"code":1107,"language":616,"meta":617,"style":617},"uv tool install --force --python 3.X \"kraft-sdlc==X.Y.Z\"\n",[514,1109,1110],{"__ignoreMap":617},[621,1111,1112,1115,1118,1121,1124,1127,1130],{"class":623,"line":624},[621,1113,1114],{"class":687},"uv",[621,1116,1117],{"class":634}," tool",[621,1119,1120],{"class":634}," install",[621,1122,1123],{"class":699}," --force",[621,1125,1126],{"class":699}," --python",[621,1128,1129],{"class":634}," 3.X",[621,1131,1132],{"class":634}," \"kraft-sdlc==X.Y.Z\"\n",[590,1134],{},"Without ",[514,1137,847],{},", uv moves Kraft to its default Python. Add the extra if you\nuse vector search: ",[514,1140,1141],{},"\"kraft-sdlc[vector]==X.Y.Z\"",". To stay on that version, do\nnot run ",[514,1144,523],{},"; it moves you to the newest release again.",[542,1147,1148,1151,1152,1155,1156,1159,1160,1162,1163,1166],{},[833,1149,1150],{},"Homebrew."," The tap has one formula, which each release rewrites to the\nnewest version, so Homebrew cannot install an older one. ",[514,1153,1154],{},"brew pin kraft"," stops\n",[514,1157,1158],{},"brew upgrade",", and with it ",[514,1161,523],{},", from moving the version you\nhave. To go back to an older release, ",[514,1164,1165],{},"brew uninstall kraft"," and install that\nversion with uv.",[1089,1168,1087],{"id":1169},"roll-back-to-an-earlier-2x-release",[510,1171,1172],{},"Pinning the older release is not enough when the upgrade migrated the database.\nA migration is one way: an older release refuses a database a newer one\nmigrated, and Kraft copied the database before it migrated it.",[571,1174,1175,1195,1198,1205,1237],{},[542,1176,1177,1178,1181,1182,1186,1187,1190,1191,1194],{},"Stop the server: ",[514,1179,1180],{},"kraft admin stop",", or as\n",[526,1183,1185],{"href":1184},"\u002Fguides\u002Frun\u002Frun-as-a-service#stop-a-service","Stop a service"," says when Kraft\nruns as a service. That removes the service: run ",[514,1188,1189],{},"kraft admin install-service","\nonce the older release runs, as the restore in\n",[526,1192,152],{"href":1193},"\u002Fguides\u002Frun\u002Fback-up-and-restore#restore-a-backup","\ndoes.",[542,1196,1197],{},"Pin the earlier release, as above.",[542,1199,1200,1201,1204],{},"Start it with ",[514,1202,1203],{},"kraft admin start --detach",". If it starts, the upgrade changed\nno schema, so Kraft made no copy and the database needs no restore.",[542,1206,1207,1208,1210,1211,1213,1214,1217,1218,1221,1222,1224,1225,1229,1230,1233,1234,1236],{},"If it exits with ",[514,1209,582],{},", which\n",[514,1212,1203],{}," prints and ",[514,1215,1216],{},"run\u002Flogs\u002Fserver.log"," records, the\nearlier release runs schema ",[514,1219,1220],{},"M",", and going back loses everything done since\nthe upgrade. Restore the newest of Kraft's copies whose own schema is ",[514,1223,1220],{},":\n",[526,1226,1228],{"href":1227},"\u002Fguides\u002Frun\u002Fback-up-and-restore#find-the-copy-to-restore","Find the copy to restore","\nshows how to read it, and\n",[526,1231,1232],{"href":1193},"Restore a backup"," puts it in\nplace, with ",[514,1235,674],{}," set to that copy's path.",[542,1238,1239,1240,1242,1243,1245,1246,1248,1249,1282,1284,1285,1287,1288,1290],{},"If no copy holds schema ",[514,1241,1220],{},", check the backup you took in step 1 of the\nupgrade, the file that step printed. Set ",[514,1244,674],{}," to it; the command prints\nits schema, as\n",[526,1247,1228],{"href":1227},"\ndoes for Kraft's copies:",[612,1250,1252],{"className":614,"code":1251,"language":616,"meta":617,"style":617},"backup=\"$HOME\u002Fkraft-backup-20261002-093015.db\"\nsqlite3 -readonly \"$backup\" 'PRAGMA user_version'\n",[514,1253,1254,1267],{"__ignoreMap":617},[621,1255,1256,1258,1260,1262,1264],{"class":623,"line":624},[621,1257,674],{"class":627},[621,1259,631],{"class":630},[621,1261,679],{"class":634},[621,1263,650],{"class":627},[621,1265,1266],{"class":634},"\u002Fkraft-backup-20261002-093015.db\"\n",[621,1268,1269,1271,1273,1275,1277,1279],{"class":623,"line":671},[621,1270,556],{"class":687},[621,1272,700],{"class":699},[621,1274,703],{"class":634},[621,1276,715],{"class":627},[621,1278,679],{"class":634},[621,1280,1281],{"class":634}," 'PRAGMA user_version'\n",[590,1283],{},"If it is ",[514,1286,1220],{},", restore it the same way. If it is not ",[514,1289,1220],{}," either, there is no\nway back to that release: pin the newer release again and stay on it.",[534,1292,1294],{"id":1293},"next-steps","Next steps",[539,1296,1297,1302,1307,1312],{},[542,1298,1299,1301],{},[526,1300,152],{"href":153},": take the backup, and find the copy to roll back to.",[542,1303,1304,1306],{},[526,1305,168],{"href":169},": take the new shipped chains and library tasks.",[542,1308,1309,1311],{},[526,1310,160],{"href":161},": update and restart a service.",[542,1313,1314,1316],{},[526,1315,188],{"href":189},": when an item stops after an upgrade.",[1318,1319,1320],"style",{},"html pre.shiki code .s7iLA, html code.shiki .s7iLA{--shiki-light:#0E1116;--shiki-default:#0E1116;--shiki-dark:#F0F3F6}html pre.shiki code .sklAV, html code.shiki .sklAV{--shiki-light:#A0111F;--shiki-default:#A0111F;--shiki-dark:#FF9492}html pre.shiki code .semJd, html code.shiki .semJd{--shiki-light:#032563;--shiki-default:#032563;--shiki-dark:#ADDCFF}html pre.shiki code .szw1H, html code.shiki .szw1H{--shiki-light:#702C00;--shiki-default:#702C00;--shiki-dark:#FFB757}html pre.shiki code .ssYy9, html code.shiki .ssYy9{--shiki-light:#023B95;--shiki-default:#023B95;--shiki-dark:#91CBFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":617,"searchDepth":671,"depth":671,"links":1322},[1323,1324,1325,1326,1331],{"id":536,"depth":671,"text":537},{"id":568,"depth":671,"text":569},{"id":1003,"depth":671,"text":1004},{"id":1071,"depth":671,"text":1072,"children":1327},[1328,1329],{"id":1091,"depth":694,"text":1092},{"id":1169,"depth":694,"text":1330},"Roll back to an earlier 2.​x release",{"id":1293,"depth":671,"text":1294},"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.","md",null,{},true,{"title":164,"description":1332},"IWeh7WBTsruNpMFq1ZD1PbrEMXN_C8_IAhiLVUTbc2U",[1340,1342],{"title":160,"path":161,"stem":162,"description":1341,"children":-1},"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.",{"title":168,"path":169,"stem":170,"description":1343,"children":-1},"Pick up new shipped chains, library tasks and policy after a Kraft upgrade, without losing your own edits.",1791801253113]