Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Secrets

Kazzle has a built-in encrypted vault for storing API keys, database credentials, tokens, and other sensitive values your app needs. Secrets are encrypted at rest with AES-256-GCM using KMS-wrapped data encryption keys — plaintext values never touch the database.

​
Concepts

Collections group related secrets together (e.g. stripe-keys, database-credentials). Every collection has a slug (lowercase, hyphenated) that you reference in config files and CLI commands. Environments are optional scopes within a collection (e.g. production, staging). Secrets can be scoped to a specific environment or left at the collection level as defaults. Resolution order: when resolving secrets for a given collection + environment, environment-specific secrets override collection-level secrets with the same name. This lets you share most secrets across environments while overriding specific values per-environment.

​
Managing secrets

​
In the app

Open Settings > Vault to create collections, environments, and secrets through the UI.

​
With the AI

The AI can create collections, create environments, store secrets, move them between scopes, and delete them for you. The AI sees secret names and metadata but not the encrypted values.

​
With the CLI

# Run a command with secrets injected as env vars
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

# Export secrets as KEY=value lines
kazzle secrets.export --collection=stripe-keys --env=production

​
Referencing secrets from your app

Add the secrets field to a component in kazzle.config.ts: 
import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    {
      name: 'API Server',
      type: 'process',
      path: './server',
      secrets: {
        collection: 'stripe-keys',
        env: 'production'
      }
    }
  ]
});
Both collection and env are slugs, not display names.

​
How secrets become env vars

When secrets are resolved for a component:
  1. The collection is found by slug within your space
  2. Secrets scoped to the specified environment are loaded
  3. Collection-level secrets (no environment) are included as defaults
  4. Environment-specific secrets override collection-level ones with the same name
  5. Secret references inside values are resolved
  6. Secret names are converted to env var format: uppercased, non-alphanumeric characters become underscores
A secret named Stripe Secret Key becomes STRIPE_SECRET_KEY. Each secret has a body mode that determines how it’s injected:
  • string secrets (API keys, tokens, URIs) are injected as plain scalar strings
  • json secrets (structured config) are injected as JSON strings
  • fields secrets (login credentials, typed field bags) are injected as JSON strings

​
When secrets are injected

ContextInjected?Details
Deploy (process component)YesAdded as runtime environment variables in production
Deploy (UI component)PartialOnly VITE_* prefixed secrets are passed at build time
CLI (kazzle run)YesInjected into the command’s environment
CLI (secrets.export)YesExported as KEY=value lines
Dev previewNot yetThe preview starter doesn’t resolve component.secrets yet — use kazzle run for now

​
Template references

Secret values can reference other secret fields with the same syntax Kazzle uses elsewhere: 
postgresql://${secret.123e4567-e89b-12d3-a456-426614174000.username}:${secret.123e4567-e89b-12d3-a456-426614174000.password}@db.example.com:5432/mydb
Supported formats:
  • ${secret.<uuid>} — whole secret value
  • ${secret.<uuid>.<field>} — specific field or JSON path
References are resolved after secrets are loaded. Circular or broken references fail instead of silently falling back.