Why Capsule

If your app is more than a single model call, you usually need the same set of things: durable state, workflow pages, background work, integrations, storage, a clean deploy path, and users who can actually sign into the product. Capsule puts those pieces in one app model. You still write normal Python, but you do not have to stitch together a separate runtime, queue, page backend, storage layer, and deployment story around it.

​

What you write vs what Capsule manages

That split is the reason Capsule feels faster than stitching together a model wrapper, a web stack, a worker queue, storage, and channel adapters yourself. You are still building the product logic. You are just not rebuilding the same scaffolding every time.

​

What changes when the app gets real

The first version of an agent is often a single handler. That is fine. But once users depend on it, the shape usually changes:

• the app needs durable state, not just chat history
• the app needs workflow pages, not just free-form text
• the app needs async work that should not block the reply
• the app needs to show up in more than one place
• the app needs users to sign into the product, with access scoped to that app
• the app needs a deploy story that looks like a product, not a demo script

Capsule is opinionated about that transition. It assumes the model call is only one piece of the app, and it gives you product primitives for the rest. That includes the auth boundary. When someone signs into a deployed Capsule app, they become a user of that app. Another Capsule app can have a different authenticated user set, even if the same email appears in both.

​

One definition, multiple surfaces

cpsl.App sits at the center of the system. The same definition can declare:

• the runtime image
• chat handlers
• pages and data handlers
• collections and settings
• tasks and schedules
• integrations, filesystems, and secrets
• channels, pricing, and deploy behavior

That matters because it keeps the app legible as it grows. You do not end up with chat in one place, the queue page in another, background jobs in a third, and deployment knobs somewhere off to the side.

​

A runtime per app user

Capsule runs your app inside a managed, sandboxed runtime per app user. That gives you a consistent place for sessions, handlers, task execution, integrations, and mounted filesystems to live. The unit here is the app user, not a global Capsule identity. That is what lets one deployed app have its own user pool and its own authenticated surfaces. This is one of the biggest differences from a plain library. You are not just importing a chat helper. You are defining something Capsule can actually run, route, and expose as a product.

​

Product primitives instead of app glue

Real apps need a few boring but important things:

• durable records
• long-running work
• authenticated connections to outside systems
• storage for generated files and uploads
• workflow UI for operators or end users

Capsule gives you those pieces directly. Collections, tasks, pages, integrations, filesystems, and settings are all part of the same app model. That means you can spend your time deciding what the product should do instead of deciding which second system should own each concern.

​

When Capsule is the right fit

Capsule is a strong fit when the model is only one part of the application:

• customer-facing assistants that need real product surfaces
• multi-channel agents that have to meet users where they already are
• internal copilots with dashboards, review flows, and operator tasks
• vertical AI products that need files, schedules, integrations, and durable state

If all you need is a one-off script or a single webhook, Capsule may be more machinery than you want. If you are building something users will actually live in, the trade starts to look very good.

​

Where to go next

• Real App Anatomy
• App Model And Runtime
• Quickstart
• Sessions And Channels
• Tasks And Scheduling
• Integrations, Secrets, And Filesystems