[{"data":1,"prerenderedAt":1353},["ShallowReactive",2],{"navigation_docs":3,"-guides-run-run-as-a-service":504,"-guides-run-run-as-a-service-surround":1348},[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":160,"body":506,"description":1341,"extension":1342,"links":1343,"meta":1344,"navigation":1345,"path":161,"seo":1346,"stem":162,"__hash__":1347},"docs\u002F3.guides\u002F4.run\u002F06.run-as-a-service.md",{"type":507,"value":508,"toc":1329},"minimark",[509,518,523,573,576,579,664,671,676,698,728,845,863,866,889,895,904,914,928,946,950,956,965,999,1002,1024,1040,1043,1055,1060,1064,1071,1084,1087,1090,1093,1297,1304,1308,1325],[510,511,512,513,517],"p",{},"Kraft starts at login and starts again if it exits, and ",[514,515,516],"code",{},"kraft admin health","\nshows it running. A second instance with its own home and port runs beside it.",[519,520,522],"h2",{"id":521},"before-you-start","Before you start",[524,525,526,541,566],"ul",{},[527,528,529,532,533,536,537,540],"li",{},[514,530,531],{},"$KRAFT_HOME"," is ",[514,534,535],{},"~\u002F.kraft"," unless you set it; see\n",[538,539,372],"a",{"href":373},".",[527,542,543,544,547,548,551,552,551,555,558,559,562,563,565],{},"Run ",[514,545,546],{},"kraft admin install-service"," from a shell where ",[514,549,550],{},"claude",", ",[514,553,554],{},"git",[514,556,557],{},"gh"," and\nyour other tools are on ",[514,560,561],{},"PATH",". The service takes its ",[514,564,561],{}," from that shell.",[527,567,568,569,572],{},"Kraft must not be running: ",[514,570,571],{},"install-service"," refuses while a server is up.",[519,574,160],{"id":575},"run-kraft-as-a-service",[510,577,578],{},"A service starts Kraft at login and restarts it if it exits.",[580,581,582,610,656],"ol",{},[527,583,584,585],{},"Stop the running server:",[586,587,592],"pre",{"className":588,"code":589,"language":590,"meta":591,"style":591},"language-bash shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","kraft admin stop\n","bash","",[514,593,594],{"__ignoreMap":591},[595,596,599,603,607],"span",{"class":597,"line":598},"line",1,[595,600,602],{"class":601},"szw1H","kraft",[595,604,606],{"class":605},"semJd"," admin",[595,608,609],{"class":605}," stop\n",[527,611,612,613,627,630,631,642,644,645,648,649,652,653,540],{},"Install the service:",[586,614,616],{"className":588,"code":615,"language":590,"meta":591,"style":591},"kraft admin install-service\n",[514,617,618],{"__ignoreMap":591},[595,619,620,622,624],{"class":597,"line":598},[595,621,602],{"class":601},[595,623,606],{"class":605},[595,625,626],{"class":605}," install-service\n",[628,629],"br",{},"On macOS this writes a launchd agent and loads it. On Linux it writes a\nsystemd user unit and enables it. It prints where it wrote the file:",[586,632,637],{"className":633,"code":635,"language":636,"meta":591},[634],"language-text","kraft: wrote \u002FUsers\u002Fyou\u002FLibrary\u002FLaunchAgents\u002Fcom.kraft.daemon.plist, loaded with launchctl\n","text",[514,638,639],{"__ignoreMap":591},[595,640,635],{"className":641},[597],[628,643],{},"On Linux the line names ",[514,646,647],{},"~\u002F.config\u002Fsystemd\u002Fuser\u002Fkraft.service"," (under\n",[514,650,651],{},"$XDG_CONFIG_HOME"," when you set it) and ",[514,654,655],{},"systemctl --user",[527,657,658,659,663],{},"Check the service, as ",[538,660,662],{"href":661},"#verify-the-service","Verify the service"," shows.",[510,665,666,667,540],{},"There is one service per user. Its launchd label and systemd unit name are\nfixed, so run a second instance by hand: see\n",[538,668,670],{"href":669},"#run-two-instances","Run two instances",[672,673,675],"h3",{"id":674},"give-the-service-an-environment","Give the service an environment",[510,677,678,680,681,683,684,687,688,690,691,694,695,697],{},[514,679,571],{}," copies ",[514,682,561],{}," and the variables that locate the instance from\nthe shell you ran it from, and writes them into the unit. The list is in\n",[538,685,372],{"href":686},"\u002Freference\u002Fconfiguration\u002Fenvironment-variables#variables-you-set",".\nTo pick up a changed ",[514,689,561],{}," later, run ",[514,692,693],{},"kraft admin uninstall-service",", then\n",[514,696,571],{}," again.",[510,699,700,701,706,707,709,710,713,714,718,719,723,724,727],{},"Nothing else from that shell reaches the service. A repo's\n",[538,702,703],{"href":293},[514,704,705],{},"env_passthrough"," copies a variable from the\nserver's own environment, so under a service it finds only the ones ",[514,708,571],{}," copied. A\nkey you export in your shell, such as ",[514,711,712],{},"GEMINI_API_KEY"," or a ",[538,715,717],{"href":716},"\u002Fconcepts\u002Fvocabulary#forge","forge"," token, does\nnot reach the ",[538,720,722],{"href":721},"\u002Fconcepts\u002Fvocabulary#worker","workers",". Set it in the service instead, then run\n",[514,725,726],{},"kraft admin restart",":",[524,729,730,768],{},[527,731,732,736,737,740,741,759,761,762,765,766,540],{},[733,734,735],"strong",{},"systemd:"," run ",[514,738,739],{},"systemctl --user edit kraft"," and add the variable to the\ndrop-in it opens:",[586,742,746],{"className":743,"code":744,"language":745,"meta":591,"style":591},"language-ini shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","[Service]\nEnvironment=\"GEMINI_API_KEY=...\"\n","ini",[514,747,748,753],{"__ignoreMap":591},[595,749,750],{"class":597,"line":598},[595,751,752],{},"[Service]\n",[595,754,756],{"class":597,"line":755},2,[595,757,758],{},"Environment=\"GEMINI_API_KEY=...\"\n",[628,760],{},"The drop-in is a separate file from the unit Kraft writes, so it survives\n",[514,763,764],{},"uninstall-service"," and ",[514,767,571],{},[527,769,770,773,774,727,777,836,838,841,842,844],{},[733,771,772],{},"launchd:"," add it to the agent's ",[514,775,776],{},"EnvironmentVariables",[586,778,780],{"className":588,"code":779,"language":590,"meta":591,"style":591},"plutil -replace EnvironmentVariables.GEMINI_API_KEY -string \"${GEMINI_API_KEY:?export GEMINI_API_KEY in this shell first}\" \\\n  ~\u002FLibrary\u002FLaunchAgents\u002Fcom.kraft.daemon.plist\n",[514,781,782,831],{"__ignoreMap":591},[595,783,784,787,791,794,797,800,803,807,810,813,816,819,822,825,828],{"class":597,"line":598},[595,785,786],{"class":601},"plutil",[595,788,790],{"class":789},"ssYy9"," -replace",[595,792,793],{"class":605}," EnvironmentVariables.GEMINI_API_KEY",[595,795,796],{"class":789}," -string",[595,798,799],{"class":605}," \"${",[595,801,712],{"class":802},"s7iLA",[595,804,806],{"class":805},"sklAV",":?",[595,808,809],{"class":802},"export",[595,811,812],{"class":802}," GEMINI_API_KEY",[595,814,815],{"class":802}," in",[595,817,818],{"class":802}," this",[595,820,821],{"class":802}," shell",[595,823,824],{"class":802}," first",[595,826,827],{"class":605},"}\"",[595,829,830],{"class":805}," \\\n",[595,832,833],{"class":597,"line":755},[595,834,835],{"class":605},"  ~\u002FLibrary\u002FLaunchAgents\u002Fcom.kraft.daemon.plist\n",[628,837],{},[514,839,840],{},"-replace"," adds the key or changes it, so it is safe to run again. With the\nvariable unset or empty in your shell, the shell stops the command and prints\nthat message, so an empty value never replaces the key already in the file.\n",[514,843,571],{}," rewrites that file, so do this again after you reinstall\nthe service.",[510,846,847,848,851,852,855,856,859,860,540],{},"Both files are usually readable by other accounts on the machine, and so is a\nkey written into them. On systemd, keep keys in a file only you can read, such\nas ",[514,849,850],{},"~\u002F.config\u002Fkraft\u002Fsecrets.env"," after ",[514,853,854],{},"chmod 600",", and point the drop-in at\nit with ",[514,857,858],{},"EnvironmentFile=%h\u002F.config\u002Fkraft\u002Fsecrets.env"," instead of\n",[514,861,862],{},"Environment=",[672,864,662],{"id":865},"verify-the-service",[586,867,869],{"className":588,"code":868,"language":590,"meta":591,"style":591},"kraft admin restart\nkraft admin health\n",[514,870,871,880],{"__ignoreMap":591},[595,872,873,875,877],{"class":597,"line":598},[595,874,602],{"class":601},[595,876,606],{"class":605},[595,878,879],{"class":605}," restart\n",[595,881,882,884,886],{"class":597,"line":755},[595,883,602],{"class":601},[595,885,606],{"class":605},[595,887,888],{"class":605}," health\n",[510,890,891,894],{},[514,892,893],{},"restart"," goes through the service manager when a service is installed, and\nprints:",[586,896,899],{"className":897,"code":898,"language":636,"meta":591},[634],"kraft: restarted the service\n",[514,900,901],{"__ignoreMap":591},[595,902,898],{"className":903},[597],[510,905,906,909,910,913],{},[514,907,908],{},"health"," exits 0 once the server is back, and its ",[514,911,912],{},"version"," row names the\nrelease it runs:",[586,915,918],{"className":916,"code":917,"language":636,"meta":591},[634],"status         ok\nversion        2.0.0\n",[514,919,920,924],{"__ignoreMap":591},[595,921,923],{"className":922},[597],"status         ok\n",[595,925,927],{"className":926},[597],"version        2.0.0\n",[510,929,930,931,933,934,937,938,941,942,945],{},"After an update and before the restart, ",[514,932,908],{}," also prints the installed\nrelease on an ",[514,935,936],{},"installed"," row that says ",[514,939,940],{},"restart pending",". A 1.4 server shows no\nsuch row: ",[538,943,172],{"href":944},"\u002Fguides\u002Frun\u002Fupgrade-from-1-4#update-from-14","\nsays what to read instead.",[672,947,949],{"id":948},"stop-a-service","Stop a service",[510,951,952,955],{},[514,953,954],{},"kraft admin stop"," does not keep a service stopped: the service manager starts\nit again. Where a guide says to stop the server and Kraft runs as a service,\nremove the service instead, then put it back when you are done.",[510,957,958,959,961,962,964],{},"Before you remove it, save what you added to the service. ",[514,960,764],{},"\ndeletes the service file, and ",[514,963,571],{}," writes a new one from your\nshell:",[524,966,967,994],{},[527,968,969,971,972,974,975,977,978,980,981,984,985,987,988,991,992,540],{},[733,970,772],{}," both commands replace the agent's plist, so every key you added to\nits ",[514,973,776],{}," with ",[514,976,786],{}," is gone, a forge token or worker\ncredentials included, and nothing says so. Before ",[514,979,764],{},", run\n",[514,982,983],{},"plutil -p ~\u002FLibrary\u002FLaunchAgents\u002Fcom.kraft.daemon.plist"," and note the keys\nyou added. After ",[514,986,571],{},", add them again, as\n",[538,989,675],{"href":990},"#give-the-service-an-environment"," shows, then\nrun ",[514,993,726],{},[527,995,996,998],{},[733,997,735],{}," a drop-in is a separate file from the unit Kraft writes, so it\nsurvives. Only what you put in the unit file itself is lost.",[510,1000,1001],{},"Then remove the service:",[586,1003,1005],{"className":588,"code":1004,"language":590,"meta":591,"style":591},"kraft admin uninstall-service\nkraft admin stop\n",[514,1006,1007,1016],{"__ignoreMap":591},[595,1008,1009,1011,1013],{"class":597,"line":598},[595,1010,602],{"class":601},[595,1012,606],{"class":605},[595,1014,1015],{"class":605}," uninstall-service\n",[595,1017,1018,1020,1022],{"class":597,"line":755},[595,1019,602],{"class":601},[595,1021,606],{"class":605},[595,1023,609],{"class":605},[510,1025,1026,1028,1029,1031,1032,1035,1036,1039],{},[514,1027,764],{}," does not wait for the server to finish, so ",[514,1030,954],{},"\nfollows it. It prints ",[514,1033,1034],{},"kraft: no server running",", or ",[514,1037,1038],{},"kraft: stopped (pid N)","\nwhen the server was still draining: go on after either.",[510,1041,1042],{},"Do the task that needs the server stopped. Then put the service back:",[586,1044,1045],{"className":588,"code":615,"language":590,"meta":591,"style":591},[514,1046,1047],{"__ignoreMap":591},[595,1048,1049,1051,1053],{"class":597,"line":598},[595,1050,602],{"class":601},[595,1052,606],{"class":605},[595,1054,626],{"class":605},[510,1056,1057,1059],{},[514,1058,571],{}," takes the environment of the shell you run it from, as above.",[672,1061,1063],{"id":1062},"remove-the-service","Remove the service",[510,1065,1066,1067,1070],{},"Save what you added to the service first, as ",[538,1068,949],{"href":1069},"#stop-a-service","\nsays: removing a launchd agent deletes its file.",[586,1072,1074],{"className":588,"code":1073,"language":590,"meta":591,"style":591},"kraft admin uninstall-service\n",[514,1075,1076],{"__ignoreMap":591},[595,1077,1078,1080,1082],{"class":597,"line":598},[595,1079,602],{"class":601},[595,1081,606],{"class":605},[595,1083,1015],{"class":605},[510,1085,1086],{},"It stops the server, without waiting for it to finish, and deletes the launchd\nagent or the systemd unit. A systemd drop-in you made stays.",[519,1088,670],{"id":1089},"run-two-instances",[510,1091,1092],{},"Two instances need separate homes and separate ports. A second server on the\nsame port refuses to start and names the one already there.",[580,1094,1095,1152,1245,1285],{},[527,1096,1097,1098,1101,1102,1105,1106,1141,1143,1144,1146,1147,713,1149,1151],{},"Start the second instance once on a free port. The first start seeds its\n",[514,1099,1100],{},"config\u002F",". This example uses 8767, since 8765 is the default and 8766 is\nwhere a contributor's ",[514,1103,1104],{},"just dev"," runs:",[586,1107,1109],{"className":588,"code":1108,"language":590,"meta":591,"style":591},"KRAFT_HOME=~\u002Fkraft-staging KRAFT_PORT=8767 kraft admin start --detach\n",[514,1110,1111],{"__ignoreMap":591},[595,1112,1113,1116,1119,1122,1125,1127,1130,1133,1135,1138],{"class":597,"line":598},[595,1114,1115],{"class":802},"KRAFT_HOME",[595,1117,1118],{"class":805},"=",[595,1120,1121],{"class":605},"~\u002Fkraft-staging",[595,1123,1124],{"class":802}," KRAFT_PORT",[595,1126,1118],{"class":805},[595,1128,1129],{"class":605},"8767",[595,1131,1132],{"class":601}," kraft",[595,1134,606],{"class":605},[595,1136,1137],{"class":605}," start",[595,1139,1140],{"class":789}," --detach\n",[628,1142],{},"You can also make ",[514,1145,1100],{}," yourself before the first start, to write its\n",[514,1148,322],{},[514,1150,364],{}," first. The first start then adds each\ndefault file the directory lacks, and keeps the files you wrote.",[527,1153,1154,1155,1157,1158,1160,1161,1164,1165,1167,1168,1171,1172,1174,1175,1177,1178,1181,1182,1184,1185,1187,1188,1190,1191],{},"Write the port into that home's ",[514,1156,322],{},", so the server and the\n",[514,1159,602],{}," command find it without ",[514,1162,1163],{},"KRAFT_PORT",". A port given only as\n",[514,1166,1163],{}," or ",[514,1169,1170],{},"--port"," is not saved, and every other command would still\ndial 8765.",[628,1173],{},"The command below adds the line only if ",[514,1176,322],{}," has no ",[514,1179,1180],{},"port:"," line yet.\nKraft does not seed ",[514,1183,322],{},", so a missing file counts as no ",[514,1186,1180],{}," line.\nA second run changes nothing. If the file already has a ",[514,1189,1180],{}," line, change its\nvalue to 8767 by hand: the command leaves it alone.",[586,1192,1194],{"className":588,"code":1193,"language":590,"meta":591,"style":591},"f=~\u002Fkraft-staging\u002Fconfig\u002Faccess.yaml\ngrep -q '^port:' \"$f\" || printf '\\nport: 8767\\n' >> \"$f\"\n",[514,1195,1196,1206],{"__ignoreMap":591},[595,1197,1198,1201,1203],{"class":597,"line":598},[595,1199,1200],{"class":802},"f",[595,1202,1118],{"class":805},[595,1204,1205],{"class":605},"~\u002Fkraft-staging\u002Fconfig\u002Faccess.yaml\n",[595,1207,1208,1211,1214,1217,1220,1223,1226,1229,1232,1235,1238,1240,1242],{"class":597,"line":755},[595,1209,1210],{"class":601},"grep",[595,1212,1213],{"class":789}," -q",[595,1215,1216],{"class":605}," '^port:'",[595,1218,1219],{"class":605}," \"",[595,1221,1222],{"class":802},"$f",[595,1224,1225],{"class":605},"\"",[595,1227,1228],{"class":805}," ||",[595,1230,1231],{"class":789}," printf",[595,1233,1234],{"class":605}," '\\nport: 8767\\n'",[595,1236,1237],{"class":805}," >>",[595,1239,1219],{"class":605},[595,1241,1222],{"class":802},[595,1243,1244],{"class":605},"\"\n",[527,1246,1247,1248,727,1250],{},"Run every command for that instance with the same ",[514,1249,1115],{},[586,1251,1253],{"className":588,"code":1252,"language":590,"meta":591,"style":591},"KRAFT_HOME=~\u002Fkraft-staging kraft view list\nKRAFT_HOME=~\u002Fkraft-staging kraft admin stop\n",[514,1254,1255,1271],{"__ignoreMap":591},[595,1256,1257,1259,1261,1263,1265,1268],{"class":597,"line":598},[595,1258,1115],{"class":802},[595,1260,1118],{"class":805},[595,1262,1121],{"class":605},[595,1264,1132],{"class":601},[595,1266,1267],{"class":605}," view",[595,1269,1270],{"class":605}," list\n",[595,1272,1273,1275,1277,1279,1281,1283],{"class":597,"line":755},[595,1274,1115],{"class":802},[595,1276,1118],{"class":805},[595,1278,1121],{"class":605},[595,1280,1132],{"class":601},[595,1282,606],{"class":605},[595,1284,609],{"class":605},[527,1286,1287,1288,1290,1291,1293,1294,1296],{},"Start any agent you run yourself with the same ",[514,1289,1115],{},". An agent\nreaches the instance its environment names. Workers inherit their\ninstance's ",[514,1292,1115],{},", so their own ",[514,1295,602],{}," calls reach the instance that\nstarted them.",[510,1298,1299,1300,1303],{},"You know it worked when step 1 prints the address with port 8767, and\n",[514,1301,1302],{},"KRAFT_HOME=~\u002Fkraft-staging kraft view list"," shows the second instance's board,\nnot the first's.",[519,1305,1307],{"id":1306},"next-steps","Next steps",[524,1309,1310,1315,1320],{},[527,1311,1312,1314],{},[538,1313,152],{"href":153},": copy the database before you change a service or a home",[527,1316,1317,1319],{},[538,1318,140],{"href":141},": bind a service beyond loopback, with a password",[527,1321,1322,1324],{},[538,1323,372],{"href":373},": every variable that locates an instance",[1326,1327,1328],"style",{},"html pre.shiki code .szw1H, html code.shiki .szw1H{--shiki-light:#702C00;--shiki-default:#702C00;--shiki-dark:#FFB757}html pre.shiki code .semJd, html code.shiki .semJd{--shiki-light:#032563;--shiki-default:#032563;--shiki-dark:#ADDCFF}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);}html pre.shiki code .ssYy9, html code.shiki .ssYy9{--shiki-light:#023B95;--shiki-default:#023B95;--shiki-dark:#91CBFF}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}",{"title":591,"searchDepth":755,"depth":755,"links":1330},[1331,1332,1339,1340],{"id":521,"depth":755,"text":522},{"id":575,"depth":755,"text":160,"children":1333},[1334,1336,1337,1338],{"id":674,"depth":1335,"text":675},3,{"id":865,"depth":1335,"text":662},{"id":948,"depth":1335,"text":949},{"id":1062,"depth":1335,"text":1063},{"id":1089,"depth":755,"text":670},{"id":1306,"depth":755,"text":1307},"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.","md",null,{},true,{"title":160,"description":1341},"uOp9KxeEvN5Hf2cXBqM6gve_EKznPT1WsJpdfueFxqg",[1349,1351],{"title":156,"path":157,"stem":158,"description":1350,"children":-1},"Where Kraft writes its logs, how to read a session's log, and how to free the disk space worktrees use.",{"title":164,"path":165,"stem":166,"description":1352,"children":-1},"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.",1791801252954]