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 (Settings → Projects and DSNs) or from the API:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.bucker.io/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.

Already run a Sentry SDK? An unmodified Sentry SDK pointed at your Bucker DSN reports errors here with no new package: switch-from-sentry.md has the one-line change per language and a plain table of what does and does not carry over yet.

Your language

Bucker ships its own SDKs for JavaScript (browser, Node.js, edge runtimes and the framework entry points in sdk-frameworks.md), Python and Flutter. Every other language reports through one of two paths that need nothing of ours installed, and each entry below says which and how far it has been checked:

Language Path Status
JavaScript, TypeScript @bucker/browser, @bucker/node, @bucker/sdk-core/edge Bucker SDK
Python bucker-sdk Bucker SDK
JavaScript or Python, already on Sentry the Sentry SDK, DSN swapped Certified at the versions in sentry-compat.md
Go sentry-go, DSN swapped — or OpenTelemetry via OTLP Grammar-compatible, not certified
Ruby sentry-ruby, DSN swapped — or OpenTelemetry via OTLP Grammar-compatible, not certified
PHP sentry/sentry, DSN swapped — or OpenTelemetry via OTLP Grammar-compatible, not certified
Java, Kotlin io.sentry:sentry, DSN swapped — or OpenTelemetry via OTLP Grammar-compatible, not certified
.NET Sentry (NuGet), DSN swapped — or OpenTelemetry via OTLP Grammar-compatible, not certified
Anything else the Sentry SDK for it, or any OpenTelemetry exporter (otlp.md) Grammar-compatible, not certified

Certified means a pinned release of that SDK runs, unmodified, in the conformance suite and the rows it leaves are checked cell by cell. Grammar-compatible, not certified means the SDK speaks the envelope format Bucker accepts, but no release of it runs in that suite — so errors are expected to land, and the project's drops panel is where to look if one does not. The setup screen (Set up project) has the four steps for each, with your DSN in them; platforms.md is the same list as a page.

For traces, logs and metrics from any of these languages, OpenTelemetry is the path: an unmodified exporter with three environment variables (otlp.md). A first-party SDK for one of them is reopened only where a Bucker feature needs code inside the process — state slices and GenAI capture today — not to repeat what the Sentry SDK already sends.

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.

Without a DSN: log in, or pass a token

You do not have to create the project in the browser first.

npx create-bucker                                   # at a terminal: log in with a device code
BUCKER_TOKEN=bkr_pat_… npx create-bucker --yes      # an agent or CI: a token in the environment
npx create-bucker --token "$BUCKER_TOKEN" --org acme --project checkout --yes

With a token (--token or BUCKER_TOKEN) the wizard lists the organizations the token reaches (--org picks one), lists that org's projects (--project picks one), creates a project when the org has none — named after package.json's name, or pass --create-project "<name>" — fetches the project's DSN, installs exactly as with --dsn, and then polls the first-event diagnosis until the first event lands, for up to --verify-timeout seconds (120 by default; --no-verify skips the wait). Each change of verdict (auth_failed, rejected, accepted_unsupported_items, …) is printed as it happens, and the onboarding test event alone does not count as this install's event. A timeout exits non-zero and prints the verdict and the four stages. A project that already had events is said to be so, rather than reported as verified by this install. Several orgs or projects and no flag: at a terminal it asks, anywhere else it stops and lists the slugs.

The token is never written anywhere — not to .env, not to a generated file, not to the terminal. Only the DSN is written, through the same env-file path as --dsn.

What the token needs, and which routes the wizard calls:

Step Route Scope
List organizations GET /orgs any valid token (a pinned token lists its one org)
List projects GET /orgs/:org/projects project:read
Create a project (only when needed) POST /orgs/:org/projects org:write — ADMIN or OWNER
Fetch the DSN GET /orgs/:org/projects/:project/keys project:read
Wait for the first event GET /orgs/:org/projects/:project/onboarding and …/onboarding/diagnosis project:read

