Skip to content
bucker

Getting started

Target: a first error visible in Bucker in under five minutes, whether a person or a coding agent does the work.

0. What you need

A project DSN. It looks like:

https://<publicKey>@<region>.<ingestHost>/<projectId>

Get one from the dashboard (project → Client Keys) or from the API:

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:4000/orgs/<orgSlug>/projects/<projectSlug>/keys

Each key in the response carries a dsn field. The DSN is derived from the key at read time, never stored, so changing the ingest host or region propagates without a data migration. See dsn-and-regions.md.

Not ready to install anything? You can point Bucker at the error stream you already have — read-only, no SDK change, incumbent tool untouched — and evaluate it against your own errors first: evaluating-without-migrating.md.

1. The human path — create-bucker

npx create-bucker --dsn "https://<publicKey>@us.ingest.example.com/<projectId>"

What it does, in order:

  1. Detects the package manager from the lockfile — bun.lock/bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm. With no lockfile it falls back to the packageManager field, then to npm.
  2. Detects the framework from package.json and config files: Next.js (dependency next or a next.config.*), Fastify, Express, a browser app (Vite, a root index.html, or a UI framework dependency), or plain Node.
  3. Installs the SDK — @bucker/browser and @bucker/node for Next.js, @bucker/node for servers, @bucker/browser for browser apps.
  4. Writes the init files for that framework (see the table below).
  5. Writes the DSN into an env file — .env.local for Next.js, .env otherwise — and adds that file to .gitignore if a .gitignore exists and does not cover it. The DSN is never inlined into a source file.
  6. Creates a verify artifact that throws on purpose, so you can confirm the first event lands without inventing a bug.
Framework Files written How you verify
Next.js (App Router) instrumentation.*, instrumentation-client.*, app/bucker-verify/page.*, app/api/bucker-verify/route.* Open /bucker-verify, request /api/bucker-verify
Next.js (Pages Router) instrumentation.*, instrumentation-client.*, pages/bucker-verify.*, pages/api/bucker-verify.* Same paths
Express / Fastify / Node bucker.server.*, bucker-verify.*, plus one import injected at the top of your entry file Run the bucker-verify script
Browser bucker.client.*, bucker-verify.html Open /bucker-verify.html and click the button

Next.js files are written beside your routes directory: at the repo root normally, or under src/ when src/app or src/pages exists.

Flags

Flag Effect
--dsn <dsn> Required (except with --emit-agent-docs alone)
--dry-run Prints the full plan and writes nothing at all
--yes, -y Accepts every change, including edits to files you wrote
--dir <path> Target a directory other than the current one
--framework <name> Override detection: nextjs, express, fastify, node, browser
--package-manager <name> Override detection: npm, yarn, pnpm, bun
--no-install Skip the dependency install step
--emit-agent-docs Also write llms.txt, AGENTS.md and .bucker/install.md into the repo

Re-running is safe

Every generated file carries a bucker:managed marker. On a re-run:

  • a file with the marker is regenerated silently — the tool owns it;
  • a file without the marker is never overwritten without printing a unified diff and asking, and --yes is what answers that question;
  • an env key that already holds a different DSN counts as a change to your data, so it also prompts;
  • if stdin is not a TTY (CI, an agent's shell) the prompt cannot be answered, so the change is declined and listed at the end rather than assumed.

--dry-run builds the identical plan and returns before the first write, so what you see in a dry run is exactly what a real run would do.

2. The agent path

A coding agent installs Bucker from three documents, no human in the loop:

  • llms.txt — one screen: what the product is, where the machine-readable surfaces are, and the trust rules that govern telemetry strings.
  • AGENTS.md — instructions that live in the customer's repo, so future agent sessions inherit them.
  • skills/bucker-install.md — a numbered checklist with exact commands, explicit STOP conditions, and a verification step the agent can check by itself.

Drop them into a repo with:

npx create-bucker --emit-agent-docs

AGENTS.md is merged, not replaced: the Bucker block is fenced by <!-- bucker:managed:start --> / <!-- bucker:managed:end --> markers and a re-run rewrites exactly that block, leaving the rest of the file alone.

3. Confirming the first event landed

GET /orgs/:orgSlug/projects/:projectSlug/onboarding

Requires the read relation on the project, like every other project route. It returns:

{
  "hasReceivedFirstEvent": true,
  "firstEventAt": "2026-08-07T10:02:11.000Z",
  "hasSourceMaps": false,
  "hasRepoConnected": false,
  "dsn": "https://<publicKey>@us.ingest.example.com/<projectId>"
}

Every field is derived from stored data, not from a flag someone remembered to set: hasReceivedFirstEvent and firstEventAt come from the oldest row in events for the project, and dsn from the project's oldest active key.

hasSourceMaps and hasRepoConnected are false until those subsystems exist. Debug-ID artifact upload and repository connections are not built yet; the endpoint probes for their tables and reports false when they are absent, so the checklist stays honest instead of failing.

If nothing arrives

  1. Confirm the env var is loaded in the running process.
  2. Confirm the DSN parses: https, a region-prefixed host, exactly one path segment, and no password half — Bucker DSNs never carry a secret.
  3. Confirm the worker is running. POST /api/<projectId>/envelope/ returning 200 means the envelope was queued; pnpm --filter @bucker/workers start is what turns it into an issue.
  4. Check quota. Over quota, ingest degrades to stratified sampling rather than dropping silently, so a verify event can be delayed but should not vanish.