quickstart.mdx

title	Quickstart
description	Build, serve, and deploy a small Capsule app.

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

• First Chat App for the message loop
• Add Data And State for session data and collections
• Add Pages for app UI
• Deploy An App for serve/deploy details
• CLI Reference for the full command surface