Skip to main content
This is the shortest path from an empty project to a live Capsule app. You will build one app with chat and a small page, run it locally, then deploy the same entry point. Once deployed, Capsule gives each app user an isolated sandboxed runtime where your agent can use its Python environment, files, secrets, and mounted filesystems.

​
1. Install Capsule

Install cpsl. The package includes the Python API and the capsule CLI. 
uv add cpsl
or: 
pip install cpsl
Verify the CLI: 
capsule --help

​
2. Authenticate

capsule login
This authenticates your local machine as a builder. Your deployed app will still get its own app-scoped user sign-in flow.

​
3. Create a project from a template

Use a production-shaped starter instead of a blank file: 
capsule create my-app --template quickstart
cd my-app
The generated README shows required secrets, local run commands, and the deploy entry point.

​
4. Install dependencies

If you have uv: 
uv sync
Without uv: 
pip install -e .

​
5. Add secrets

Templates print the exact secret commands they need. For quickstart: 
capsule secret create ANTHROPIC_API_KEY=sk-ant-...
Local environment variables work while serving locally. Deployed apps need Capsule secrets.

​
6. Serve locally

capsule serve app.py:app
Open the preview URL from the command output. You should see a hosted chat surface and a context page.

​
7. Deploy

capsule deploy app.py:app
Deploy packages the same app definition and returns a hosted URL. Users sign into that hosted app; the signed-in user is available inside handlers as session.user.

​
Try another template

capsule create studio --template media-studio
capsule create browser-demo --template browser-agent
capsule create monitor --template background-agent

​
Next steps