Not installable yet. This page describes the install path of the first build as designed. The packages botrampart, @botrampart/node and @botrampart/browser and the container images are not published. The target for this whole page is under 15 minutes from init to first data; that is a goal, not a measurement.
What you need
- A Node app on Express, Fastify or Next.js. Python and Java SDKs are planned after the first build.
- Somewhere to run Core: a Cloudflare account (Workers Paid starts at $5 a month1) or any host that runs one container. Target footprint: 256 MB of memory, no database server.
- An S3-compatible bucket: Cloudflare R2, Amazon S3, or MinIO, which the generator can bundle.
- Optional: a key for a decision-model provider, or a self-hosted model. Without one, the five-minute loop is off and everything else works.
-
Generate the install
The generator asks four questions and writes plain files you can read and commit. It generates your site keys locally and sends them nowhere.
$ npx botrampart init ? Where will Core run? Cloudflare | Docker on a Linux host | Kubernetes ? Object storage? R2 | S3 | MinIO (bundled) ? Where are access logs? nginx | ingress-nginx | ALB | none yet ? App framework? Express | Fastify | Next.js ✓ wrote docker-compose.yml, botrampart.policy.yaml ✓ generated site keys into ./secrets (never sent anywhere) Next: add two lines to your app and one script tag. Then run `br doctor`.On Cloudflare it writes a Wrangler configuration and a deploy button instead of a compose file. Kubernetes gets plain manifests.
-
Start Core
# docker-compose.yml, as generated (abridged) services: core: image: ghcr.io/botrampart/core:1 ports: ["8787:8787"] environment: BR_LAKE_URL: s3://acme-botrampart/br/v1/ BR_DECISION_PROVIDER: off # or gemini, openai, a self-hosted model secrets: [br_keys, lake_writer]$ docker compose up -d core -
Add the backend SDK, in observe mode
Mount the SDK at the root of your app so every route gets a path class by default. In
observemode it decides every request and logs the decision, but lets everything through.server.js · Node, ExpresssyncInstance
import express from "express"; import { botrampart } from "@botrampart/node"; const app = express(); const br = botrampart({ site: "site_123", secretsFile: "./secrets/br_keys", core: "http://localhost:8787", // counters sync here every 5 to 10 seconds mode: "observe", // decide and log, enforce nothing }); app.use(br.express()); // mounts /_br/*, verifies, charges, sets req.br -
Add the browser SDK
One script tag, served from your own origin by the backend SDK, so no third-party domain can change the code your visitors run. That is the lesson of the 2024 Polyfill.io incident, when a CDN script under new ownership served malware to more than 100,000 sites.2
Your page templategetSdkScript
<script src="/_br/sdk.js" data-site="site_123" async></script> -
Check the install
Terminal · checks Core, the script route and the lakegetSdkScript
$ npx br doctor ✓ Core reachable, policy v1 synced to 1 instance ✓ /_br/sdk.js served from your origin ✓ lake writable: s3://acme-botrampart/br/v1/ ! 3 paths in recent responses carry no BotRampart header: /healthz, /legacy/export, /feed.xmlOpen your site and ask the SDK what the browser holds. A first visit is tier 0; a moment later the proof-of-work has run in the background and the session is tier 1.
In the browser, from your own origingetSessionStatus
await fetch("/_br/status").then((r) => r.json()); // { "tier": 1, "expiresAt": 1794825300, "sessionEndsAt": 1795428300, "tierExpiresAt": {}, "identified": false } -
Watch for an hour
Within the first hour the decision log in your bucket shows spend by path class, the sessions that would have been challenged and why, and path costs suggested from how long each path takes to answer. Try a draft policy against that traffic before you enforce anything:
Replay a draft against the last 24 hourssimulatePolicy
curl -X POST "http://localhost:8787/v1/policy/simulate" \ -H "Authorization: Bearer $BR_CONSOLE_TOKEN" -H "Content-Type: application/json" \ -d @draft-policy.json { "challenged_share_current": 0.004, "challenged_share_draft": 0.012, "signed_in_affected": 0, "summary": "Would have challenged 1.2% of sessions against 0.4% today, none of them signed in." } -
Enforce tier 1
Switch
modeto"enforce"with the default policy. Ordinary browsing stays inside the refill rate and sees nothing. Clients that cannot run JavaScript keep reading general pages on their 30-unit allowance and are asked for a proof-of-work on costly paths. Keep the five-minute loop in shadow until its answers match what you would have done.
Where to go next
Guide
Integration
Route costs, sign-in, GraphQL, challenge handling, fail modes and the policy file.
Reference
Architecture
Components, data layout, the decision model contract and the threat model.
Sources
Every figure from someone else on this page, with the words it rests on. Checked on the date shown; the full ledger is claims.yaml.
- Cloudflare docs: Workers pricing.
minimum charge of $5 USD per month for an account
Checked 2026-11-18. - Sansec: Polyfill supply chain attack hits 100K+ sites.
The new Chinese owner of the popular Polyfill JS project injects malware into more than 100 thousand sites.
Checked 2026-11-18.