# 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:

```bash
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](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](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](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](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](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](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](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](evaluating-without-migrating.md).

---

## 1. The human path — `create-bucker`

```bash
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.

```bash
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`](llms.txt) — one screen: what the product is, where the machine-readable
  surfaces are, and the trust rules that govern telemetry strings.
- [`AGENTS.md`](AGENTS.md) — instructions that live in the customer's repo, so future
  agent sessions inherit them.
- [`skills/bucker-install.md`](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:

```bash
npx create-bucker --emit-agent-docs
```

### The skill pack

Six versioned skills live in [`skills/`](skills/), each in the agent-skill format
(front matter `name`, `description`, `version`, then numbered steps), with a
[`manifest.json`](skills/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:

```bash
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:

```jsonc
{
  "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](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.
