Install

The server part

@parlox/server reports the AI fetchers and crawlers that never run JavaScript, on any stack.

AI fetchers and crawlers (ChatGPT's and Claude's page readers, Perplexity, Google's agents, training crawlers) never run JavaScript, so only your server sees them. The server part reports them to Parlox and answers the ownership check. It is optional: without it Parlox still sees people and browser agents.

Terminal
npm install @parlox/server

@parlox/server has no runtime dependencies and runs on Node 20 and later, edge runtimes, Cloudflare Workers, Deno and Bun. The source is public: github.com/parlox-io/parlox-js (MIT).

What it sends

For each GET or HEAD request for a page (not a static asset) that looks automated, it sends one small report in the background, never delaying the response. (The Next.js and Vercel middleware report as the request arrives, before your page answers, so their reports carry no status.) A request looks automated when its user agent names a bot, a crawler, an AI fetcher, an HTTP library or a headless browser, when it sends no user agent, or when it lacks headers every browser sends (Sec-Fetch-Mode, Accept-Language). Requests from people are filtered out on your server and never sent.

A report holds the path, method, status, user agent, a few request headers, and a one-way hash of the client address and the day that groups one crawler's requests into a visit. Pages, robots.txt, llms.txt, sitemaps and JSON are reported; images, stylesheets, scripts and fonts are not, and neither are requests under /api/ unless you pass includeApi: true.

Reports never delay or fail a response, and never throw. Pass onError to see failures.

The variables

.env
# A "Crawler reports only" key
PARLOX_SECRET_KEY=sk_parlox_…
# Optional: answers the ownership check
PARLOX_VERIFY_TOKEN=…
# Optional: the header your own proxy sets with the client address
PARLOX_IP_HEADER=x-real-ip

PARLOX_SECRET_KEY holds a key with access "Crawler reports only", the kind a new site gets and the install wizard creates. That is all the server part needs. Keep it on the server only: never in browser code, in git, or under a name your frontend build exposes (VITE_…, NEXT_PUBLIC_…). Orders use a key of their own.

Which one fits your setup

The server part runs in whatever produces your pages' HTML, because that is where fetchers arrive.

What serves your pagesServer part
A Node or edge server (Next.js, Express, Hono, Remix, SvelteKit, Astro), behind nginx or not@parlox/server, one line (below)
Another app server that renders the pages (PHP, Python, Ruby, Go, Java, .NET)The HTTP call, from that server
nginx (or any web server) serving the built files of a single-page appNone for the pages. See what a static site cannot see
A static hostNone, except on Vercel (below)

Orders are separate: whatever confirms a payment on your side, Node or not, can post the order.

Next.js

In middleware.ts at the project root (or in src/ when the app uses one), or proxy.ts in Next.js 16:

middleware.ts
import { withParlox } from "@parlox/server/next";

export default withParlox(); // or withParlox(yourExistingMiddleware): its result is returned unchanged

export const config = {
  // Pages, robots.txt, llms.txt, sitemaps and the ownership check; not static assets or API routes.
  matcher: ["/((?!_next/static|_next/image|api/|favicon.ico|.*\\.(?:png|jpe?g|gif|svg|webp|avif|ico|css|js|map|woff2?)$).*)"],
};

Wrapping an existing middleware? Keep your own matcher: it decides where your middleware runs, and Parlox reports what it sees. To report agents that call your API, include /api/ in the matcher and pass includeApi: true.

Express

Right after const app = express(), before your routes. Any Connect-style server works the same way.

server.js
import { parlox } from "@parlox/server/express"; // CommonJS: const { parlox } = require("@parlox/server/express");

app.use(parlox());

Put it in your source file, never in compiled output (dist/, build/), which the next build would replace. Pages your app renders (EJS, Handlebars, Pug and other view engines) or serves as static .html get the pinned tag as the first element of their <head>. An API with no pages needs no tag: the browser part belongs in your frontend.

If your app already posts to https://gateway.parlox.io/v1/s with code of its own, do not add the middleware as well, or each crawler visit is counted twice.

Hono

On Node, Bun, Cloudflare Workers and Pages, Vercel and AWS Lambda, right after the app is created, before your routes:

src/index.ts
import { Hono } from "hono";
import { parlox } from "@parlox/server/hono";

const app = new Hono();
app.use(parlox());

The adapter reads PARLOX_SECRET_KEY, PARLOX_VERIFY_TOKEN and PARLOX_IP_HEADER from c.env first (Cloudflare's bindings), then from process.env.

  • Cloudflare Workers: add PARLOX_SECRET_KEY as a runtime secret (Settings → Variables & Secrets, or wrangler secret put), not as a build variable.
  • Cloudflare Pages: its dashboard variables apply at runtime and at build time, so make sure no build step can put the key into browser code (below).
  • basePath(): an app mounted under a base path does not see /.well-known/parlox-verify. Prove ownership with the DNS record or the tag.
  • AWS Lambda: the report starts only after an asynchronous hash, so after your handler has returned. It usually goes out during the instance's next invocation, and is lost if the instance is frozen and then recycled.

A page layout (a JSX <head> in jsxRenderer, or an html template) gets the pinned tag as the first element of its <head>.

A static site on Vercel

A static site (a Vite React build, for example) has no server of its own. On Vercel, Routing Middleware fills that role. Add middleware.ts next to package.json:

Terminal
npm install @parlox/server @vercel/functions
middleware.ts
import { next } from "@vercel/functions";
import { withParlox } from "@parlox/server/vercel";

export default withParlox({ next }); // or withParlox(yourMiddleware, { next })

export const config = {
  matcher: ["/((?!assets/|_vercel/|favicon\\.ico|.*\\.(?:png|jpe?g|gif|svg|webp|avif|ico|css|js|map|woff2?)$).*)"],
};

The matcher keeps the middleware off static assets and Vercel's own /_vercel/ paths. Vercel prices Routing Middleware as compute.

On any other static host (Netlify, Cloudflare Pages, GitHub Pages, S3) there is no server part. Add only the browser part, and prove ownership with a file public/.well-known/parlox-verify holding your verification token. GitHub Pages built with Jekyll leaves out folders whose names start with a dot, so use the DNS record there.

Remix, SvelteKit, Astro, Deno

For any server built on the Web-standard Request and Response:

TypeScript
import { parloxFetch } from "@parlox/server/fetch";

const parlox = parloxFetch();

// Before your handler: the ownership check.
const early = parlox.handle(request);
if (early) return early;

// After it, with the platform's waitUntil when it has one:
parlox.observe(request, response.status, waitUntil);

Without waitUntil (Node or Bun), reports wait in the batching queue described below.

Any other stack: the HTTP call

PHP, Python, Ruby, Go and other stacks send the same report with one HTTP call. For each GET or HEAD request that:

  • is not for a static asset: its path does not end in .png, .jpg, .jpeg, .gif, .svg, .webp, .avif, .ico, .css, .js, .mjs, .map, .woff, .woff2, .ttf, .otf, .eot, .mp4, .webm, .mp3 or .wav (pages, robots.txt, llms.txt, sitemaps and JSON count);
  • is not under /api/, unless you want agents that call your API reported (health checks and monitors live there);
  • looks automated: the user agent matches /bot|crawl|spider|gpt|claude|anthropic|meta-|perplexity|google-agent|fetch|python|curl|wget|axios|node|http|headless|scrap/i, or the request has no User-Agent, no Sec-Fetch-Mode or no Accept-Language header;
  • and does not carry an x-parlox-audit header (Parlox's own page checker),

send this after the response:

HTTP
POST https://gateway.parlox.io/v1/s
Authorization: Bearer $PARLOX_SECRET_KEY
Content-Type: application/json

{"events":[{"path":"/products/x","method":"GET","status":200,"ua":"...","referer":null,"accept":"...","accept_language":null,"sec_fetch_mode":null,"ip_hash":"<lowercase SHA-256 hex of the client address + '|' + the UTC date YYYY-MM-DD>","ip":"<client address, only when the user agent matches the pattern above>","host":"<the Host header>","signature_agent":null,"signature_input":null,"signature":null}]}

The rules:

  • Send it in the background with a two-second timeout. Never block or fail the page on it.
  • Up to 100 events per request; events after the first 100 are ignored.
  • Take ip only from the connection or from a header your own proxy sets, never from X-Forwarded-For as the client sent it, and do not change your app's proxy-trust settings for Parlox. Send it only when the user agent matches the pattern: a request reported only because a header is missing gets "ip": null. Hash the address your server sees for ip_hash even when you do not send ip.
  • The three signature* fields are the request's Web Bot Auth headers (Signature-Agent, Signature-Input, Signature), copied as they are, when present.
  • If you use that proof, answer GET /.well-known/parlox-verify with your verification token.

Orders over HTTP use the same endpoint with a different key: Purchases from the server.

The client address

For a request whose user agent names a bot, the server part sends the client's address so Parlox can check the claim against the vendor's published address ranges. The address is judged in memory and discarded, never stored (How a visitor is identified).

It is read only from a header that a proxy you control sets:

  • on Vercel, x-real-ip, automatically;
  • behind Cloudflare, cf-connecting-ip (the Hono and fetch adapters read it by default for a request Cloudflare's own network delivered);
  • elsewhere, the header you name in PARLOX_IP_HEADER (behind nginx, x-real-ip: Behind nginx).

Without one, no address is sent, and visits are still grouped by a hash computed on your server. Do not change your framework's proxy-trust settings for Parlox.

Behind nginx

When nginx proxies to your app server, the app sees nginx's address, not the client's. Have nginx pass the client's address and the original host, and tell the server part which header to read:

nginx.conf
location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
}
.env
PARLOX_IP_HEADER=x-real-ip
  • X-Real-IP carries the client's address, which Parlox checks against the vendors' published ranges for a request whose user agent names a bot, then discards. Without it, those visits stay declared, unless the request is signed.
  • Host $host passes the host the client asked for (nginx sends the upstream's own address by default). Signed requests are checked against it: Signed requests.
  • If nginx itself sits behind a CDN, $remote_addr is the CDN's address. Use the CDN's client header instead (Cloudflare's is cf-connecting-ip), or nginx's real-IP module configured for that CDN.

Never point PARLOX_IP_HEADER at a header the client can set, such as X-Forwarded-For as it arrives.

What a static site cannot see

When nginx (or a static host) serves the built files of your app, no Parlox code runs where the pages are requested. Then:

Seen
People, and browser agents (they run your JavaScript)Yes, by the browser part
People sent by AI assistantsYes, by the browser part
Cart and checkout steps from your GA4 data layerYes, by the browser part
OrdersYes, when your backend posts them
Assistants' fetchers reading your pages (ChatGPT-User, Claude-User, Perplexity-User)No
Search and AI crawlers (OAI-SearchBot, PerplexityBot, GPTBot, Googlebot), and their reads of robots.txt, llms.txt and sitemapsNo

Fetchers and crawlers never run JavaScript, so only the server that answers them can report them, and Parlox has no nginx module. To see them, put the pages behind a server that runs the server part, or move them to a host whose middleware can (Vercel).

A backend that serves only your API, behind the same nginx, does not change this: fetchers read your pages, which nginx serves. That backend can still post your orders.

Prove ownership with the DNS record: a common nginx rule, location ~ /\. { deny all; }, refuses every path that starts with a dot, /.well-known/parlox-verify included.

How reports travel

  • Where the platform keeps work alive after a response (Next.js middleware, Vercel, Cloudflare Workers and Pages), each report is sent at once through waitUntil, with a two-second limit.
  • Where the platform may freeze or stop the code soon after a response (AWS Lambda, Deno Deploy, Azure Functions), each report is sent at once too, never queued.
  • In both cases, at most 64 reports are sent at once in the whole process; beyond that a report is counted instead of sent.
  • On a long-running server (Express, Hono on Node or Bun), reports wait in a queue and go in batches: at 20 reports or every 10 seconds, at most 100 reports and 200,000 bytes per request, one request at a time, with a ten-second limit. At most 1,000 wait; when the queue is full, the oldest is dropped and counted.

A batch is sent again only when Parlox provably stored none of it: it answered 429, or the connection never reached it. Any other failure is not retried, so no report is stored twice. Reports dropped, or whose delivery was not confirmed, are counted, and the count travels with the next request. The dashboard's Install status then reads "could not confirm delivery of N reports".

Shutdown

On a long-running server, send what is queued before the process stops on a signal. The package installs no signal handlers of its own:

JavaScript
import { parlox } from "@parlox/server/express"; // or "@parlox/server/hono"

process.on("SIGTERM", async () => {
  await parlox.flush();
  process.exit(0);
});

If your app already handles the signal, add await parlox.flush() there, before it exits. flush() waits at most 30 seconds (parlox.flush(ms) sets another limit); give it less than your platform's grace period. Elsewhere, import { flush } from "@parlox/server".

Parlox's own checks

Parlox's page checker fetches your pages with a real browser's user agent and the real user agents of ChatGPT, Claude and Meta AI, and marks each request with an x-parlox-audit header. @parlox/server skips those requests, so checks are never counted as agent visits. Code of your own that reports requests should skip them too. Parlox's other checks (the ownership check, the UCP check) use user agents of their own, and the gateway drops their reports whatever your code does.

Every option: Server API.