[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/docs",{"_7":8,"_9":10,"_11":12},"path","develop/local-development.mdx","markdownUrl","/llms.mdx/docs/develop/local-development/content.md","pageTree",{"_13":14,"_15":16},"$fumadocs_loader","page-tree","data",{"_17":18,"_19":20,"_21":22,"_23":24},"$id","root","name","OpenSana Docs","children",[79,80,81],"fallback",{"_17":25,"_19":26,"_21":27},"fallback:root","Docs",[28],{"_29":30,"_19":31,"_18":-7,"_32":-7,"_33":-7,"_34":-7,"_21":35,"_17":36,"_37":-7,"_38":-7},"type","folder","Use","defaultOpen","description","collapsible",[39,40,41,42],"fallback:use","$ref","icon",{"_29":30,"_19":73,"_18":-7,"_32":44,"_33":74,"_34":-7,"_21":75,"_17":76,"_37":77,"_38":-7},{"_29":30,"_19":57,"_18":-7,"_32":44,"_33":58,"_34":-7,"_21":59,"_17":60,"_37":61,"_38":-7},{"_29":30,"_19":51,"_18":-7,"_32":44,"_33":52,"_34":44,"_21":53,"_17":54,"_37":55,"_38":-7},{"_29":30,"_19":43,"_18":-7,"_32":44,"_33":45,"_34":44,"_21":46,"_17":47,"_37":48,"_38":-7},"Working with AI",true,"Connect OpenSana to MCP-aware clients and install project skills.",[],"fallback:use/working-with-ai",{"_49":50},"metaFile","use/working-with-ai/meta.json","User Interface","Navigate projects, tasks, comments, and AI threads in the web app.",[],"fallback:use/user-interface",{"_49":56},"use/user-interface/meta.json","Deployment","Deploy and operate OpenSana in the supported Convex-based model.",[63],"fallback:use/deployment",{"_49":62},"use/deployment/meta.json",{"_17":64,"_29":65,"_19":66,"_33":67,"_38":-7,"_68":69,"_37":70},"fallback:use/deployment/deploy-to-vercel.mdx","page","Deploy to Vercel","Deploy the OpenSana Next.js web app to Vercel with integrated Convex deployment.","url","/docs/use/deployment/deploy-to-vercel",{"_71":72},"file","use/deployment/deploy-to-vercel.mdx","CLI","Install, connect, configure, and troubleshoot the OpenSana CLI.",[],"fallback:use/cli",{"_49":78},"use/cli/meta.json",{"_17":460,"_29":65,"_19":20,"_33":461,"_38":-7,"_68":462,"_37":463},{"_29":30,"_19":195,"_18":44,"_32":44,"_33":196,"_34":-7,"_21":197,"_17":198,"_37":199,"_38":-7},{"_29":30,"_19":82,"_18":44,"_32":44,"_33":83,"_34":-7,"_21":84,"_17":85,"_37":86,"_38":-7},"Develop OpenSana","Architecture, tests, internals.",[88,89,90,91,92,93,94,95,96,97],"develop",{"_49":87},"develop/meta.json",{"_17":191,"_29":65,"_19":148,"_33":192,"_38":-7,"_68":193,"_37":194},{"_17":8,"_29":65,"_19":187,"_33":188,"_38":-7,"_68":189,"_37":190},{"_17":182,"_29":65,"_19":183,"_33":184,"_38":-7,"_68":185,"_37":186},{"_17":177,"_29":65,"_19":178,"_33":179,"_38":-7,"_68":180,"_37":181},{"_17":172,"_29":65,"_19":173,"_33":174,"_38":-7,"_68":175,"_37":176},{"_17":167,"_29":65,"_19":168,"_33":169,"_38":-7,"_68":170,"_37":171},{"_17":162,"_29":65,"_19":163,"_33":164,"_38":-7,"_68":165,"_37":166},{"_17":157,"_29":65,"_19":158,"_33":159,"_38":-7,"_68":160,"_37":161},{"_17":152,"_29":65,"_19":153,"_33":154,"_38":-7,"_68":155,"_37":156},{"_29":30,"_19":98,"_18":-7,"_32":44,"_33":99,"_34":-7,"_21":100,"_17":101,"_37":102,"_38":-7},"CLI Internals","Architecture and contracts behind the OpenSana CLI runtime bridge.",[104,105,106,107,108,109,110,111],"develop/cli",{"_49":103},"develop/cli/meta.json",{"_17":147,"_29":65,"_19":148,"_33":149,"_38":-7,"_68":150,"_37":151},{"_17":142,"_29":65,"_19":143,"_33":144,"_38":-7,"_68":145,"_37":146},{"_17":137,"_29":65,"_19":138,"_33":139,"_38":-7,"_68":140,"_37":141},{"_17":132,"_29":65,"_19":133,"_33":134,"_38":-7,"_68":135,"_37":136},{"_17":127,"_29":65,"_19":128,"_33":129,"_38":-7,"_68":130,"_37":131},{"_17":122,"_29":65,"_19":123,"_33":124,"_38":-7,"_68":125,"_37":126},{"_17":117,"_29":65,"_19":118,"_33":119,"_38":-7,"_68":120,"_37":121},{"_17":112,"_29":65,"_19":113,"_33":114,"_38":-7,"_68":115,"_37":116},"develop/cli/protocols-and-payloads.mdx","Protocols and Payloads","Runtime payload shapes, normalized events, and server-facing chunk semantics.","/docs/develop/cli/protocols-and-payloads",{"_71":112},"develop/cli/codex-runtime-planned.mdx","Codex Runtime (Planned)","Planned direction for Codex runtime support in OpenSana.","/docs/develop/cli/codex-runtime-planned",{"_71":117},"develop/cli/claude-code-runtime.mdx","Claude Code Runtime","The current production runtime for OpenSana CLI thread execution.","/docs/develop/cli/claude-code-runtime",{"_71":122},"develop/cli/message-and-chunk-data-model.mdx","Message and Chunk Data Model","Understand how thread messages, assistant envelopes, and normalized chunks fit together.","/docs/develop/cli/message-and-chunk-data-model",{"_71":127},"develop/cli/claims-heartbeats-retries-failures.mdx","Claims, Heartbeats, Retries, and Failures","Understand the reliability model behind CLI thread execution.","/docs/develop/cli/claims-heartbeats-retries-failures",{"_71":132},"develop/cli/lifecycle.mdx","CLI Lifecycle","Follow a thread from session registration to streamed completion or failure.","/docs/develop/cli/lifecycle",{"_71":137},"develop/cli/architecture-overview.mdx","CLI Architecture Overview","Understand the CLI as the bridge between OpenSana threads and local agent runtimes.","/docs/develop/cli/architecture-overview",{"_71":142},"develop/cli/index.mdx","Overview","Internal architecture documentation for the OpenSana CLI and runtime bridge.","/docs/develop/cli",{"_71":147},"develop/contributing-conventions.mdx","Contributing Conventions","Follow the repo's code style, validation, and ownership conventions when contributing.","/docs/develop/contributing-conventions",{"_71":152},"develop/specs-first-workflow.mdx","Specs-First Workflow","Use the internal specs as the implementation source of truth before changing behavior.","/docs/develop/specs-first-workflow",{"_71":157},"develop/testing.mdx","Testing","Run and extend the main test suites in OpenSana.","/docs/develop/testing",{"_71":162},"develop/mcp-server-architecture.mdx","MCP Server Architecture","Understand how OpenSana exposes an MCP server over the Convex HTTP layer.","/docs/develop/mcp-server-architecture",{"_71":167},"develop/convex-backend-architecture.mdx","Convex Backend Architecture","Understand how the Convex schema, functions, and permission model are organized.","/docs/develop/convex-backend-architecture",{"_71":172},"develop/web-app-architecture.mdx","Web App Architecture","A high-level map of the Next.js application and frontend domain boundaries.","/docs/develop/web-app-architecture",{"_71":177},"develop/repository-structure.mdx","Repository Structure","Understand how the OpenSana monorepo is organized.","/docs/develop/repository-structure",{"_71":182},"Local Development","Run the web app, Convex backend, docs app, and supporting tools locally.","/docs/develop/local-development",{"_71":8},"develop/index.mdx","Contributor documentation for understanding and extending OpenSana.","/docs/develop",{"_71":191},"Use OpenSana","User guides, CLI, deploy.",[201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234],"use",{"_49":200},"use/meta.json",{"_17":457,"_29":280,"_38":458,"_19":459},{"_17":453,"_29":65,"_19":365,"_33":454,"_38":-7,"_68":455,"_37":456},{"_17":448,"_29":65,"_19":449,"_33":450,"_38":-7,"_68":451,"_37":452},{"_17":443,"_29":65,"_19":444,"_33":445,"_38":-7,"_68":446,"_37":447},{"_17":441,"_29":280,"_38":442,"_19":51},{"_17":436,"_29":65,"_19":437,"_33":438,"_38":-7,"_68":439,"_37":440},{"_17":431,"_29":65,"_19":432,"_33":433,"_38":-7,"_68":434,"_37":435},{"_17":426,"_29":65,"_19":427,"_33":428,"_38":-7,"_68":429,"_37":430},{"_17":421,"_29":65,"_19":422,"_33":423,"_38":-7,"_68":424,"_37":425},{"_17":416,"_29":65,"_19":417,"_33":418,"_38":-7,"_68":419,"_37":420},{"_17":414,"_29":280,"_38":415,"_19":73},{"_17":410,"_29":65,"_19":148,"_33":411,"_38":-7,"_68":412,"_37":413},{"_17":405,"_29":65,"_19":406,"_33":407,"_38":-7,"_68":408,"_37":409},{"_17":400,"_29":65,"_19":401,"_33":402,"_38":-7,"_68":403,"_37":404},{"_17":395,"_29":65,"_19":396,"_33":397,"_38":-7,"_68":398,"_37":399},{"_17":390,"_29":65,"_19":391,"_33":392,"_38":-7,"_68":393,"_37":394},{"_17":385,"_29":65,"_19":386,"_33":387,"_38":-7,"_68":388,"_37":389},{"_17":380,"_29":65,"_19":381,"_33":382,"_38":-7,"_68":383,"_37":384},{"_17":375,"_29":65,"_19":376,"_33":377,"_38":-7,"_68":378,"_37":379},{"_17":373,"_29":280,"_38":374,"_19":43},{"_17":369,"_29":65,"_19":148,"_33":370,"_38":-7,"_68":371,"_37":372},{"_29":30,"_19":340,"_18":-7,"_32":44,"_33":341,"_34":44,"_21":342,"_17":343,"_37":344,"_38":-7},{"_29":30,"_19":311,"_18":-7,"_32":44,"_33":312,"_34":44,"_21":313,"_17":314,"_37":315,"_38":-7},{"_29":30,"_19":282,"_18":-7,"_32":44,"_33":283,"_34":44,"_21":284,"_17":285,"_37":286,"_38":-7},{"_17":279,"_29":280,"_38":281,"_19":57},{"_17":275,"_29":65,"_19":148,"_33":276,"_38":-7,"_68":277,"_37":278},{"_17":270,"_29":65,"_19":271,"_33":272,"_38":-7,"_68":273,"_37":274},{"_17":265,"_29":65,"_19":266,"_33":267,"_38":-7,"_68":268,"_37":269},{"_17":260,"_29":65,"_19":261,"_33":262,"_38":-7,"_68":263,"_37":264},{"_17":255,"_29":65,"_19":256,"_33":257,"_38":-7,"_68":258,"_37":259},{"_17":250,"_29":65,"_19":251,"_33":252,"_38":-7,"_68":253,"_37":254},{"_17":245,"_29":65,"_19":246,"_33":247,"_38":-7,"_68":248,"_37":249},{"_17":240,"_29":65,"_19":241,"_33":242,"_38":-7,"_68":243,"_37":244},{"_17":235,"_29":65,"_19":236,"_33":237,"_38":-7,"_68":238,"_37":239},"use/deployment/faq.mdx","FAQ","Short answers to common OpenSana usage, CLI, and deployment questions.","/docs/use/deployment/faq",{"_71":235},"use/deployment/self-hosting-convex.mdx","Self-Hosting (Experimental)","Experimental guidance for running OpenSana against a self-hosted Convex deployment.","/docs/use/deployment/self-hosting-convex",{"_71":240},"use/deployment/operations-and-debugging.mdx","Operations and Debugging","Diagnose common production and integration issues in OpenSana deployments.","/docs/use/deployment/operations-and-debugging",{"_71":245},"use/deployment/production-checklist.mdx","Production Checklist","A practical launch checklist for an OpenSana deployment.","/docs/use/deployment/production-checklist",{"_71":250},"use/deployment/email-and-resend.mdx","Email and Resend","Configure transactional email delivery for invitations and onboarding flows.","/docs/use/deployment/email-and-resend",{"_71":255},"use/deployment/auth-and-clerk.mdx","Auth and Clerk","Configure Clerk as the authentication layer for OpenSana deployments.","/docs/use/deployment/auth-and-clerk",{"_71":260},"use/deployment/environment-variables.mdx","Environment Variables","Reference for all environment variables, where each one belongs, and what it does.","/docs/use/deployment/environment-variables",{"_71":265},"use/deployment/deploy-with-convex.mdx","Deploy the Convex Backend","Create a Convex deployment, configure environment variables, and push functions and schema.","/docs/use/deployment/deploy-with-convex",{"_71":270},"use/deployment/index.mdx","Deploy and operate OpenSana for real users and connected CLIs.","/docs/use/deployment",{"_71":275},"_4","separator","","Dev Container","Run AI CLIs in an isolated workspace with optional network restrictions.",[288,289,290,291],"use/working-with-ai/dev-container",{"_49":287},"use/working-with-ai/dev-container/meta.json",{"_17":307,"_29":65,"_19":148,"_33":308,"_38":-7,"_68":309,"_37":310},{"_17":302,"_29":65,"_19":303,"_33":304,"_38":-7,"_68":305,"_37":306},{"_17":297,"_29":65,"_19":298,"_33":299,"_38":-7,"_68":300,"_37":301},{"_17":292,"_29":65,"_19":293,"_33":294,"_38":-7,"_68":295,"_37":296},"use/working-with-ai/dev-container/troubleshooting.mdx","Troubleshooting","Diagnose common dev container issues affecting OpenSana profiles, MCP connectivity, and AI CLIs.","/docs/use/working-with-ai/dev-container/troubleshooting",{"_71":292},"use/working-with-ai/dev-container/opensana-and-ai-clis.mdx","OpenSana and AI CLIs","Use the dev container with OpenSana profiles, Claude Code, MCP config, and project-local AI setup.","/docs/use/working-with-ai/dev-container/opensana-and-ai-clis",{"_71":297},"use/working-with-ai/dev-container/setup-and-modes.mdx","Setup and Modes","Build the dev container, provide host environment variables, and choose between strict or open networking.","/docs/use/working-with-ai/dev-container/setup-and-modes",{"_71":302},"use/working-with-ai/dev-container/index.mdx","Use the project dev container to run AI CLIs inside an isolated development environment.","/docs/use/working-with-ai/dev-container",{"_71":307},"Skills","Install OpenSana skills and connect supported AI clients in your project workflow.",[317,318,319,320],"use/working-with-ai/skills",{"_49":316},"use/working-with-ai/skills/meta.json",{"_17":336,"_29":65,"_19":148,"_33":337,"_38":-7,"_68":338,"_37":339},{"_17":331,"_29":65,"_19":332,"_33":333,"_38":-7,"_68":334,"_37":335},{"_17":326,"_29":65,"_19":327,"_33":328,"_38":-7,"_68":329,"_37":330},{"_17":321,"_29":65,"_19":322,"_33":323,"_38":-7,"_68":324,"_37":325},"use/working-with-ai/skills/codex-planned.mdx","Codex (Planned)","Understand the planned Codex integration path and how its setup differs from fully supported flows.","/docs/use/working-with-ai/skills/codex-planned",{"_71":321},"use/working-with-ai/skills/claude-code.mdx","Claude Code","Set up Claude Code to use OpenSana MCP config and installed skills.","/docs/use/working-with-ai/skills/claude-code",{"_71":326},"use/working-with-ai/skills/install-skills.mdx","Install Skills","Install OpenSana skills for supported clients and choose the right scope for your setup.","/docs/use/working-with-ai/skills/install-skills",{"_71":331},"use/working-with-ai/skills/index.mdx","Connect supported AI clients to OpenSana through generated config and installed skills.","/docs/use/working-with-ai/skills",{"_71":336},"MCP Server","Connect OpenSana through the Model Context Protocol.",[346,347,348,349],"use/working-with-ai/mcp",{"_49":345},"use/working-with-ai/mcp/meta.json",{"_17":364,"_29":65,"_19":365,"_33":366,"_38":-7,"_68":367,"_37":368},{"_17":359,"_29":65,"_19":360,"_33":361,"_38":-7,"_68":362,"_37":363},{"_17":354,"_29":65,"_19":355,"_33":356,"_38":-7,"_68":357,"_37":358},{"_17":350,"_29":65,"_19":293,"_33":351,"_38":-7,"_68":352,"_37":353},"use/working-with-ai/mcp/troubleshooting.mdx","Diagnose common MCP setup, discovery, and project scoping problems.","/docs/use/working-with-ai/mcp/troubleshooting",{"_71":350},"use/working-with-ai/mcp/workflows-and-scoping.mdx","Workflows and Scoping","Understand how MCP access maps to OpenSana projects, profiles, and daily workflows.","/docs/use/working-with-ai/mcp/workflows-and-scoping",{"_71":354},"use/working-with-ai/mcp/connect-and-configure.mdx","Connect and Configure","Generate MCP configuration for supported clients and bind it to the right OpenSana project.","/docs/use/working-with-ai/mcp/connect-and-configure",{"_71":359},"use/working-with-ai/mcp/index.mdx","Introduction","Use MCP to expose OpenSana tasks and project context to supported AI clients.","/docs/use/working-with-ai/mcp",{"_71":364},"use/working-with-ai/index.mdx","Set up MCP and client-side skills so OpenSana works smoothly with local AI tools.","/docs/use/working-with-ai",{"_71":369},"_3","","use/cli/troubleshooting.mdx","CLI Troubleshooting","Diagnose common setup, auth, runtime, and profile issues in the OpenSana CLI.","/docs/use/cli/troubleshooting",{"_71":375},"use/cli/init-mcp-and-editor-integration.mdx","Init, MCP, and Editor Integration","Generate MCP config and install OpenSana skills for supported CLI targets.","/docs/use/cli/init-mcp-and-editor-integration",{"_71":380},"use/cli/api-keys.mdx","API Keys","Create and manage API keys for the CLI and MCP integrations.","/docs/use/cli/api-keys",{"_71":385},"use/cli/one-shot-commands.mdx","One-Shot Commands","Use the CLI as a scriptable interface for organizations, projects, tasks, and artifacts.","/docs/use/cli/one-shot-commands",{"_71":390},"use/cli/profiles-paths-status.mdx","Profiles, Paths, and Status","Understand how the CLI resolves saved profiles and working directories.","/docs/use/cli/profiles-paths-status",{"_71":395},"use/cli/setup-and-connect.mdx","Setup and Connect","Configure a CLI profile and start a long-running OpenSana agent connection.","/docs/use/cli/setup-and-connect",{"_71":400},"use/cli/install.mdx","Install the CLI","Install or run the OpenSana CLI on demand.","/docs/use/cli/install",{"_71":405},"use/cli/index.mdx","Connect local agent runtimes to OpenSana and run one-shot task commands.","/docs/use/cli",{"_71":410},"_2","","use/user-interface/threads-and-ai-chats.mdx","Threads and AI Chats","Work with project and task-scoped AI conversations backed by connected CLIs.","/docs/use/user-interface/threads-and-ai-chats",{"_71":416},"use/user-interface/comments-attachments-artifacts.mdx","Comments, Files, and Artifacts","Store discussion, files, and structured markdown deliverables on tasks.","/docs/use/user-interface/comments-attachments-artifacts",{"_71":421},"use/user-interface/subtasks.mdx","Subtasks","Use task hierarchies to break larger work into smaller pieces.","/docs/use/user-interface/subtasks",{"_71":426},"use/user-interface/tasks.mdx","Tasks","Create, organize, update, and search tasks in OpenSana.","/docs/use/user-interface/tasks",{"_71":431},"use/user-interface/organizations-projects-roles.mdx","Orgs, Projects, and Roles","Understand how OpenSana groups work and grants access.","/docs/use/user-interface/organizations-projects-roles",{"_71":436},"_1","","use/key-concepts.mdx","Key Concepts","Learn the core objects and workflows that shape how OpenSana works.","/docs/use/key-concepts",{"_71":443},"use/getting-started.mdx","Quick Start","Create your first workspace structure, task, and thread in OpenSana.","/docs/use/getting-started",{"_71":448},"use/index.mdx","Product documentation for people using OpenSana, including admins and CLI users.","/docs/use",{"_71":453},"_0","","Getting Started","index.mdx","Public documentation for using, operating, and developing OpenSana.","/docs",{"_71":460}]

Local Development

Prerequisites

Main Commands

Local URLs

Optional Tooling

Contributor Advice

On this page