Skip to main content
Capsule is a Python framework for building apps that have an agent in the middle, but still need the rest of the application around it: state, UI, background work, integrations, and deployment. If you have ever built a chatbot prototype and then immediately needed:
  • a real page instead of a chat transcript
  • saved data instead of in-memory state
  • a scheduled sync or background job
  • a way for users to connect GitHub, AWS, or Gmail
that is the problem Capsule is trying to solve. 
import cpsl

app = cpsl.App(
    name="sales-assistant",
    image=cpsl.Image(),
)

leads = app.collection(
    "leads",
    columns=["name", "company", "status"],
    scope="app",
)


@app.page("Leads", icon="users")
def leads_page():
    return cpsl.ui.Page([cpsl.ui.Table(leads)])


@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    if msg.text == "count leads":
        await session.reply(f"Leads: {await leads.count()}")
        return

    await session.reply(f"You said: {msg.text}")
That one file already defines:
  • the runtime environment
  • a persisted collection
  • a sidebar page
  • a chat handler
Run it locally with: 
capsule serve app:app

​
What Capsule is for

Capsule is a good fit when the chat loop is only one part of the product. Typical Capsule apps mix a few layers together:
  • a chat surface for free-form user input
  • structured pages for dashboards, workflows, and review steps
  • collections for durable application state
  • data handlers for computed or external data
  • tasks and schedules for slow, recurring, or asynchronous work
In practice that usually means internal tools, operator copilots, research dashboards, customer-facing assistants, or vertical AI products that need a real UI and a real state model behind the model call.

​
The core model

The framework is easier to learn if you keep a few core objects in mind:
  • cpsl.App is the root object. It is both your app definition and the thing Capsule deploys.
  • Session is the live request or conversation context.
  • Collections are your persistent documents. They can be shared app-wide or scoped per user, owner, or session.
  • Data handlers are just Python functions that return JSON.
  • Pages can be declared in Python or written in React.
  • Tasks and schedules move slow work out of the request path.
If you understand those pieces, most of the rest of the SDK feels straightforward.

​
Learn Capsule

If you are new to the framework, follow this order:
  1. Installation to install the SDK and CLI.
  2. Quickstart to run a minimal app.
  3. First Chat App to learn the session model.
  4. Collections And Scopes and Data Handlers And Pages to build real product surfaces.
  5. Tasks And Schedules when you need background work.
  6. Reference when you want exact API behavior.

​
Example apps

The repository also ships a set of examples worth reading once you have the basics down:
  • echo for the smallest chat app
  • platform_test for collections, scopes, auth, and custom pages
  • custom_pages and nootropics for data handlers, DSL pages, React pages, and theme work
  • test_suite for tasks, schedules, TaskBoard, and integration prompts
  • infra_analyst for owner-scoped collections, streaming replies, and pricing
These docs use those examples as source material, but the tutorials are written to be simpler and more focused than the raw example apps. Browse the repository examples here: beam-cloud/capsule