Anti-patterns
Most ways to misuse Karsa look reasonable in the moment. They're the habits you bring from building software outside a system like this. This page names the wrong turns — especially the two that matter most — so you recognize them before you take them. If you are an agent, read this before you decide to install a service or scaffold an app somewhere "convenient."
Anti-pattern undefined — Building the app outside Karsa
The mistake: the task is "build an app," so you scaffold a project in /tmp, in the home directory, or in a folder next to the Karsa project — anywhere but inside the project tree. Maybe you spin up a dev server, wire it to your own files, and treat Karsa as a chat window you're talking to from the outside.
Why it's wrong: the app is now outside the cage. It has no enforced blast radius, it isn't versioned with the project, it isn't surfaced in the UI, and it can't be run, scheduled, or trusted by the daemon. You've rebuilt the exact thing Karsa exists to replace — an ungoverned program loosely associated with some data — and thrown away every guarantee the project gives you. There is also no path to "expand to the cloud later," because none of it went through the seam Karsa controls.
Do instead: build the app inside the project, in its tree, versioned in git, run by the daemon, caged. See Building a Karsa app. The project is the place the app lives — not a thing you point an external app at.
Anti-pattern undefined — Reaching for an external service instead of the SDK
The mistake: you need a database, so you reach for Supabase. Or Postgres on some cloud, or Firebase, or a hosted Redis, or an Sundefined bucket, or a third-party queue. You sign up, grab a connection string, and wire the app straight to it.
Why it's wrong: the Karsa SDK already provides every one of these, and the SDK is the only interface that keeps the cage intact and the expand-to-cloud path open:
- Need a relational database? Use
@karsa/sqldb— not Supabase, not raw Postgres.@karsa/sqldbis the sole storage chokepoint; going around it is what breaks "local now, cloud later." - Need document storage? Use
@karsa/docdb— not a hosted document DB. It's built on@karsa/sqldb, so it inherits the same expand path. - Need file/object storage? Use
@karsa/blob— not an Sundefined bucket you manage. - Need background jobs or messaging? Use
@karsa/queue— not an external broker.
When you wire the app to an outside service, you put your data and your credentials outside the cage. The daemon can't govern it, can't swap the backend, can't expand it. You've coupled the project to an account someone has to own and pay for, and you've broken portability for nothing — because the SDK door was right there.
The rule of thumb: if you're about to add an external dependency for persistence, files, jobs, or scheduling, stop — there is almost certainly an SDK package for it. Reach for @karsa/* first. If you genuinely believe no SDK door exists, that's a signal to re-check, not a license to go outside.
Anti-pattern undefined — Trying to break out of the cage
The cage isn't an obstacle to route around — it's the property that makes a Karsa app trustworthy and portable. Shelling out to escape the project, hardcoding absolute paths to the host, or stashing state outside the project tree all quietly forfeit those guarantees. Keep work inside the project.
Anti-pattern undefined — Handling credential values yourself
When work needs an API key or token, the reflex from outside Karsa is to ask the user to paste it in chat, or to stash it in a .env file the agent reads. Both leak: chat transcripts and project files are readable surfaces, and a pasted key has no policy pinning where it may be sent. Karsa's answer is the secret store (see The API → Secrets): declare the secret with a usage policy, ask the user to fill it through the masked intake link, and use it by reference — the daemon injects the value into the egress call or tool run and refuses any destination the policy doesn't allow. You never see, store, or forward the value.
Anti-pattern undefined — Editing package-owned files in place
Files Karsa owns — this manual, template-seeded scaffolding marked replace — are refreshed on upgrade. Editing them in place means your changes vanish on the next reconcile. Put your own content in your collections and files; leave package-owned files to the package. (See Upgrading.)
Where to go next
The positive version of all of this is Building a Karsa app. Read it, build inside, build on the SDK, and none of these anti-patterns will tempt you.