Configuration

FrogBot reads frogbot.config.ts, frogbot.config.mjs, or frogbot.config.js from the current directory or a parent. Set FROGBOT_CONFIG_PATH to use another location.

Create the file

Export the result of buildConfig from your project root.

import { sqliteAdapter } from '@frogbotai/db-sqlite'
import { buildConfig } from 'frogbot'

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: sqliteAdapter({
    client: {
      url: process.env.DATABASE_URL ?? 'file:./frogbot.db'
    }
  }),
  collections: []
})

buildConfig validates the FrogBot surface, runs plugins, and returns a sanitized configuration. Run type generation to add configured agent slugs to GeneratedTypes.

Set core options

FrogBotConfig requires secret, db, and collections. globals are forbidden; use collections instead.

Option	Type	Default	Description
`secret`	`string`	Required	Signs tokens and cookies and encrypts stored secrets.
`previousSecrets`	`string[]`	—	Earlier `secret` values still accepted for reads (verifying tokens, matching API keys, decrypting stored values) while you rotate the secret. New data always uses `secret`.
`db`	`DatabaseAdapter`	Required	Database adapter, such as `sqliteAdapter()`. See Database.
`collections`	`CollectionConfig[]`	Required	Collections to register. When none has `auth`, FrogBot adds a `users` auth collection. See Collections.
`admin`	`RootAdminConfig`	—	Root admin panel options, such as `user`, `meta`, `theme`, and `components`. See Root components.
`agents`	`AgentConfig[]`	—	Code-defined agents. Requires `ai`. See Agents.
`ai`	`AIConfig`	—	Providers, routers, access, hooks, and telemetry. See AI.
`auth`	`{ jwtOrder: ('JWT' \| 'Bearer' \| 'cookie')[] }`	`{ jwtOrder: ['JWT', 'Bearer', 'cookie'] }`	Order in which the built-in strategy reads a token from the `Authorization: JWT` header, the `Authorization: Bearer` header, and the auth cookie. Methods left out of `jwtOrder` aren’t read. `jwtOrder` is required when you set `auth`.
`baseAccess`	`{ collections?: CollectionAccess; globals?: GlobalAccess }`	—	Access rules combined with every collection’s and global’s own access using AND.
`blocks`	`Block[]`	—	Blocks registered once and referenced by slug from Blocks fields. See Root block registration.
`bodyParser`	`Partial<BusboyConfig>`	—	Options passed to the busboy parser for `multipart/form-data` requests, such as `limits`. Experimental.
`cli`	`{ commands?: Record<string, CLICommand> }`	—	Adds commands to the `frogbot` CLI, or replaces built-in ones. See Plugin commands.
`connections`	`ConnectionsConfig`	—	Providers users can link accounts with. See Connections.
`cookiePrefix`	`string`	`'frogbot'`	Prefix for every cookie FrogBot sets, such as `frogbot-token`.
`cors`	`'' \| string[] \| { origins: '' \| string[]; headers?: string[] }`	`[]`	Origins allowed to make cross-origin requests. `'*'` allows any origin. The object form also adds allowed request `headers`. See Cookies.
`csrf`	`string[]`	`[]`	Origins whose requests may authenticate with the auth cookie. `serverURL` is added automatically when set. See Cookies.
`custom`	`Record<string, any>`	`{}`	Your own server-only data. FrogBot doesn’t read it.
`debug`	`boolean`	`false`	Returns error messages and stack traces in API responses, including errors that are normally hidden.
`defaultDepth`	`number`	`1`	Relationship population depth used when a request doesn’t set `depth`. See Depth.
`defaultMaxTextLength`	`number`	`40000`	Maximum length of Text and Textarea values when the field doesn’t set `maxLength`.
`editor`	`RichTextAdapterProvider`	—	Default editor for Rich Text fields. Required when any collection has a Rich Text field without its own `editor`. See Rich Text.
`email`	`EmailPiece \| Promise<EmailPiece>`	No email	Email piece used to send verification and password-reset messages. Without it, FrogBot warns at startup and logs email sends instead of delivering them. See Email.
`endpoints`	`Endpoint[]`	—	Root REST endpoints. Handlers receive `FrogBotRequest`. See Custom endpoints.
`graphQL`	`GraphQLConfig`	See GraphQL options	GraphQL API options.
`hooks`	`{ afterError?: AfterErrorHook[] }`	—	Root hooks. See Root hooks.
`i18n`	`I18nOptions`	English only	Admin panel languages and translations. See I18n.
`indexSortableFields`	`boolean`	`false`	Adds a database index to every sortable top-level field. Useful for databases that require an index to sort, such as Azure Cosmos DB.
`jobs`	`JobsConfig`	—	Tasks, workflows, queues, and schedules. See Jobs Queue.
`kv`	`KVAdapterResult`	`databaseKVAdapter()`	Key-value store behind `frogbot.kv`. See Key-value store.
`llmInstructions`	`false \| { access?: Access; editor?: RichTextAdapter }`	`{}`	Agent instructions editors can save per collection, shared with MCP clients. `access` adds who may edit them (default: users of the admin user collection); `false` removes the collection and the menu item.
`localization`	`false \| LocalizationConfig`	`false`	Content locales. See Localization.
`logger`	`'sync' \| { options: LoggerOptions; destination?: DestinationStream } \| Logger`	Pretty-printed pino logger	Logger behind `frogbot.logger`. Pass pino options, options with a destination stream, or a pino logger instance. `'sync'` writes logs synchronously.
`loggingLevels`	`Partial<Record<ErrorName, Level \| false>>`	See description	Log level for each error class, or `false` to not log it. Defaults: `info` for `Forbidden`, `Locked`, `MissingFile`, `NotFound`, and `ValidationError`; `error` for the rest.
`maxDepth`	`number`	`10`	Highest `depth` any request can use. Larger values are lowered to this limit.
`onInit`	`OnInit \| OnInit[]`	—	Runs after initialization with the `FrogBot` instance. See Run initialization steps.
`plugins`	`Plugin[]`	—	Functions that transform the config, in order, before sanitization. See Run plugins.
`queryPresets`	`QueryPresetsConfig`	—	Access rules for saved list filters, columns, and sorts on collections with `enableQueryPresets`. See Query presets.
`routes`	`RoutesConfig`	See Routes	URL paths for the admin panel, REST API, and GraphQL.
`serverURL`	`string`	`''`	Absolute URL of your app, such as `https://example.com`, with no path. Used for links in emails and file URLs, and added to `csrf`.
`settings`	`SettingsEntry[]`	—	Pages added to the admin Settings area. See Register a settings page.
`storage`	`StorageAdapter[]`	—	File storage adapters from `@frogbotai/storage-*`. The first also serves FrogBot’s own upload collections. See Storage adapters.
`telemetry`	`boolean`	`true`	Sends anonymous usage events. Set `false` to turn it off.
`tools`	`readonly (AnyTool \| MCPServer)[]`	—	Tools and MCP servers attached to every agent. See Share tools across agents.
`typescript`	`TypeScriptConfig`	See Type generation options	Type generation options.
`upload`	`FetchAPIFileUploadOptions`	`{}`	Options for parsing uploaded files on every upload collection, and the `transformers` that process them, such as `sharpTransformer()`. See Uploads.

