[{"data":1,"prerenderedAt":369},["ShallowReactive",2],{"navigation":3,"\u002Fconcepts\u002Fworkspaces":169,"\u002Fconcepts\u002Fworkspaces-surround":364},[4,28,85,127,157],{"title":5,"path":6,"stem":7,"children":8,"icon":27},"Getting Started","\u002Fgetting-started","1.getting-started\u002F1.index",[9,12,17,22],{"title":10,"path":6,"stem":7,"icon":11},"Introduction","i-lucide-house",{"title":13,"path":14,"stem":15,"icon":16},"Installation","\u002Fgetting-started\u002Finstallation","1.getting-started\u002F2.installation","i-lucide-download",{"title":18,"path":19,"stem":20,"icon":21},"Quick start","\u002Fgetting-started\u002Fquick-start","1.getting-started\u002F3.quick-start","i-lucide-zap",{"title":23,"path":24,"stem":25,"icon":26},"Architecture","\u002Fgetting-started\u002Farchitecture","1.getting-started\u002F4.architecture","i-lucide-layers","i-lucide-rocket",{"title":29,"icon":30,"path":31,"stem":32,"children":33,"page":84},"Concepts","i-lucide-lightbulb","\u002Fconcepts","2.concepts",[34,39,44,49,54,59,64,69,74,79],{"title":35,"path":36,"stem":37,"icon":38},"Durable agents","\u002Fconcepts\u002Fdurable-agents","2.concepts\u002F1.durable-agents","i-lucide-infinity",{"title":40,"path":41,"stem":42,"icon":43},"Glossary","\u002Fconcepts\u002Fglossary","2.concepts\u002F10.glossary","i-lucide-book-a",{"title":45,"path":46,"stem":47,"icon":48},"Restate in five minutes","\u002Fconcepts\u002Frestate-primer","2.concepts\u002F2.restate-primer","i-lucide-cpu",{"title":50,"path":51,"stem":52,"icon":53},"Entities & addressing","\u002Fconcepts\u002Fentities-addressing","2.concepts\u002F3.entities-addressing","i-lucide-at-sign",{"title":55,"path":56,"stem":57,"icon":58},"Timelines & events","\u002Fconcepts\u002Ftimelines-events","2.concepts\u002F4.timelines-events","i-lucide-list-ordered",{"title":60,"path":61,"stem":62,"icon":63},"Projections & the catalog","\u002Fconcepts\u002Fprojections-catalog","2.concepts\u002F5.projections-catalog","i-lucide-database",{"title":65,"path":66,"stem":67,"icon":68},"Workspaces & execution","\u002Fconcepts\u002Fworkspaces","2.concepts\u002F6.workspaces","i-lucide-terminal",{"title":70,"path":71,"stem":72,"icon":73},"Harnesses","\u002Fconcepts\u002Fharnesses","2.concepts\u002F7.harnesses","i-lucide-plug",{"title":75,"path":76,"stem":77,"icon":78},"Multi-agent patterns","\u002Fconcepts\u002Fmulti-agent","2.concepts\u002F8.multi-agent","i-lucide-network",{"title":80,"path":81,"stem":82,"icon":83},"Lifecycle & control","\u002Fconcepts\u002Flifecycle","2.concepts\u002F9.lifecycle","i-lucide-sliders-horizontal",false,{"title":86,"icon":87,"path":88,"stem":89,"children":90,"page":84},"Guides","i-lucide-book-open","\u002Fguides","3.guides",[91,106],{"title":92,"icon":93,"path":94,"stem":95,"children":96,"page":84},"Agents","i-lucide-bot","\u002Fguides\u002Fagents","3.guides\u002F1.agents",[97,101],{"title":98,"path":99,"stem":100,"icon":93},"Building agents","\u002Fguides\u002Fagents\u002Fbuilding-agents","3.guides\u002F1.agents\u002F1.building-agents",{"title":102,"path":103,"stem":104,"icon":105},"Frontend integration","\u002Fguides\u002Fagents\u002Ffrontend-integration","3.guides\u002F1.agents\u002F2.frontend-integration","i-lucide-monitor",{"title":107,"icon":108,"path":109,"stem":110,"children":111,"page":84},"Operations","i-lucide-server-cog","\u002Fguides\u002Foperations","3.guides\u002F2.operations",[112,117,122],{"title":113,"path":114,"stem":115,"icon":116},"Self-hosting","\u002Fguides\u002Foperations\u002Fself-hosting","3.guides\u002F2.operations\u002F1.self-hosting","i-lucide-server",{"title":118,"path":119,"stem":120,"icon":121},"Auth & API keys","\u002Fguides\u002Foperations\u002Fauth-api-keys","3.guides\u002F2.operations\u002F2.auth-api-keys","i-lucide-key-round",{"title":123,"path":124,"stem":125,"icon":126},"Backup & restore","\u002Fguides\u002Foperations\u002Fbackup-restore","3.guides\u002F2.operations\u002F3.backup-restore","i-lucide-database-backup",{"title":128,"icon":129,"path":130,"stem":131,"children":132,"page":84},"Reference","i-lucide-book-marked","\u002Freference","4.reference",[133,138,143,148,153],{"title":134,"path":135,"stem":136,"icon":137},"Event schema","\u002Freference\u002Fevents","4.reference\u002F1.events","i-lucide-list-tree",{"title":139,"path":140,"stem":141,"icon":142},"Addressing","\u002Freference\u002Faddressing","4.reference\u002F2.addressing","i-lucide-map-pin",{"title":144,"path":145,"stem":146,"icon":147},"Gateway HTTP API","\u002Freference\u002Fgateway-api","4.reference\u002F3.gateway-api","i-lucide-webhook",{"title":149,"path":150,"stem":151,"icon":152},"CLI","\u002Freference\u002Fcli","4.reference\u002F4.cli","i-lucide-square-terminal",{"title":154,"path":155,"stem":156,"icon":83},"Configuration","\u002Freference\u002Fconfiguration","4.reference\u002F5.configuration",{"title":158,"path":159,"stem":160,"children":161,"icon":163},"Contributing","\u002Fcontributing","5.contributing\u002F1.index",[162,164],{"title":158,"path":159,"stem":160,"icon":163},"i-lucide-git-pull-request",{"title":165,"path":166,"stem":167,"icon":168},"The package map","\u002Fcontributing\u002Fpackage-map","5.contributing\u002F2.package-map","i-lucide-boxes",{"id":170,"title":65,"body":171,"description":357,"extension":358,"links":359,"meta":360,"navigation":361,"path":66,"seo":362,"stem":67,"__hash__":363},"docs\u002F2.concepts\u002F6.workspaces.md",{"type":172,"value":173,"toc":346},"minimark",[174,183,188,203,206,210,217,228,272,276,283,286,290,297,308,312,325,332,336],[175,176,177,178,182],"p",{},"Agents that touch the real world need somewhere to run commands. A ",[179,180,181],"strong",{},"workspace"," is the sandboxed environment — a filesystem plus a shell — that an agent's tools run in, chosen when the agent is spawned.",[184,185,187],"h2",{"id":186},"what-a-workspace-is","What a workspace is",[175,189,190,191,195,196,195,199,202],{},"When an agent has workspace tools enabled, ",[192,193,194],"code",{},"bash",", ",[192,197,198],{},"read_file",[192,200,201],{},"write_file",", and friends all operate inside its workspace. The workspace is picked at spawn time and fixed for the agent's life — an agent never switches workspaces mid-story, so \"where did this file go\" always has one answer.",[175,204,205],{},"Like agents, each workspace processes one command at a time. Two commands aimed at the same workspace run back to back, never interleaved — so even agents sharing a workspace can't trample each other mid-command.",[184,207,209],{"id":208},"private-and-shared-workspaces","Private and shared workspaces",[175,211,212,213,216],{},"By default every agent gets a ",[179,214,215],{},"private"," workspace, named after the agent itself — a fresh, isolated environment nobody else touches.",[175,218,219,220,223,224,227],{},"An agent can hand a child a named workspace instead when it spawns it: several agents spawned with the same name get one ",[179,221,222],{},"shared"," workspace and see the same filesystem. That's the tool for a team of agents collaborating on one checkout — a parent spawns each worker with ",[192,225,226],{},"workspace: \"team-build\""," and they read each other's files, still one command at a time.",[229,230,231],"note",{},[175,232,233,234,236,237,243,244,247,248,254,255,258,259,263,264,267,268,271],{},"A workspace can be chosen at spawn from either side. An agent spawning another sets it with the ",[192,235,181],{}," argument on the ",[238,239,240],"a",{"href":99},[192,241,242],{},"spawn_agent"," tool; a spawn through the gateway sets it with the optional ",[192,245,246],{},"workspaceRef"," field on ",[238,249,251],{"href":250},"\u002Freference\u002Fgateway-api#spawn",[192,252,253],{},"POST \u002Fapi\u002Fspawn"," — a ",[192,256,257],{},"\u003Ctenant>\u002F\u003Cname>"," ",[238,260,262],{"href":261},"\u002Freference\u002Faddressing#workspace-keys","workspace key",". Omit it and the new agent gets its own private workspace. The one exception is the ",[192,265,266],{},"teaspill"," CLI ",[192,269,270],{},"spawn",", which has no workspace flag — spawn through the API (or the frontend SDK) when you need to place an agent in a shared workspace from outside.",[184,273,275],{"id":274},"the-executor-plane","The executor plane",[175,277,278,279,282],{},"Workspaces are hosted by the ",[179,280,281],{},"executor"," — a service plane you deploy alongside your agents, separate from them. It fronts real environments through adapters; the default adapter is Docker: one container per workspace, with a named volume so files persist across commands, container restarts, and idle teardowns.",[175,284,285],{},"The separation is deliberate: agent processes scale on how many model conversations you run; the executor fleet scales on how much compute and disk your workspaces demand. Ten thousand chatty agents with no shell access need lots of the former and none of the latter — and vice versa for three agents compiling a monorepo.",[184,287,289],{"id":288},"long-running-commands","Long-running commands",[175,291,292,293,296],{},"A build that takes twenty minutes doesn't hold anything hostage. While a command runs, its output streams live to a per-workspace output stream — your UI can tail it in real time, the same way it live-follows a ",[238,294,295],{"href":56},"timeline",". When the command finishes, the agent's tool call returns with the exit code and the tail of the output, and the agent's next step proceeds.",[298,299,300],"accordion",{},[301,302,305],"accordion-item",{"icon":303,"label":304},"i-lucide-microscope","Why the agent gets the tail, not the full output",[175,306,307],{},"The full output goes out-of-band to the durable stream, and the recorded tool result carries only the exit code, a bounded tail, and a reference to that stream. This keeps the durable record of the run small — a gigabyte of build logs never enters the agent's replayable history — while losing nothing: the reference points at the complete output, and UIs read it from the stream directly.",[184,309,311],{"id":310},"the-trust-boundary","The trust boundary",[313,314,315],"caution",{},[175,316,317,318,321,322,324],{},"The default Docker adapter works by mounting the host's Docker socket into the executor — and holding that socket is ",[179,319,320],{},"root-equivalent access to the host machine",". This is a reasonable trade for a single-tenant, self-hosted deployment where the executor sits behind the gateway with your own agents; it is not a boundary for running hostile code. Keep the executor internal, never expose it to untrusted callers, and read the hardening options in ",[238,323,113],{"href":114}," before production.",[175,326,327,328,331],{},"The workspace containers themselves are hardened separately — image pinning, per-workspace network isolation — but that protects the workspaces, not the socket. The distinction, and the knobs, are in the ",[238,329,330],{"href":114},"Self-hosting guide",".",[184,333,335],{"id":334},"next-steps","Next steps",[175,337,338,339,343,344,331],{},"Workspaces are where tools ",[340,341,342],"em",{},"run",". The engine deciding which tools to call — the model loop itself — is the harness: ",[238,345,70],{"href":71},{"title":347,"searchDepth":348,"depth":349,"links":350},"",1,2,[351,352,353,354,355,356],{"id":186,"depth":349,"text":187},{"id":208,"depth":349,"text":209},{"id":274,"depth":349,"text":275},{"id":288,"depth":349,"text":289},{"id":310,"depth":349,"text":311},{"id":334,"depth":349,"text":335},"The sandboxed environment an agent's tools run in, and the executor plane that hosts it.","md",null,{},{"icon":68},{"title":65,"description":357},"dLZokiVkNkkKGKNGle1RbIn2U0V2PjOqKrWe_aAYsw8",[365,367],{"title":60,"path":61,"stem":62,"description":366,"icon":63,"children":-1},"The read side of teaspill — one-way copies of what agents do, and the live registry your UI subscribes to.",{"title":70,"path":71,"stem":72,"description":368,"icon":73,"children":-1},"The engine that runs the model loop inside a wake — native for any provider, or Claude Agent SDK for Claude Code semantics.",1784473422967]