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:
- 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. - Source maps. When the bundler plugin is installed, a minified frame is resolved and the
result is reported as a guard (
resolved,unresolved, ornot_applicable). - First real event. The installer waits for a non-synthetic event (
--verify-timeout,--no-verifyskips it). You trigger it from the app. - 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-verifychecks the claim offline. It is an extension-kind claim, so a verifier that does not know the kind reports itUNVERIFIED_BY_THIS_VERSIONand no tier accepts it.sdk_inventory_getwithinclude: ["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.