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:
- 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 thepackageManagerfield, then to npm. - Detects the framework from
package.jsonand config files: Next.js (dependencynextor anext.config.*), Fastify, Express, a browser app (Vite, a rootindex.html, or a UI framework dependency), or plain Node. - Installs the SDK —
@bucker/browserand@bucker/nodefor Next.js,@bucker/nodefor servers,@bucker/browserfor browser apps. - Writes the init files for that framework (see the table below).
- Writes the DSN into an env file —
.env.localfor Next.js,.envotherwise — and adds that file to.gitignoreif a.gitignoreexists and does not cover it. The DSN is never inlined into a source file. - 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
--yesis 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:
- Confirm the env var is loaded in the running process.
- Confirm the DSN parses:
https, a region-prefixed host, exactly one path segment, and no password half — Bucker DSNs never carry a secret. - Confirm the worker is running.
POST /api/<projectId>/envelope/returning200means the envelope was queued;pnpm --filter @bucker/workers startis what turns it into an issue. - Check quota. Over quota, ingest degrades to stratified sampling rather than dropping silently, so a verify event can be delayed but should not vanish.