Connect Services

Real apps need credentials and durable storage. Capsule separates those into three primitives:

integrations for credentials that belong to the app user
secrets for credentials that belong to the workspace or app operator
filesystems for mounted durable files

1. Create workspace resources

capsule secret create OPENAI_API_KEY=sk-...
capsule fs create reports

Secrets and filesystems are workspace resources. The app opts into them in code.

2. Inject secrets and mount filesystems

app = cpsl.App(
    name="connected-app",
    image=cpsl.Image(python_packages=["openai"]),
    secrets=["OPENAI_API_KEY"],
    filesystems={"/data": cpsl.FileSystem("reports")},
)

Inside the runtime, /data behaves like a normal mounted directory.

3. Declare user integrations

Use integrations when the credential belongs to the signed-in app user.

app.add_integration(
    cpsl.GitHub(
        client_id=cpsl.Secret.from_name("GITHUB_CLIENT_ID"),
        client_secret=cpsl.Secret.from_name("GITHUB_CLIENT_SECRET"),
        scopes=["repo", "read:user"],
    )
)

Known secret-form integrations can be declared directly:

app.add_integration(cpsl.AWS())

4. Prompt at runtime

@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    github = await session.require_integration(
        cpsl.Integration.GITHUB,
        reason="Connect GitHub so I can inspect repositories.",
    )
    await session.reply(f"Connected GitHub with scopes: {github.scopes}")

Use show_integration(...) instead when the connection is optional and you only want to render a non-blocking card.

5. Save files

with open("/data/report.txt", "w") as f:
    f.write("Generated by Capsule\n")

Use collections for queryable records and filesystems for durable files, generated artifacts, uploads, and large intermediate outputs.

Next steps

Add long-running work with Background Work.
See Integrations, Secrets, and Filesystems.

Start Here

Build Apps

Features

Concepts

Updates

Connect Services

1. Create workspace resources

2. Inject secrets and mount filesystems

3. Declare user integrations

4. Prompt at runtime

5. Save files

Next steps

​1. Create workspace resources

​2. Inject secrets and mount filesystems

​3. Declare user integrations

​4. Prompt at runtime

​5. Save files

​Next steps

1. Create workspace resources

2. Inject secrets and mount filesystems

3. Declare user integrations

4. Prompt at runtime

5. Save files

Next steps