Configuration

Chimpbase is configured through your app definition (chimpbase.app.ts) and environment variables.

App Definition

The main entry point is your chimpbase.app.ts:

import type { ChimpbaseAppDefinitionInput } from "@chimpbase/bun";

export default {
  project: { name: "my-app" },
  httpHandler: myHonoApp,
  migrations: { /* ... */ },
  registrations: [ /* actions, workers, subscriptions, crons, plugins */ ],
  worker: {
    maxAttempts: 5,
    retryDelayMs: 1000,
  },
  telemetry: {
    minLevel: "info",
    persist: { log: true, metric: true, trace: true },
  },
  workflows: {
    contractsDir: "./workflow-contracts",
  },
} satisfies ChimpbaseAppDefinitionInput;

Environment Variables

Variable	Description	Default
CHIMPBASE_STORAGE_ENGINE	Storage engine (postgres, sqlite, memory)	sqlite
CHIMPBASE_DATABASE_URL or DATABASE_URL	PostgreSQL connection URL	—
CHIMPBASE_STORAGE_PATH	SQLite file path	data/{name}.db
CHIMPBASE_WORKER_CONCURRENCY	Worker concurrency	1
CHIMPBASE_WORKER_POLL_INTERVAL_MS	Worker poll interval	250
CHIMPBASE_WORKER_LEASE_MS	Worker lease duration	30000
CHIMPBASE_ENV_FILE	Path to .env file	.env
CHIMPBASE_SECRETS_DIR	Path to secrets directory	/run/secrets

Storage Engines

PostgreSQL (recommended for production)

const chimpbase = await createChimpbase({
  storage: { engine: "postgres", url: process.env.DATABASE_URL! },
});

Supports concurrent workers, event bus coordination across instances, and is the recommended choice for production.

SQLite (development)

const chimpbase = await createChimpbase({
  storage: { engine: "sqlite" },
  // path defaults to data/{project-name}.db
});

Single-process only. Good for development and testing.

Memory (testing)

const chimpbase = await createChimpbase({
  storage: { engine: "memory" },
});

Data is lost on restart. Used for unit tests.

Runtime Hosts

Runtime	Package	Install	HTTP Server
Bun	@chimpbase/bun	bun add @chimpbase/bun	Bun.serve()
Deno	@chimpbase/deno	deno add npm:@chimpbase/deno	Deno.serve()
Node	@chimpbase/node	npm install @chimpbase/node	node:http.createServer()

All three hosts expose the same API surface: createChimpbase, loadChimpbaseApp, startChimpbaseApp, runChimpbaseAction, syncChimpbaseSchema, and syncChimpbaseWorkflowContracts. Bun ships TypeScript directly with no build step. Node automatically adapts between its callback-based HTTP API and the Web standard Request/Response that Chimpbase expects.

Bun CLI

# Run the app
bun run chimpbase.app.ts

# Execute an action
bun run chimpbase.app.ts action -- seedDemoWorkspace '[]'

# Schema management
bun run chimpbase.app.ts schema generate
bun run chimpbase.app.ts schema check

Deno CLI

Deno includes a built-in runDenoCli():

import { runDenoCli } from "@chimpbase/deno";

await runDenoCli();

Custom Entry Point

By default, chimpbase.app.ts is both your app definition and your entry point. For advanced scenarios (custom secrets loading, separate worker processes, environment-specific setup), create a separate app.ts:

import { createChimpbase } from "@chimpbase/bun";
import { loadLocalSecretStore } from "@chimpbase/tooling/secrets";
import { normalizeProjectConfig } from "@chimpbase/core";
import appDefinition from "./chimpbase.app.ts";

const secrets = await loadLocalSecretStore(
  import.meta.dir,
  normalizeProjectConfig({ secrets: { dir: "run/secrets", envFile: ".env" } }),
);

const chimpbase = await createChimpbase({
  ...appDefinition,
  projectDir: import.meta.dir,
  secrets,
  storage: { engine: "postgres", url: process.env.DATABASE_URL! },
});

await chimpbase.start();

Start Options

// Start both HTTP server and background worker (default)
chimpbase.start();

// HTTP server only (no background worker)
chimpbase.start({ serve: true, runWorker: false });

// Worker only (no HTTP server)
chimpbase.start({ serve: false, runWorker: true });