Local development

Locally, you want tracing with zero infrastructure. The simplest setup uses the SQLite adapter with a file — no database server, no migration commands.

Embedded in your app

Point database at a SQLite file in development. The schema is created on first use, so there is nothing to run before starting your app.

import { sqlite, postgres } from "@breadcrumb-sh/core/adapters";

export const bc = breadcrumb({
  database: process.env.DATABASE_URL
    ? postgres(process.env.DATABASE_URL)
    : sqlite(".breadcrumb/dev.db"),
  basePath: "/api/breadcrumb",
});

Run your app and open the route you mounted the dashboard at. There is no separate dev server: the dashboard is a component in your app, so it runs under your dev server with your hot reload, the same code you ship.

Only the database swaps between local and deployed. The mount, the auth, and the dashboard route stay identical, so there’s no setup that exists only in development and can rot without you noticing.

Debugging with your agent

Open the MCP tab in the dashboard and create a key to let your coding agent query these traces while you work. A local instance names itself breadcrumb-local, so you can keep it connected alongside a deployed one without the two colliding. See MCP.

Next steps

• Instrumenting: send traces from your code.
• MCP: let your coding agent read the traces you just captured.
• Production: move from SQLite to Postgres and deploy.