The Karsa Manual

This is the bible — the one place to learn how Karsa works and how to work inside it. It is written for two readers at once: the human running Karsa, and the agent working inside a project. Wherever you are — the web UI at /doc, a file under $KARSA_HOME/doc/, or a page on karsa.app/doc — it is the same manual, from the same source.

Karsa is a local-first runtime for turning successful AI work into reusable systems — persistent data, automations, schedules, tasks, and AI agents, running on your own machine. You don't prompt a chatbot from the outside; you stand up a project, give your agents the tools and data they need, and let them build within the cage — on plain files, versioned in git, on a runtime you own. Start personal and local; the same project can move to the cloud when it matters, without a rebuild.

If you're an agent reading this

You are working inside a Karsa project. Before you reach for anything external, read this manual:

doc_data-and-storage. doc_using-karsa — the shape of a project: collections, chat, the daemon, where things live on disk. $KARSA_API_BASE. doc_data-and-storage — where data goes by shape, and the rpc API conventions to put it there: use $KARSA_API_BASE, upload assets, sqldb + collections, docdb docs. Read this before you save anything. doc_building-a-karsa-app. doc_building-a-karsa-app — when the task is "build an app," you build it here, on the Karsa SDK. This is the most important page for you. doc_anti-patterns. doc_anti-patterns — the mistakes that look reasonable and are wrong. Read this before you decide to install Supabase, scaffold a Next.js app in /tmp, or stand up your own database.

The manual is the shared, maintained truth. Your system prompt points you here on purpose — so the answer lives in one place, stays current, and is the same for every agent harness.

If you're a human reading this

Start with Using Karsa for the lay of the land, Agents for who does the work, then Building a Karsa app when you want an agent to produce something real. Upgrading explains how the pieces stay current; Anti-patterns is worth a skim so you recognize an agent heading the wrong way.

The topics

• Using Karsa — projects, collections, chat, and the daemon.
• Agents — what an agent is, chats and tasks, making and managing agents, waking them from automations.
• Data and storage — where data goes by shape, and the rpc API conventions to put it there.
• Building a Karsa app — build inside the project, on the SDK.
• Upgrading — how Karsa updates itself: one version, a signed release list, the Updater, the sudo step and the way back.
• Anti-patterns — what not to do, and why.
• The agent primer — what every agent harness is told on every turn.
• Always-on agents — an agent that works between your messages (also called ambient, background or long-running), built step by step.

Topics

• How Karsa works — The mental model — artifacts, types, collections, resources, events, and subscribers.
• Using Karsa — Projects, collections, chat, and the daemon — the shape of day-to-day work.
• Agents — What an agent is, your first one, talking to agents in chat, handing them tasks, creating and managing agents through the API (persona, docs, context, harness, notifications), waking one from code, and two worked examples (an ingress; store every event and wake in batches).
• Data and storage — Where data goes by shape, and the Karsa HTTP API conventions an agent uses to put it there.
• Automating with events, subscribers, and fns — How an agent wires up reactive + scheduled work on Karsa's infra — publish events, create subscribers, bind them to fns.
• The Karsa API — The uniform CRUD surface every collection gets for free, the special endpoints, and how to discover it all.
• Building a Karsa app — Build the app INSIDE the project, on the Karsa SDK. An app is a CAGED namespace under app/{app_id}/ and a bundle of fns Karsa calls at fixed moments (setup.check, setup.install, subscribers, service, ui) — like App Store apps on iOS. Covers fn runtimes (code | cli + flags), native vs non-native, the bundle, exposed-fn API, permissions, addressing, and the gotchas from building codex.
• Upgrading — How Karsa updates itself — one version, a signed release list, the Updater app's daily check, download and install, the sudo step, and the way back.
• Anti-patterns — The two big mistakes — building outside Karsa, and reaching for external services.
• The agent primer — What every agent is told each time it wakes — Karsa, your project, the API, where things go, chats and tasks, the manual, how to answer — before its own persona.
• Always-on agents — An agent that keeps working between your messages — woken by a clock, by the outside world (webhooks) and by your data changing (a shared partner's too), with a work queue that survives restarts, memory, a sign-off loop and boundaries — built step by step with the ops, for agents and the person who runs the server.
• The browser — @karsa/browser: a headless Chrome your project's agents share, profiles (the project's, an agent's own) that keep their logins apart, signing one in from its page, and how an agent uses it.