Skip to content
bucker

Installing Bucker with a coding agent

A coding agent can install the SDK for you, and you can read exactly what it intends to do before it does anything. This page is the contract: what the agent runs, what it is told, what it is never shown, and how the install proves itself.

1. Check the skill before you trust it

The agent's instructions are the bucker-install skill, served by the MCP tool get_bucker_skills and written to docs/skills/ by create-bucker --skills. An agent edits your repository on its say-so, so the pack must be the one Bucker released.

bucker-verify skill ./skills --key ./bucker-skills.pub

The pack is a manifest.json listing each skill with its SHA-256, a packDigest over those lines, and an ed25519 signature over packDigest. The check is offline and refuses (exit 2) a pack whose manifest or any skill's digest was altered. The key is the one you obtained out of band from the release: a key found inside the pack is only the pack's claim about itself and is never trusted. A signed pack checked with no --key, and an unsigned pack without --allow-unsigned, exit 7 ("nothing was checked") rather than pass.

2. Ask for the plan

npx create-bucker --json --dry-run

Standard output carries exactly one JSON document, schema create-bucker-plan/1, and nothing else (progress and the package manager's output go to standard error). It lists the detected framework, the steps, the files to be created or edited with a bounded diff each, the guards that applied (for example a Sentry SDK already present, or the source-map check), and a plan.digest: a SHA-256 over what will happen. The plan is deterministic. The real run that follows prints the same plan, so a person who confirmed the dry run has confirmed the run.

The DSN is a credential, so it is reported as { "variable": "BUCKER_DSN", "fingerprint": "<8 hex>" } and never as a value. The installer writes the value into the env file itself, under the same never-overwrite rule as before: an existing key with a different value is left alone and reported. --json never prompts; an edit to your own code that was not confirmed with --yes is declined and says so.

3. Run it

npx create-bucker --json --yes --org <org> --project <project>

The run then proves the install, in order:

  1. Test envelope. A synthetic envelope (BuckerTestEvent) goes to the ingest door the DSN names. A 2xx says the DSN authenticates and the door accepts. It proves nothing about your SDK, and the server never counts it as the app's first event.
  2. Source maps. When the bundler plugin is installed, a minified frame is resolved and the result is reported as a guard (resolved, unresolved, or not_applicable).
  3. First real event. The installer waits for a non-synthetic event (--verify-timeout, --no-verify skips it). You trigger it from the app.
  4. Receipt. The installer reports the plan digest, the SDK versions it read from disk, the framework and the DSN fingerprint to POST /orgs/:org/projects/:project/install/verify.

4. The receipt

The server checks that the fingerprint belongs to an active key of that project and that a real event has arrived (409 no_real_event otherwise), then signs an install_verified claim into the organization's receipt log. It records the plan digest, framework, SDK versions, the fingerprint, whether source maps were checked and when the first real event arrived. It records no path, no repository name and no person.

  • The project comes from the URL and the caller's permission on it, never from the body, and the body schema refuses an unknown field. Another organization's project is "not found".
  • The same plan digest reported twice returns the claim already filed. A second install of the same project is a different plan and files a new claim (reissued: true); the old one is never rewritten.
  • bucker-verify checks the claim offline. It is an extension-kind claim, so a verifier that does not know the kind reports it UNVERIFIED_BY_THIS_VERSION and no tier accepts it.
  • sdk_inventory_get with include: ["setup"] shows the project's newest receipt.

There is no MCP tool that files a receipt: it is filed by the installer a person ran with their own token.

What an agent must never do

  • Print, log, paste or commit the DSN or any bkr_ / bpat_ token. The installer redacts both from every output path; do not work around it.
  • Merge, approve or deploy on the strength of an install. A receipt says the pipeline works.