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