A personal access token (Settings → Tokens) with project:read installs into an existing project; add org:write to let it create one. An org CI token is used the same way.

No token, at a terminal (or anywhere with --login): the wizard runs the OAuth device authorization grant (RFC 8628). It prints a URL and a short code; open the URL, enter the code, and pick the organization on the approval page. It never opens a browser itself. The access token it receives is scoped org:read org:write project:read (the server narrows that to your role), pinned to the organization you picked, held in memory for this one run, and never saved — there is no refresh token on disk and no login to clear afterwards. Without a token, a DSN or a terminal, the wizard stops and says so rather than waiting for an approval nobody was shown.

A dirty working tree is warned about before the first write. If git status --porcelain reports changes, the wizard lists them and asks before writing (a non-TTY declines); --yes proceeds with the warning. A directory that is not a git repository skips the check.

Flags

Flag Effect
--dsn <dsn> The project DSN. Not needed with a token, a device login, or agent docs alone
--token <token> Fetch the DSN with this token (or set BUCKER_TOKEN). Never written to disk
--api-url <url> Control plane, default https://api.bucker.io (or set BUCKER_API_URL)
--org <slug> / --project <slug> Pick when the token reaches several
--create-project <name> Create a project and install into it
--login Run the device login even without a TTY
--verify-timeout <secs> / --no-verify How long to wait for the first event (120), or not at all
--dry-run Prints the full plan and writes nothing at all
--yes, -y Accepts every change, including edits to files you wrote, and writing into a dirty git tree
--dir <path> Target a directory other than the current one
--framework <name> Override detection: nextjs, express, fastify, node, browser, sveltekit, nuxt, remix, django, flask, fastapi
--ignore-sentry Install the Bucker SDK even where a Sentry SDK is set up (default: point SENTRY_DSN at Bucker instead)
--uninstall Remove every file the wizard wrote, the line it injected, its AGENTS.md section and its DSN keys, each as a diff (with --dry-run: show only)
--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, .bucker/install.md and .mcp.json into the repo
--skills Also copy the Bucker agent skills into .claude/skills/<name>/SKILL.md
--plugin Also write a Claude Code plugin (skills + .mcp.json) and a local marketplace under .bucker/

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

The skill pack

Six versioned skills live in skills/, each in the agent-skill format (front matter name, description, version, then numbered steps), with a manifest.json carrying a sha256 per file and one pack digest:

Skill For
bucker-install Wiring the SDK and verifying the first event
bucker-debug-issue The essence-first loop: essence → hydrate only what is missing → RCA → claim → repro → patch
bucker-sourcemaps Debug-ID source maps from a Vite/Rollup build, and proving they resolve
bucker-switch-from-sentry Evaluating read-only, swapping the DSN, or replacing a Sentry SDK
bucker-finding-sessions What people did in the browser with no issue to start from: filter, count, then read one session
bucker-alerting Writing alert rules as an agent: a rule starts in shadow, you ask for promotion with the evidence, a person decides
bucker-cli-approvals Governed changes from the bucker CLI: exit code 3 means a person must decide, wait for them, then spend the approval once on the same plan

