[{"data":1,"prerenderedAt":1255},["ShallowReactive",2],{"navigation_docs":3,"-project-architecture":520,"-project-architecture-surround":1250},[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":509,"body":522,"description":1243,"extension":1244,"links":1245,"meta":1246,"navigation":1247,"path":510,"seo":1248,"stem":511,"__hash__":1249},"docs\u002F6.project\u002F5.architecture.md",{"type":523,"value":524,"toc":1233},"minimark",[525,540,548,564,569,576,735,739,745,748,987,991,1006,1017,1025,1029,1036,1157,1170,1174,1195,1209,1213],[526,527,528,529,534,535,539],"p",{},"Kraft is one Python process on your machine. It serves a React SPA and an HTTP\nAPI, walks each ",[530,531,533],"a",{"href":532},"\u002Fconcepts\u002Fvocabulary#work-item","work item","'s ",[530,536,538],{"href":537},"\u002Fconcepts\u002Fvocabulary#chain","chain",", and spawns a coding agent or a command for\neach task.",[526,541,542,543,547],{},"This page is for contributors and for anyone who wants to know what runs\nwhere. It shows how the parts fit and where each one is enforced in the code.\nEverything Kraft knows is in one SQLite database, ",[544,545,546],"code",{},"run\u002Forchestrator.db",", beside\na search index it can rebuild.",[526,549,550,551,553,554,556,557,560,561,563],{},"For what a work item does, step by step and status by status, read\n",[530,552,36],{"href":37}," first. For the words,\nsee ",[530,555,48],{"href":49},". For which module under ",[544,558,559],{},"src\u002Fkraft\u002F","\nholds what, see the ",[530,562,513],{"href":514},".",[565,566,568],"h2",{"id":567},"the-parts","The parts",[526,570,571],{},[572,573],"img",{"alt":574,"src":575},"Kraft's components: clients, the FastAPI process with its API, executor, pollers and stores, worker sessions in a git worktree, and the forge CLIs","\u002Fdiagrams\u002Fcomponents.svg",[577,578,579,603,636,650,666,690,713],"ul",{},[580,581,582,586,587,590,591,594,595,598,599,602],"li",{},[583,584,585],"strong",{},"One process."," ",[544,588,589],{},"kraft"," (or ",[544,592,593],{},"kraft admin start",") runs uvicorn with the\nFastAPI app from ",[544,596,597],{},"src\u002Fkraft\u002Fapi\u002F",". The same process serves the built SPA,\nanswers the API under ",[544,600,601],{},"\u002Fapi",", pushes events over a WebSocket, and runs every\nwork item's walk as an asyncio task. There is no queue, broker or second\nserver.",[580,604,605,608,609,611,612,615,616,619,620,623,624,627,628,631,632,635],{},[583,606,607],{},"Clients."," The SPA, the ",[544,610,589],{}," CLI and the MCP server all call the same\nHTTP API. The MCP server is ",[544,613,614],{},"kraft admin mcp",": a separate stdio process that\nyour coding agent starts, with a tool for most ",[544,617,618],{},"item"," and ",[544,621,622],{},"view"," verbs and\nfor ",[544,625,626],{},"repo connect"," (every tool but ",[544,629,630],{},"permission_request"," is also a CLI subcommand). Both go\nthrough ",[544,633,634],{},"src\u002Fkraft\u002Fclient\u002F",", so a verb and its tool cannot drift apart.",[580,637,638,586,641,644,645,649],{},[583,639,640],{},"The executor.",[544,642,643],{},"src\u002Fkraft\u002Fexecutor\u002F"," walks a work item's frozen chain node\nby node. It runs builtin and ",[530,646,648],{"href":647},"\u002Fconcepts\u002Fvocabulary#forge","forge"," tasks inside the process and launches\nagent and subprocess tasks as child processes. It is started by an API\nrequest (resume, retry, approve, reject, skip) or by a poller.",[580,651,652,655,656,660,661,665],{},[583,653,654],{},"Worker sessions."," Each agent task is a headless agent CLI (Claude Code,\nCodex, Gemini, Antigravity, Cursor, OpenCode or Amp) started in the item's git ",[530,657,659],{"href":658},"\u002Fconcepts\u002Fvocabulary#worktree","worktree",", with an environment built from an allowlist. With a ",[530,662,664],{"href":663},"\u002Fconcepts\u002Fvocabulary#sandbox","sandbox","\nconfigured, it runs in a container (Docker or Podman) instead, and reaches the network\nonly through Kraft's egress proxy. A worker talks back to Kraft for\npermission decisions, plan progress and review replies.",[580,667,668,671,672,675,676,679,680,684,685,689],{},[583,669,670],{},"Pollers."," Background tasks in the same process re-enter items that are\n",[544,673,674],{},"waiting"," or ",[544,677,678],{},"rate_limited",", stop parked items whose time cap ran out, fire\nschedules, pick up ready issues from ",[530,681,683],{"href":682},"\u002Fconcepts\u002Fvocabulary#beads","beads"," when ",[530,686,688],{"href":687},"\u002Fconcepts\u002Fvocabulary#auto-intake","auto-intake"," is on, fire delayed\nauto-escalations, archive old ended items, and notice a merge request closed\non the forge without merging.",[580,691,692,586,695,697,698,701,702,705,706,708,709,712],{},[583,693,694],{},"Stores.",[544,696,546],{}," holds work items, sessions, gates, review\nthreads and an append-only ",[544,699,700],{},"events"," table. All writes go through one writer\nqueue (",[544,703,704],{},"src\u002Fkraft\u002Fdb.py","). The WebSocket, notifications and the search index\neach follow the ",[544,707,700],{}," tail. ",[544,710,711],{},"run\u002Findex.db"," is the full-text and vector\nsearch index over your repos' documents.",[580,714,715,718,719,722,723,726,727,730,731,734],{},[583,716,717],{},"Outside tools."," Kraft calls ",[544,720,721],{},"git"," for worktrees and rebases, ",[544,724,725],{},"gh"," or\n",[544,728,729],{},"glab"," for merge requests and CI, and ",[544,732,733],{},"bd"," for beads, each as a subprocess\nwith your own login.",[565,736,738],{"id":737},"from-filing-to-merge","From filing to merge",[526,740,741],{},[572,742],{"alt":743,"src":744},"Sequence of one work item: create, resume, the spec author, a gate, approval, the rest of the chain, a CI wait, final review, merge","\u002Fdiagrams\u002Frequest-flow.svg",[526,746,747],{},"The table follows one work item. Its second column gives the numbered steps\nof the diagram above.",[749,750,751,772],"table",{},[752,753,754],"thead",{},[755,756,757,761,764,767],"tr",{},[758,759,760],"th",{},"Step",[758,762,763],{},"What happens",[758,765,766],{},"Diagram",[758,768,769,770],{},"Where in ",[544,771,559],{},[773,774,775,818,847,886,918,940,962],"tbody",{},[755,776,777,781,795,798],{},[778,779,780],"td",{},"1. File",[778,782,783,786,787,791,792,563],{},[544,784,785],{},"kraft item create"," posts the item. Intake resolves its chain, freezes the chain and the effective ",[530,788,790],{"href":789},"\u002Fconcepts\u002Fvocabulary#policy","policy"," onto a new row, and copies attachments. The item lands ",[544,793,794],{},"paused",[778,796,797],{},"1 to 2",[778,799,800,803,804,803,807,810,811,814,815],{},[544,801,802],{},"api\u002Froutes\u002Fwork_items.py",", ",[544,805,806],{},"executor\u002Fentry.py",[544,808,809],{},"store\u002Fwork_items.py","; chains in ",[544,812,813],{},"config\u002Fchains\u002F","; copies in ",[544,816,817],{},"run\u002Fattachments\u002F",[755,819,820,823,836,839],{},[778,821,822],{},"2. Resume",[778,824,825,828,829,831,832,835],{},[544,826,827],{},"kraft item resume"," claims the item with a conditional update from ",[544,830,794],{}," to ",[544,833,834],{},"active",", checks the slot limit in the same statement, and starts its walk as a task.",[778,837,838],{},"3 to 5",[778,840,841,803,844],{},[544,842,843],{},"api\u002Froutes\u002Flifecycle.py",[544,845,846],{},"executor.run",[755,848,849,852,860,863],{},[778,850,851],{},"3. Walk",[778,853,854,855,859],{},"The walk loads the chain, cuts the worktree, and runs each node's steps. An agent task builds its command line from the ",[530,856,858],{"href":857},"\u002Fconcepts\u002Fvocabulary#harness-profile","harness profile",", then launches it, watches its log, and reads its result file and usage.",[778,861,862],{},"6 to 8",[778,864,865,803,868,803,871,803,874,803,877,803,880,803,883],{},[544,866,867],{},"executor\u002Fwalk.py",[544,869,870],{},"builtins.py",[544,872,873],{},"executor\u002Fdispatch.py",[544,875,876],{},"adapters\u002Fagent.py",[544,878,879],{},"harness.py",[544,881,882],{},"harnesses\u002F*.yaml",[544,884,885],{},"adapters\u002Fsubprocess.py",[755,887,888,891,907,910],{},[778,889,890],{},"4. Gate",[778,892,893,894,898,899,902,903,906],{},"At a ",[530,895,897],{"href":896},"\u002Fconcepts\u002Fvocabulary#gate","gate"," node the item becomes ",[544,900,901],{},"needs_human"," and Kraft writes ",[544,904,905],{},"gate_requested",". The walk task ends. The event reaches the board over the WebSocket and, if you configured one, a notification.",[778,908,909],{},"9 to 10",[778,911,912,803,915],{},[544,913,914],{},"executor\u002Fgates.py",[544,916,917],{},"notify.py",[755,919,920,923,932,935],{},[778,921,922],{},"5. Approve",[778,924,925,928,929,931],{},[544,926,927],{},"kraft item approve"," checks for open must-fix threads, sets the item ",[544,930,834],{}," again, and starts a new walk at the node after the gate.",[778,933,934],{},"11 to 14",[778,936,937],{},[544,938,939],{},"api\u002Froutes\u002Fgates.py",[755,941,942,945,951,954],{},[778,943,944],{},"6. Merge request",[778,946,947,948,950],{},"Forge nodes open the draft merge request and read CI. A pending pipeline is an external wait: the item goes ",[544,949,674],{},", the walk task ends, and the wait scheduler re-enters the walk when the next check is due.",[778,952,953],{},"15 to 16",[778,955,956,803,959],{},[544,957,958],{},"adapters\u002Fforge\u002F",[544,960,961],{},"waits.py",[755,963,964,967,978,981],{},[778,965,966],{},"7. Finish",[778,968,969,970,973,974,977],{},"After ",[544,971,972],{},"final_review",", forge nodes mark the merge request ready, wait for any required approval, merge, and watch the post-merge pipeline. The walk marks the item ",[544,975,976],{},"completed"," and closes its issues in beads.",[778,979,980],{},"17 to 19",[778,982,983,803,985],{},[544,984,958],{},[544,986,806],{},[565,988,990],{"id":989},"what-a-restart-does-to-running-items","What a restart does to running items",[526,992,993,994,675,997,1000,1001,1005],{},"Pause an item before you run ",[544,995,996],{},"kraft admin stop",[544,998,999],{},"restart",". A clean stop\nends each running agent, and the item then stops and waits for you. See\n",[530,1002,1004],{"href":1003},"\u002Fguides\u002Frun\u002Frestart-kraft#a-restart-ends-running-agents","A restart ends running agents","\nfor the commands.",[526,1007,1008,1009,1012,1013,1016],{},"A restart does not lose finished work. On startup, ",[544,1010,1011],{},"worker\u002Freattach.py"," finds\nthe sessions that were running, adopts the ones still alive, and resumes each\nitem's walk from the node and step it had reached. A session outlives a crash\nor a ",[544,1014,1015],{},"kill -9"," of the server, because each agent runs in its own process\ngroup.",[526,1018,1019,1020,726,1022,1024],{},"A clean stop is different: it cancels every item's task, and the task kills\nits agent's process group on the way out. After a ",[544,1021,996],{},[544,1023,999],{}," there is nothing left to adopt.",[565,1026,1028],{"id":1027},"trust-boundaries","Trust boundaries",[526,1030,1031,1032,1035],{},"Four lines matter. The ",[530,1033,493],{"href":1034},"\u002Fproject\u002Fsecurity#default-posture"," page\nstates what each one does and does not stop by default; this is only where\neach one lives in the code.",[749,1037,1038,1048],{},[752,1039,1040],{},[755,1041,1042,1045],{},[758,1043,1044],{},"Boundary",[758,1046,1047],{},"Enforced by",[773,1049,1050,1068,1101,1142],{},[755,1051,1052,1055],{},[778,1053,1054],{},"Network clients to the API",[778,1056,1057,1060,1061,1064,1065],{},[544,1058,1059],{},"api\u002Fperimeter.py"," (the local-client check and auth middleware), ",[544,1062,1063],{},"auth.py"," (password login and sessions), the bearer token in ",[544,1066,1067],{},"run\u002F",[755,1069,1070,1073],{},[778,1071,1072],{},"A worker to Kraft",[778,1074,1075,1076,803,1079,803,1082,803,1085,1088,1089,1092,1093,1096,1097,1100],{},"The permission gate (",[544,1077,1078],{},"api\u002Froutes\u002Fsessions.py",[544,1080,1081],{},"permission_hooks.py",[544,1083,1084],{},"permission_rules.py",[544,1086,1087],{},"grants.py","), and the self-action guard: ",[544,1090,1091],{},"client\u002Fcontext.py"," in the CLI and MCP server, and ",[544,1094,1095],{},"forbid_self_action"," in ",[544,1098,1099],{},"api\u002Fdeps.py"," for a worker that identifies itself",[755,1102,1103,1106],{},[778,1104,1105],{},"A worker to your machine",[778,1107,1108,1109,1112,1113,803,1116,803,1119,803,1122,1096,1125,1128,1129,1132,1133,803,1136,619,1139],{},"Nothing, unless the repo sets ",[544,1110,1111],{},"sandbox:",". Then ",[544,1114,1115],{},"worker\u002Fbackends\u002Fdocker.py",[544,1117,1118],{},"worker\u002Fsandbox.py",[544,1120,1121],{},"worker\u002Frefstore.py",[544,1123,1124],{},"assert_on_branch",[544,1126,1127],{},"adapters\u002Fforge\u002Fgit.py"," before every host-side commit, rebase or push from its worktree, and for ",[544,1130,1131],{},"network:"," the egress proxy in ",[544,1134,1135],{},"worker\u002Fegress.py",[544,1137,1138],{},"worker\u002Fchannel.py",[544,1140,1141],{},"worker\u002Finject.py",[755,1143,1144,1147],{},[778,1145,1146],{},"Kraft to your forge",[778,1148,1149,1150,675,1152,1154,1155],{},"Your own ",[544,1151,725],{},[544,1153,729],{}," login, used as is by ",[544,1156,958],{},[526,1158,1159,1160,1164,1165,1169],{},"A sandbox covers a ",[530,1161,1163],{"href":1162},"\u002Fconcepts\u002Fvocabulary#workspace","workspace","'s members as it covers the root. Where each\nhold lives in the code is under ",[530,1166,1168],{"href":1167},"\u002Fproject\u002Fsource-map#workspace-members","Workspace members","\non the Source map.",[565,1171,1173],{"id":1172},"state-on-disk","State on disk",[526,1175,1176,1177,1180,1181,1184,1185,1187,1188,1191,1192,1194],{},"State lives in ",[544,1178,1179],{},"$KRAFT_HOME"," (default ",[544,1182,1183],{},"~\u002F.kraft","). ",[544,1186,1067],{}," holds the databases,\nsession logs and result files, worktrees, attachment copies, the process id\nfile, and the sandbox's sockets, CA and ref stores. ",[544,1189,1190],{},"config\u002F"," holds the YAML the\nTemplates and Settings screens edit. Kraft seeds ",[544,1193,1190],{}," from the shipped\ndefaults on first run and never overwrites it, so an upgrade cannot clobber an\nedited policy.",[526,1196,1197,1200,1201,1203,1204,1206,1207,563],{},[530,1198,497],{"href":1199},"\u002Fproject\u002Fdata-and-privacy#secrets-and-state"," lists every\nfile in ",[544,1202,1067],{}," with its mode. ",[530,1205,294],{"href":295}," lists\nwhat is in ",[544,1208,1190],{},[565,1210,1212],{"id":1211},"related","Related",[577,1214,1215,1223,1228],{},[580,1216,1217,1219,1220,1222],{},[530,1218,513],{"href":514},": which module under ",[544,1221,559],{}," holds what, and where to change a given thing.",[580,1224,1225,1227],{},[530,1226,493],{"href":494},": what each trust boundary does and does not stop by default.",[580,1229,1230,1232],{},[530,1231,36],{"href":37},": the flow above in terms of statuses and gates.",{"title":1234,"searchDepth":1235,"depth":1235,"links":1236},"",2,[1237,1238,1239,1240,1241,1242],{"id":567,"depth":1235,"text":568},{"id":737,"depth":1235,"text":738},{"id":989,"depth":1235,"text":990},{"id":1027,"depth":1235,"text":1028},{"id":1172,"depth":1235,"text":1173},{"id":1211,"depth":1235,"text":1212},"One FastAPI process, the executor inside it, the worker sessions it spawns, how a work item flows through them, and where each trust boundary is enforced.","md",null,{},true,{"title":509,"description":1243},"AAh7vUkgHLu6ATFymZjVkhRL09GPMY958O3mAV735qU",[1251,1253],{"title":505,"path":506,"stem":507,"description":1252,"children":-1},"Where to get help, which Kraft versions and platforms are supported, what its version numbers promise, and its license.",{"title":513,"path":514,"stem":515,"description":1254,"children":-1},"Which module under src\u002Fkraft\u002F holds what, and where to go to change a given thing.",1791801169912]