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 system for building real operations with AI as a worker inside them. You don't prompt a chatbot from the outside; you stand up a project, give your worker the tools and data it needs, and let it build within the cage — on plain files, versioned in git, on a runtime you own.

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 HTTP 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 engine.

If you're a human reading this

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

The topics

• Using Karsa — projects, collections, chat, and the daemon.
• Data and storage — where data goes by shape, and the HTTP API conventions to put it there.
• Building a Karsa app — build inside the project, on the SDK.
• Upgrading — versioning, seeding, and reconcile.
• Anti-patterns — what not to do, and why.

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.
• 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 — sqldb, docdb, blob, queue.
• Upgrading — How packages are versioned, seeded, and reconciled into $KARSA_HOME.
• Anti-patterns — The two big mistakes — building outside Karsa, and reaching for external services.