Skip to main content
Install cpsl, verify the capsule CLI, then authenticate to your workspace. The package includes both pieces:
  • cpsl, the Python API you write your app with
  • capsule, the CLI you use for login, serve, deploy, secrets, channels, and filesystems

​
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

uv add cpsl
Or install 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

which capsule
capsule --help
You should see command groups such as: 
create
login
app
channel
deploy
fs
secret
serve

​
Authenticate to your workspace

capsule login
This opens a browser, authenticates against your workspace, and stores a local token for platform commands. serve, deploy, secret, channel, and fs all talk to Capsule, so login is part of normal local setup.

​
Scaffold a project

Use create when you want a template instead of a blank app.py: 
capsule create my-agent-app --template quickstart
cd my-agent-app
uv sync
The create command can generate:
  • quickstart for a BAML-backed assistant with packaged context
  • media-studio for generated media in chat
  • browser-agent for browser workflows
  • background-agent for scheduled agent loops
Start with quickstart for the main path, then use media-studio, browser-agent, or background-agent when you want a more specialized starter.

​
Next steps