Skip to main content
Capsule includes the external-resource model agentic apps usually need: user integrations, workspace-owned secrets, and mounted filesystems. Instead of forcing every app to invent its own storage and credential conventions, Capsule separates these concerns directly in the platform so they stay clear in code.

​
Integrations

Integrations are user-facing connections declared at the app level with app.add_integration(...). Two modes exist:
  • OAuth integrations such as GitHub or Gmail
  • secret-form integrations such as AWS or Tailscale
At runtime, credentials land on session.integrations.

​
Secrets

Secrets are workspace-owned values referenced with cpsl.Secret.from_name(...). Use secrets for:
  • model API keys
  • OAuth client ids and client secrets
  • service credentials owned by the app operator
Secrets are different from integrations because they belong to the app or workspace, not to the end user.

​
Filesystems

Filesystems are named mounted volumes declared in the app config: 
app = cpsl.App(
    name="reports",
    image=cpsl.Image(),
    filesystems={"/data": cpsl.FileSystem("reports")},
)
Use them when data should persist as files rather than documents. In practice, a Capsule filesystem is your app’s mounted distributed storage layer.

​
User uploads

session.prompt_file() bridges user-supplied files into the runtime. It is separate from filesystems:
  • uploads originate from the user
  • filesystems are app-owned mounted storage
Often you use them together by prompting for a file, then saving it into a mounted path.

​
Runtime prompting model

Capsule can render both:
  • blocking integration/file prompts
  • non-blocking hint cards
That is why integrations and uploads can feel native in the chat UI rather than bolted on.