Skip to main content
Capsule is built around a simple idea: you define the app once in Python, and Capsule uses that definition to run the product everywhere it needs to appear. That same definition controls:
  • the managed runtime that executes your code
  • chat, pages, API surfaces, and external channels
  • tasks, schedules, and background work
  • collections, settings, integrations, secrets, and filesystems
  • product settings such as pricing, keep-warm behavior, and deploy metadata

​
One app definition, many product surfaces

Unlike a split stack where chat, background jobs, file storage, and UI all live in different systems, Capsule lets one app expose multiple surfaces at once:
  • built-in web chat
  • named external channels
  • API endpoints
  • Python DSL pages
  • React pages
  • scheduled jobs
  • background tasks
All of that is packaged off the same App definition. That is why Capsule feels closer to an application platform than to a standalone library.

​
Runtime per app user

Capsule runs the app inside a managed runtime so you do not have to invent your own execution layer around each app user. The same runtime model powers local iteration with capsule serve, hosted deploys with capsule deploy, and the channel-facing versions of the app.

​
Runtime flow

​
What capsule serve and capsule deploy read

When you run capsule serve app:app or capsule deploy app:app, Capsule resolves the app entry point and serializes the app configuration:
  • image and package installs
  • declared pages
  • data handler names
  • collection declarations
  • settings metadata
  • integrations
  • schedule specs
  • filesystems and secrets
That is why a single source file can fully describe both local iteration and production deploys.

​
Handler types

Capsule apps can contain several kinds of executable logic:
  • message handlers for chat or API conversations
  • lifecycle hooks like boot, shutdown, enter, and exit
  • tasks for asynchronous background work
  • schedules for cron-triggered jobs
  • endpoints and ASGI mounts for HTTP surfaces
Each handler runs inside the Capsule runtime with the appropriate context injected, rather than in a completely separate app stack.

​
State layers

There are three main kinds of state in Capsule:
  • session.data for per-conversation key-value state
  • collections for durable document storage
  • settings for scoped configuration values that can be edited through the UI
Use the lightest tool that fits the problem:
  • session.data for ephemeral conversation context
  • collections for real data models
  • settings for configuration, not records

​
UI layers

Capsule has two page models:
  • the Python DSL, where a page returns cpsl.ui.Page([...])
  • React pages registered with app.add_page(...)
Both can consume the same data handlers and collections. That lets the app keep one data model even when the UI becomes richer.

​
Product and deploy knobs live in code

Operational concerns are part of the app definition, not an afterthought:
  • Image(...) controls Python packages, apt packages, and setup commands
  • price and pricing_type describe how the app is sold
  • keep_warm_seconds affects runtime readiness
  • filesystems and secrets wire in external state
  • channels decide where the app can talk to users