Routes

Option	Type	Default	Description
`admin`	`string`	`'/'`	Path the admin panel is mounted at.
`api`	`string`	`'/api'`	Path prefix for the REST API.
`graphQL`	`string`	`'/graphql'`	Path of the GraphQL endpoint, below `api`.
`graphQLPlayground`	`string`	`'/graphql-playground'`	Path of the GraphQL Playground, below `api`.

Query presets

Option	Type	Default	Description
`access`	`{ create?, delete?, read?, update?: Access }`	Required	Access rules for the presets collection, applied to every preset.
`constraints`	`{ create?, delete?, read?, update?: QueryPresetConstraint[] }`	Required	Extra sharing options users can pick per preset, in addition to the built-in ones. Each constraint has a `label`, a `value`, optional `fields` to collect, and an `access` function.
`filterConstraints`	`FilterOptions`	—	Limits which sharing options a user can pick, in the same form as a Select field’s `filterOptions`.
`labels`	`{ singular?, plural? }`	—	Labels for the presets collection.

Key-value store

frogbot.kv stores JSON values by key. The default databaseKVAdapter() uses a collection in your database. Use redisKVAdapter() from @frogbotai/kv-redis to keep keys in Redis instead.

import { redisKVAdapter } from '@frogbotai/kv-redis'

export default buildConfig({
  // required options omitted
  kv: redisKVAdapter({ redisURL: process.env.REDIS_URL })
})

databaseKVAdapter() options (imported from frogbot/kv)

Option	Type	Default	Description
`kvCollectionOverrides`	`Partial<CollectionConfig>`	—	Changes the generated KV collection, such as its `slug`. Custom fields are merged with the required `key`, `data`, and `expiresAt` fields, which must keep their types.

redisKVAdapter() options

Option	Type	Default	Description
`redisURL`	`string`	`process.env.REDIS_URL`	Redis connection URL. Startup fails when neither is set.
`keyPrefix`	`string`	`'payload-kv:'`	Prefix added to every key stored in Redis.

Assemble an app

Keep collections and agents in separate modules and import them into the config.

import { sqliteAdapter } from '@frogbotai/db-sqlite'
import { buildConfig } from 'frogbot'

import { agents } from './src/agents'
import { Posts } from './src/collections/Posts'
import { Users } from './src/collections/Users'

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: sqliteAdapter({
    client: {
      url: process.env.DATABASE_URL ?? 'file:./frogbot.db'
    }
  }),
  collections: [Users, Posts],
  admin: {
    user: 'users',
    theme: 'all',
    meta: {
      title: 'Support workspace',
      titleSuffix: '- Acme'
    }
  },
  ai: {
    providers: {
      openai: true
    },
    routers: {
      fast: { model: 'openai/gpt-4o-mini' }
    },
    defaultModel: 'fast'
  },
  agents,
  cors: ['http://localhost:3000']
})

