Skip to content
Botscent

Cloudflare Workers

Add the server half of Botscent to a Cloudflare Worker and check the install.

Add the server half of Botscent to a Cloudflare Worker. The server half wraps the Worker's fetch handler. The handler gets the request's own verdict as a fourth argument. For the page half, see A script tag, React, Vue or the page for the framework your site uses.

If your Worker uses Hono, follow Hono instead.

Before you start

You need:

  • A Cloudflare Worker with a fetch handler
  • Node.js 22.12 or later, to install the package

1. Install the package

Install botscent from npm.

Terminal
npm install botscent

With pnpm, yarn or bun, use their add command.

2. Add the server half

In src/index.ts, wrap the fetch handler with withBotscent.

src/index.ts
import { withBotscent } from 'botscent/workers'

export default {
  fetch: withBotscent(async (request) => fetch(request)),
}

The adapter now inspects each request before your handler runs.

The adapter also reads Cloudflare's request.cf, so the platform's verified-bot field counts as evidence.

A Worker runs per request in front of the cache, so the transport is on by default. For an agent's document navigation, the adapter adds a Server-Timing entry with Cache-Control: no-store. The page half reads the entry.

Behind Workers Cache, a cached page carries no entry. For the details, see From the server to the page.

If the Worker stores HTML with the Cache API, set transport: 'never':

src/index.ts
import { withBotscent } from 'botscent/workers'

export default {
  fetch: withBotscent(async (request) => fetch(request), { transport: 'never' }),
}

The adapter then sends no entry to the page.

3. Add the page half

The server half reads only what each request declares. The page half finds agents that operate a browser, from inside the page.

If the Worker sends your HTML, add <script defer src="/botscent.js"></script> to each page. Serve node_modules/botscent/dist/botscent.js at /botscent.js from your own origin. If a frontend framework renders your pages, add the page half there instead. The Quickstart lists every framework.

4. Read the verdict

In the handler, read the fourth argument.

src/index.ts
import { withBotscent } from 'botscent/workers'

export default {
  fetch: withBotscent(async (request, _env, _ctx, verdict) => {
    if (new URL(request.url).pathname === '/verdict') return Response.json(verdict)
    return fetch(request)
  }),
}

A request from curl to /verdict gets {"type":"agent","agent_name":"curl","reasons":["ua.declared-agent-token"]}.

To give an agent access, use isVerified from botscent/server on this verdict. Use no other field for access. See The trust model.

5. Check the install

Deploy the Worker. Then run the check against one of its pages.

Terminal
npx botscent check https://your-site.example/

The server-half and page-script checks print pass, and the check exits with code 0. If Workers Cache answered the check's request, server-half prints unknown. Run the check again after the cached copy expires. If a check fails, see Verify your install.

Next steps