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.
or:
Verify the CLI:

​
2. Authenticate

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:
The generated README shows required secrets, local run commands, and the deploy entry point.

​
4. Install dependencies

If you have uv:
Without uv:

​
5. Add secrets

Templates print the exact secret commands they need. For quickstart:
Local environment variables work while serving locally. Deployed apps need Capsule secrets.

​
6. Serve locally

Open the preview URL from the command output. You should see a hosted chat surface and a context page.

​
7. Deploy

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

​
Next steps