The MCP server serves the same bytes as prompts (prompts/list, prompts/get), as resources (resources/list, resources/read, starting at bucker://skills/manifest.json) and through the get_bucker_skills tool. To keep them in the repository:

npx create-bucker --emit-agent-docs --skills    # + .claude/skills/<name>/SKILL.md
npx create-bucker --plugin                      # a Claude Code plugin under .bucker/

Then, in Claude Code, /plugin marketplace add ./.bucker and /plugin install bucker@bucker. The plugin's .mcp.json, like the project one, references ${BUCKER_ACCESS_TOKEN} and never contains a token.

pnpm check:skill-pack (from code/) verifies the digests, the signature when there is one, and that every MCP tool name and create-bucker flag a skill mentions exists.

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 is true once a source-map / Debug-ID artifact has been uploaded for the project, and hasRepoConnected once the project or its organization has an active repository connection — one whose consent has not been revoked and which has not been disconnected. Both are read from the stored rows on every request (domain/src/modules/onboarding/service.ts), so a revoked connection turns the tick back off rather than leaving a green item the customer deliberately undid.

The first week in one read

After the first event, the question changes from "did it land?" to "what can Bucker still not see?". The setup screen's First week panel answers it with one cell per pillar — errors, source maps, the first event, capture per signal (traces, logs, sessions), ingest loss, hosts, collectors, replay, consent, web vitals, AI calls, databases, alert rules, uptime checks, analytics trust, spend, status pages, approvers, the Slack app and outbound mail. The same cells are GET /orgs/<org>/projects/<project>/setup-cells, and an agent reads them with list_projects and include: ["setup"] (name the project with org and project; the block adds at most 900 tokens and nothing is added to a call that does not ask for it).

Each cell has a state from a closed list: live, lossy (arriving, with a named defect), silent (it arrived and stopped), missing (it never arrived), unknown (Bucker cannot tell, or the check is not built yet — it says which card builds it and is never a pass) and not_applicable. It also carries the time of its last evidence, an evidence handle, the next step (a tool name, or a human act by name) and the read that holds the detail.

Nothing is stored as "done": every cell is the stored result of its own area, derived on each read, so a gap closes when its signal arrives. A cell whose read needs a scope your credential lacks (spend needs cost:read) is named in omitted with the scope rather than left out silently. Two cells are about the people, not the telemetry: approvers says whether, for each action that asks a person by default, someone other than the requester could approve it on this project (a lone owner is a lossy sole approver), and mail says whether the deployment can send email at all.

If nothing arrives

Start with what the setup screen already says. While it waits it shows a live diagnosis — reached us · authenticated · accepted · grouped — computed on the server from every outcome ingest recorded and every DSN-auth refusal addressed to your project while the screen is open. The same document is GET /orgs/<org>/projects/<project>/onboarding/diagnosis for a script or a CLI. Its verdict is one of:

Verdict What it means What to do
waiting Nothing addressed to this project has reached us yet. Run the code that calls init.
nothing_reached_us A minute in, still nothing at all. The SDK has not run, or cannot egress. The screen also checks whether your browser can reach the ingest host; if that is blocked too, it is the network.
auth_failed Something reached us with a key we do not accept — unknown, disabled, from another project, or missing. Copy the DSN again, whole. The screen shows the first characters of a key that does not exist, never a full key.
rejected It authenticated and we refused it: too large, malformed, or over quota. The reason is on the screen.
accepted_not_grouped Accepted; the worker has not written the issue yet. Wait a moment — or start the worker (below).
accepted_unsupported_items An SDK reached us but sent only items that do not become issues yet (transactions, spans, sessions). Throw an error to see one. Common with a Sentry SDK configured for tracing only.
received The first issue exists. Open it.

The test event. "Send a test event" on the setup screen pushes one synthetic error through the real ingest path, so received can mean "the pipeline works" before your SDK has run. It is never sent unless you press the button, and it is marked as what it is: the event carries bucker.synthetic=true (and bucker.test_event=true), its issue is titled BuckerTestEvent, and the diagnosis reports it as firstIssue.synthetic: true while it is the only issue — a script waiting on received should wait for synthetic: false if it means "my SDK reported". The test issue then gets out of the way by itself: when the first real event opens an issue in the project, the worker resolves the test issue, with an activity entry saying a real event superseded it. If you sent a test event into a project that already had issues, the setup screen offers Resolve the test issue instead (the diagnosis's testIssue.open says whether it is still open). Sending another test event later reopens it as a regression.

The auth half is remembered in memory on the api process for projects someone is watching, and never stored: no row, no IP address, no full key. With more than one api machine the screen may not see every refusal, says so, and then never claims that nothing reached us.

If the diagnosis does not settle it, the short list is below; troubleshooting.md is the full version, organized by the same verdict names:

  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.