Getting Started
How It Works
The full lifecycle of a Capsul app — from your first message to a deployed URL.
The generation pipeline
You type a prompt
Your message (and the full conversation history) is sent to the Capsul backend along with your app's current HTML if it already exists.
Context is assembled
The backend builds an AI message array: system prompt → current HTML (as an assistant turn) → chat history → your new message. This means every update is aware of the existing code.
AI streams the response
Capsul calls your chosen AI provider (Groq, OpenRouter, or NVIDIA NIM) with streaming enabled. HTML chunks are forwarded to your browser via Server-Sent Events as they arrive.
Live preview updates
While the AI is still generating, the code editor shows partial HTML. Once generation is complete, the preview iframe reloads with the full app.
SDK is injected
Before the preview renders, CapsulDB and (optionally) CapsulAI are injected into the HTML ‹head›. This gives the app live access to its SQLite database and AI proxy without changing any generated code.
Version is checkpointed
The new HTML is saved to the database and added to the version history (last 5 versions kept). You can restore any version at any time.
Single-file architecture
Every Capsul app is a single .html file. All HTML, CSS, and JavaScript live inline. External libraries (Tailwind CDN, Lucide icons, Chart.js) are loaded via CDN script tags. There is no build step, no bundler, no framework — just one file that a browser can open directly.
This constraint has two big benefits: apps are trivially portable (share a URL or send a file), and the AI can regenerate or patch the entire app in a single response without worrying about module boundaries.
How data persists
Generated apps use CapsulDB — a global JavaScript API injected into every app before it runs. In Capsul mode (preview/deployed), database calls are routed to a real SQLite file on the server via a short-lived JWT-authenticated API. In standalone mode (downloaded zip), the same API is backed by AlaSQL running entirely in the browser, persisted to IndexedDB. The generated code doesn't change — only the implementation behind window.CapsulDB switches.
Security model
• API keys are encrypted with AES-256-GCM before being stored. The encryption key (APP_SECRET) lives only in your environment — never in the database.
• App data access uses short-lived (5-minute) HS256 JWTs issued by the Capsul server. Generated apps include no Firebase tokens or long-lived credentials.
• Firebase Authentication handles identity. Every API call verifies a fresh Firebase ID token — sessions never touch your database.
• Rate limiting is enforced at 60 AI generations per user per hour in an in-memory sliding window.