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.

Every space has an encrypted vault. Secrets are encrypted at rest, and the AI never sees plaintext values. The AI works with secret references, and the server substitutes the real value at runtime.

​
Secret types

String - a simple key-value environment variable. The secret name becomes the env var key. 
DATABASE_URL=postgres://...
OPENAI_API_KEY=sk-...
Multi-field - structured credentials (login, API key, OAuth, custom). Injected as a JSON string. 
ACME_LOGIN={"email":"admin@acme.com","password":"..."}

​
Collections and environments

Secrets are organized into collections (groups) and environments (buckets within a collection). 
my-saas/
├── dev/
│   ├── DATABASE_URL → postgres://dev-host/...
│   └── OPENAI_API_KEY → sk-dev-...
├── prod/
│   ├── DATABASE_URL → postgres://prod-host/...
│   └── OPENAI_API_KEY → sk-prod-...
└── (untagged)
    └── STRIPE_WEBHOOK_SECRET → whsec_...
  • Collections have a slug unique per space (e.g. my-saas). Used in CLI commands and kazzle.config.ts.
  • Environments have a slug unique per collection (e.g. dev, prod). Create them explicitly after creating a collection.
  • Untagged secrets (no environment) are included in every environment. Use them for values that don’t change between dev and prod.

​
Injection with the Kazzle CLI

Secrets are injected into processes via kazzle run in your package.json scripts: 
{
  "scripts": {
    "dev": "kazzle run --collection=my-saas --env=dev -- bun run server.ts",
    "start": "kazzle run --collection=my-saas --env=prod -- bun run server.ts"
  }
}
kazzle run calls the server, resolves secrets for the collection + environment, exports them as environment variables, and execs the child command. Secrets exist only in process memory - never on disk.

​
CLI commands

CommandWhat it does
kazzle run --collection=X --env=Y -- <cmd>Injects secrets as env vars, then runs <cmd>
kazzle secrets list --collection=XLists secret names and IDs for a collection
kazzle secrets export --collection=X --env=YExports secrets as KEY=VALUE lines
kazzle git.credentialGit credential helper - resolves repo credentials from the vault

​
Secret value references

A secret’s value can reference another secret field using ${secret.<uuid>.<field>}: 
FULL_DB_URL=postgres://${secret.123e4567-e89b-12d3-a456-426614174000.username}:${secret.123e4567-e89b-12d3-a456-426614174000.password}@host/db
References are resolved server-side at injection time. Broken references fail loudly with the secret ID and field name.

​
How the AI uses secrets

The AI never sees plaintext secret values. It uses ${secret.<secretId>.<field>} templates in tool calls: 
{ "text": "${secret.abc123-uuid.password}" }
The server substitutes the real value at execution time. Chat logs and tool results never contain plaintext.

​
Production deploy

For deployed apps, secrets are declared per component in kazzle.config.ts: 
import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    {
      name: 'server',
      type: 'process',
      path: '.',
      secrets: { collection: 'my-saas', env: 'prod' },
    },
    {
      name: 'web',
      type: 'ui',
      path: '.',
      secrets: { collection: 'my-saas', env: 'prod' },
    },
  ],
});
On deploy:
  • Process parts: secrets are pushed to the cloud as runtime environment variables.
  • UI parts: only secrets prefixed with VITE_ are inlined at build time so they can ship to the browser.

​
Security model

  • Secrets are encrypted at rest. Encryption keys are managed for you.
  • The AI works with secret references, never plaintext values. Chat logs and tool results never contain secrets.
  • The kazzle CLI authenticates with KAZZLE_API_KEY over HTTPS. No secrets touch disk.
  • Two-factor (TOTP) secrets support automatic code generation.