Configuration

Every Kazzle app has a kazzle.config.ts at its project root. The file exports one app definition: the same contract Kazzle uses for published apps and built-in connectors.

Quick start

import { defineApp } from '@kazzle/app';

export default defineApp({
  schemaVersion: 1,
  name: 'My App',
  subtitle: 'A short catalog description',
  description: { type: 'markdown', path: 'README.md' },
  maxInstallations: 1,
  setup: { type: 'none' },
  launch: { type: 'component', component: 'web' },
  components: [{ name: 'web', type: 'ui', path: '.' }],
  tools: [],
  skills: [],
});

defineApp validates the definition and provides TypeScript autocompletion. Unsupported or misspelled fields fail validation instead of being ignored.

Definition fields

Field	Type	Required	Description
`schemaVersion`	`1`	yes	Version of the definition contract.
`name`	`string`	yes	Display name in the catalog and detail page.
`subtitle`	`string`	yes	One-line catalog description.
`description`	`{ type: 'markdown', path: string }`	yes	Markdown bundled with the app, usually `README.md`.
`version`	`string`	no	Publisher version shown with the installed app.
`icon`	`string`	no	Icon path relative to the app root.
`accentColor`	hex color	no	Brand accent color.
`maxInstallations`	`number \| null`	yes	Maximum installations per space; `null` allows any number.
`setup`	setup object	yes	How an installation is configured.
`launch`	launch object	yes	What opens after installation.
`components`	component[]	yes	UI and process components.
`tools`	tool source[]	yes	Sources that compile into callable AI tools.
`skills`	skill[]	yes	Instructions loaded when relevant.
`kazzleAuth`	`'optional' \| 'required'`	no	Whether the launch surface requires Kazzle identity.
`webhookUrl`	URL	no	Receives installation lifecycle webhooks.
`appLogin`	`boolean`	no	Enables the app’s own end-user login.

Setup

An app chooses exactly one setup flow.

setup: { type: 'none' }

Use none when installation needs no external authorization.

setup: {
  type: 'oauth',
  version: '2.0',
  metadata: {
    type: 'endpoints',
    authorizationUrl: 'https://provider.example.com/oauth/authorize',
    tokenUrl: 'https://provider.example.com/oauth/token',
  },
  scopes: ['account.read'],
  pkce: 'required',
  authorizationParams: {},
  fields: [],
}

Use oauth for OAuth 1.0a or OAuth 2.0. OAuth client credentials are configured privately when the app is published; they never appear in the definition.

setup: {
  type: 'form',
  labelField: 'accountUrl',
  fields: [
    { key: 'accountUrl', label: 'Account URL', kind: 'url', required: true, secret: false },
    { key: 'apiKey', label: 'API key', kind: 'password', required: true, secret: true },
  ],
}

Form fields support text, password, url, hostname, email, and select. labelField may reference a non-secret field to distinguish multiple installations.

Launch

launch: { type: 'none' }
launch: { type: 'component', component: 'web' }
launch: { type: 'url', url: 'https://example.com', target: 'external' }

A component target must name a component in the same definition. URL targets choose embedded or external explicitly.

Components

Each component has a unique name, a type of ui or process, and a source path. An app can have at most one UI component.

components: [{
  name: 'server',
  type: 'process',
  path: './server',
  runtime: {
    dev: { command: 'bun run dev' },
    prod: { command: 'bun run start', build: 'bun run build' },
  },
}]

env can select a secret collection and environment for a component. Process components may also declare persistent or triggered execution and named schedule or webhook triggers.

Tools and skills

Tools and skills are independent. Tools define callable operations; skills explain when and how to use them.

tools: [
  { name: 'app-tools', type: 'file', path: './tools.ts' },
  {
    name: 'stripe',
    type: 'connection_actions',
    actions: ['customers.list', 'invoices.list'],
  },
],
skills: [
  { name: 'billing', source: { type: 'file', path: './skills/billing/SKILL.md' } },
  { name: 'review', source: { type: 'inline', instructions: 'Confirm before write actions.' } },
]

Connection actions require an installation when called. They are emitted by Kazzle’s system-app converter; published apps define callable tools in files. Skills remain separate and can be loaded only when relevant.

Get started

Build

Users and data

Publish

Using Kazzle

Security

Reference

Configuration

Configuration

Quick start

Definition fields

Setup

Launch

Components

Tools and skills

​Configuration

​Quick start

​Definition fields

​Setup

​Launch

​Components

​Tools and skills

Configuration

Quick start

Definition fields

Setup

Launch

Components

Tools and skills