Skip to main content
This tutorial is the day-to-day loop for shipping on Capsule. The point is not just to memorize CLI commands. The point is to see how the Python app definition, the managed runtime, workspace assets, and hosted deploys fit into one product workflow.

​
1. Scaffold a project

If you want a starting point instead of a blank directory: 
capsule bootstrap my-agent-app
cd my-agent-app
Useful templates:
  • minimal for the smallest runnable app
  • chatbot for a BAML-backed assistant
  • dashboard for chat plus a React page

​
2. Authenticate once

capsule login
This stores workspace credentials locally so the rest of the CLI can talk to Capsule.

​
3. Start the live dev loop

Serve the app: 
capsule serve app:app
During serve, Capsule:
  • resolves the entry point
  • uploads your source tree
  • boots a live runtime
  • hot-reloads when watched files change
  • regenerates page type stubs when needed
Watched file types include Python, TSX/TS/JS, CSS, JSON, YAML, images, Markdown, and HTML.

​
4. Bind external channels during local testing

If you have a named channel resource already: 
capsule serve app:app --channel my-telegram-bot
If the channel is already bound elsewhere, you can rebind it for the local serve: 
capsule serve app:app --channel my-telegram-bot --force-channel

​
5. Create workspace assets

As your app grows, these commands become part of the normal loop: 
capsule secret create OPENAI_API_KEY=sk-...
capsule fs create reports
capsule channel create my-telegram-bot --type telegram -c bot_token=123:ABC
These assets are part of what makes Capsule feel like a platform rather than a thin deploy wrapper. Channels, secrets, and filesystems are shared workspace resources that plug directly into the app definition. Useful inspection commands: 
capsule secret list
capsule fs list
capsule channel list
capsule app list

​
6. Deploy a version

When you are happy with the local behavior: 
capsule deploy app:app
Deploy packages the app definition from cpsl.App plus everything it references:
  • runtime image packages and commands
  • pages and data handlers
  • collections, settings, and integrations
  • schedules
  • secrets and mounted filesystems
  • pricing and keep-warm configuration
The deploy output shows the version and hosted URL. If the app has pricing, channels, or mounted filesystems configured, those product settings travel with the same deploy.

​
7. Smoke test the deployed app from Python

Capsule also ships a simple programmatic client: 
import cpsl

client = cpsl.Client()
reply = client.chat("hello-capsule", "ping")
print(reply.text)
You can also stream responses: 
for chunk in client.stream("hello-capsule", "write a summary"):
    print(chunk.text, end="")

​
8. Inspect deployed apps

The app command group helps you inspect what is already in the workspace: 
capsule app list
capsule app get <app-id>
If you need to create an app record explicitly: 
capsule app create --name my-new-app --price 500
Most teams can skip app create at first and let capsule deploy handle the deploy flow from code.

​
9. A practical local-to-prod loop

The normal Capsule workflow looks like this:
  1. edit app.py and any pages/*.tsx files
  2. run capsule serve app:app
  3. test the chat, pages, tasks, and integrations
  4. create or update secrets, channels, and filesystems as needed
  5. run capsule deploy app:app
  6. smoke test with the web UI or cpsl.Client

​
Common pitfalls

  • serve and deploy both expect an entry point like module:symbol.
  • Functional apps require image= on cpsl.App(...).
  • React pages need the correct component= path relative to the project root.
  • External channels should use named cpsl.Channel("name") resources rather than deprecated inline channel classes.
  • If a command says you are not logged in, run capsule login again.

​
Next steps