Upgrading

Karsa ships as a set of versioned packages — the daemon, the CLI, the web UI, project templates, and this manual (@karsa/doc). Upgrading is the act of pulling newer versions and letting the daemon reconcile them onto your machine. This page explains the model so an upgrade is never a mystery.

Packages and the registry

Everything shippable is a package with a name, a version, and a kind. The set of available packages — and where to fetch each one — is listed in a registry (registry.json). The registry is the source of truth for "what versions exist"; your install pulls from it.

A package's kind says how it's handled:

daemon / cli — the binaries that run Karsa.
web / landing — the UIs.
template — project provisioning templates (what gets seeded when you create a project).
doc — this manual, seeded to $KARSA_HOME/doc.
engine — an AI engine plugin (e.g. a local-model engine).

Installing

The install script reads the registry, downloads the package list it names — the daemon and CLI binaries plus the default content packages (web, this manual, the base project template, and any default engines) — verifies each by checksum, and places it by kind: binaries on your PATH (the karsa command), the web UI and manual and templates under $KARSA_HOME. Then it points you at karsa start. Starting the daemon registers what's on disk so it's live.

Seeding and reconcile

When you install or upgrade, the daemon seeds package content onto disk and then reconciles it — an idempotent pass that makes the on-disk state match what the installed packages declare. Reconcile never deletes your data; it ensures the directories and package-owned files are present and current.

Each package declares a reconcile policy for its files:

replace — the file is package-owned; on upgrade the newer version wins. The manual (doc/) is replace: you read it, you don't edit it, so a newer manual simply takes over.
merge — the file may carry local edits, so an upgrade layers changes in rather than clobbering.
install-if-absent — files like a project's index.md are written only when missing, so your edits are never overwritten.

This is why upgrading is safe: package-owned content refreshes, your content stays put.

Live upgrades vs. restart

Karsa hot-swaps packages at runtime — almost every upgrade applies without downtime, and you don't stop anything. A package is just files the daemon reads, and registering a newly-installed one is a live, in-place action:

Served fresh every request — the web UI and this manual. Swap the files and the next page load has the new version.
Re-registered on reconcile — your project's collections, types, agent profiles, subscribers, and engine / event-handler plugins. A reconcile pass re-reads them (re-importing changed plugin code) while the server keeps running.
The CLI (karsa) is a separate, short-lived program — it just talks to the running daemon. Upgrading the karsa binary changes nothing about the server; the next command you run is simply the new version.

The one thing that can't update live is the running daemon itself: upgrading the Karsa server binary means new server code, so the daemon re-execs (a quick, automatic handoff — your data lives on disk and is reloaded on start). Engines built into the server come along with it; engine plugins installed alongside register without a restart. In short: upgrading the Karsa server gives the daemon a brief, self-managed bounce; everything else — the CLI, plugins, web, docs, templates — is seamless.

Your running agents survive that bounce. A chat or task that's mid-run isn't tied to the daemon's life: each engine runs behind a thin wrapper that keeps going and keeps writing its log to disk even while the server is down. When the new daemon comes back it reattaches — it picks the run's log back up, finishes streaming the reply into your chat, and marks it complete, exactly as if nothing happened. If a run genuinely died during the gap (its process was hard-killed), the daemon notices it went quiet, confirms it's gone, and finalizes it as failed rather than leaving it spinning. Either way you don't lose work to an upgrade or a restart.

Upgrading the manual specifically

@karsa/doc is kind: doc, policy replace. On upgrade the daemon re-seeds $KARSA_HOME/doc from the newer bundle. Agents reading the manual off the filesystem, humans reading it at /doc, and the public reading karsa.app/doc all move to the new version together — one source, three surfaces.

Tools and `karsa doctor`

Beyond Karsa's own packages, your projects depend on external tools (git, ripgrep, an AI engine, etc.). These aren't upgraded by the reconcile pass — they live on your system. Run karsa doctor (or open the Tools collection in the System project) to see what's installed and install or update what's missing in a click.

Where to go next

For what to do with an up-to-date Karsa, read Using Karsa and Building a Karsa app.