BotRampart

Docs · Getting started

From nothing to your first hour of data, in observe mode.

The planned install takes one generator, one container and two lines in your app. Nothing is enforced until you choose to: the first step only watches, and shows you what it would have done.

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.
  1. 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.

  2. 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
  3. 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 observe mode 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
  4. 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>
  5. 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.xml

    Open 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 }
  6. 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." }
  7. Enforce tier 1

    Switch mode to "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

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.

  1. Cloudflare docs: Workers pricing. minimum charge of $5 USD per month for an account Checked 2026-11-18.
  2. 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.