Skip to main content
Capsule has two pieces that work together:
  • cpsl, the Python app API you use to define handlers, pages, collections, tasks, channels, and pricing
  • capsule, the CLI that talks to the Capsule platform for login, serve, deploy, secrets, channels, and filesystems
If you want the shortest path from code to a live agentic app, install the package, log into your workspace, and then move straight into the Quickstart.

​
Requirements

  • Python 3.10+
  • a virtual environment or uv project
  • access to a Capsule workspace if you want to serve, deploy, manage secrets, create channels, or mount filesystems

​
Install with uv

If you use uv, add Capsule to your project: 
uv add cpsl
Or install it into a virtual environment directly: 
uv venv
source .venv/bin/activate
uv pip install cpsl

​
Install with pip

python -m venv .venv
source .venv/bin/activate
pip install cpsl

​
Verify the CLI

capsule --help
You should see the main command groups: 
bootstrap
login
app
channel
deploy
fs
secret
serve

​
Authenticate to your workspace

Before you use the Capsule platform from your local machine, log in: 
capsule login
This opens a browser, authenticates against your workspace, and stores the token locally so serve, deploy, secret, channel, and fs commands can talk to Capsule. This step matters earlier than people often expect. capsule serve is not just a local script runner. It boots the Capsule dev loop around your app definition, so workspace auth is part of the normal setup. If you are targeting a local gateway, set the gateway URL first: 
export CAPSULE_GATEWAY_URL=localhost:1980
capsule login

​
Scaffold a project

To start from a template instead of a blank file: 
capsule bootstrap my-agent-app
The bootstrap command can generate:
  • minimal for a tiny message handler
  • chatbot for a BAML-backed chat app
  • dashboard for chat plus a custom React page

​
What gets installed

The cpsl package includes both the Python app API and the CLI:
  • cpsl.App, cpsl.Session, cpsl.Image, cpsl.Secret, and the rest of the app-building surface
  • the capsule CLI for workspace auth, live serve, deploys, secrets, channels, and filesystems

​
Next steps

  • Follow the Quickstart to go from one Python file to a live Capsule app.
  • Read Why Capsule if you want the platform story before diving into APIs.
  • Use First Chat App if you want a fuller walkthrough.
  • See CLI Reference for every command and subcommand.