admin.meta takes the page metadata type from next, so apps that install next get its full autocomplete. In a package without next, admin.meta is untyped when skipLibCheck is true, and TypeScript reports Cannot find module 'next' when it is false. agents is an array of AgentConfig objects, not a directory path. FrogBot v0 does not scan AGENT.md files or upsert them into a collection. Configuring an agent also enables chat persistence. FrogBot injects owner-scoped chats and messages collections unless you adopt those roles with chat: true and message: true. See Chat persistence.

Configure inference

Provider credentials are converted into an embedded gateway during initialization. Aliases map one slug to one provider-prefixed model ID and do not add fallback or per-alias access rules.

ai: {
  providers: {
    openai: true,
    internal: {
      type: 'openai-compatible',
      baseUrl: 'https://models.internal.example/v1',
      models: [{ id: 'support-v1', mode: 'chat' }]
    }
  },
  routers: {
    fast: { model: 'openai/gpt-4o-mini' },
    internal: { model: 'internal/support-v1' }
  },
  access: {
    generate: ({ req }) => Boolean(req.user)
  }
}

See AI for operation signatures, AI SDK v7 output, hooks, and the authenticated /api/v1/* mount. Every option of a custom endpoint and its models is listed in Custom provider options.

Register workers

Each entry supplies a URL-safe slug, model or alias, instructions, optional tools, an optional stop condition, and optional access.

import { isStepCount } from 'frogbot'
import type { AgentConfig } from 'frogbot'

export const supportAgent: AgentConfig = {
  slug: 'support',
  model: 'fast',
  instructions: 'Resolve support questions using the available tools.',
  stopWhen: isStepCount(8),
  access: ({ req }) => Boolean(req.user)
}

An ai block is required when agents is present. See Agents for tools and invocation.

Add endpoints

Root endpoint handlers receive FrogBotRequest, including req.frogbot.

import { buildConfig } from 'frogbot'
import type { Endpoint } from 'frogbot'

const summarize: Endpoint = {
  path: '/summarize',
  method: 'post',
  handler: async req => {
    const result = await req.frogbot.generateText({
      model: 'fast',
      prompt: 'Summarize the request',
      req
    })

    return Response.json({ text: result.text })
  }
}

export default buildConfig({
  // required options omitted
  endpoints: [summarize]
})

FrogBot reserves /agents and /agents/* for its agent API. A collection cannot use the agents slug.

Run plugins

Plugins receive and return FrogBotConfig, synchronously or asynchronously. They run one at a time before sanitization, by order, lowest first; plugins with the same order run in array order. See Order, slug, and options.

import { buildConfig } from 'frogbot'
import type { Plugin } from 'frogbot'

const addCors: Plugin = config => ({
  ...config,
  cors: ['https://app.example.com']
})

export default buildConfig({
  // required options omitted
  plugins: [addCors]
})

A plugin failure stops the build and reports its array index. Plugins that need initialization should append a callback instead of wrapping an existing one.

const addWarmup: Plugin = config => ({
  ...config,
  onInit: [
    ...(config.onInit === undefined
      ? []
      : Array.isArray(config.onInit)
        ? config.onInit
        : [config.onInit]),
    async frogbot => {
      await warmCache(frogbot)
    }
  ]
})

Run initialization steps

Pass one callback or an array to onInit. Array callbacks are awaited sequentially in declared order, and each receives the initialized FrogBot instance. If a callback throws or rejects, startup fails immediately and later callbacks do not run. An empty array is a no-op.

export default buildConfig({
  // required options omitted
  onInit: [runMigrations, seedDefaults, warmCache]
})

Follow startup

Startup applies the configuration in this order.

Validate secret, db, collections, and the absence of globals.
Run plugins serially.
Resolve chat collection roles and inject any missing defaults.
Sanitize collections, endpoints, AI, and workers.
Initialize FrogBot and attach req.frogbot to supported request paths.
Create the embedded gateway and register optional AI telemetry.
Build the typed worker registry.
Run configured onInit callbacks.

When workers are configured, sanitization also mounts GET /api/agents and POST /api/agents/:slug. The standalone server mounts authenticated gateway traffic under /api/v1/* before forwarding other /api/* requests to FrogBot.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Create the file

Set core options

Routes

Query presets

Key-value store

Assemble an app

Configure inference

Register workers

Add endpoints

Run plugins

Run initialization steps

Follow startup

​Create the file

​Set core options

​Routes

​Query presets

​Key-value store

​Assemble an app

​Configure inference

​Register workers

​Add endpoints

​Run plugins

​Run initialization steps

​Follow startup

Create the file

Set core options

Routes

Query presets

Key-value store

Assemble an app

Configure inference

Register workers

Add endpoints

Run plugins

Run initialization steps

Follow startup