Install a Cloudflare Worker mirror

What a customer_zone mirror does

A customer_zone mirror is a small Cloudflare Worker that runs on your own zone at {domain}/*. Per request it decides who is asking: AI agents (GPTBot, ClaudeBot, PerplexityBot, …) are served the NORG render of the page at your own URL — no redirect, the URL never changes — while people in a browser and search-index crawlers get your site byte-for-byte unchanged. Two rules are built in and not configurable: it must never break your site (every failure path falls back to your origin), and search engines always see exactly what humans see.

Already running your own routing Worker — for example a site that serves its home route and inner routes from different front-end stacks? See installing in front of an existing Worker.

Want to know what the Worker costs in latency? See the latency measurements.

Install without an API token

Some administrators will not issue a Cloudflare API token. The install can still proceed — in one of three ways, with a single rule for how any secret changes hands:

1. Guided screen-share. A site-owner administrator makes each change in the Cloudflare dashboard while NORG guides them through it, step by step. NORG never touches the account.
2. Read-only staging copy. NORG shares its staging account read-only, so the administrator can see the finished set-up and copy it into their own account.
3. Single-view link. Any secret — the Site Key, or a token if one is later issued — is passed as a single-view (one-time) link, never by email or chat.

A token that lacks Workers Scripts: Edit cannot deploy the Worker or create its binding, and Cloudflare has no narrower Workers scope — so a "read-only" token is never enough to install. When no token with that permission will be issued, use one of the three options above.

Site Key rotation on a token-mode install

Rotating the Site Key returns the new key once. On a token-mode (self-installed) worker the deployed worker keeps the old key and is rejected with a 401 by /api/v1/edge/* immediately. The update action does not push the new key — the NORG_SITE_KEY secret is inherited, not rewritten.

Your site is unaffected: it keeps serving its normal page (the worker fails open). Only mirror serving and the heartbeat stop, until the deployed secret matches the new key again.

Recover in one of two ways:

• Set NORG_SITE_KEY to the new value by hand in the customer's Cloudflare dashboard (Workers & Pages → the worker → Settings → Variables and Secrets), or
• Uninstall, then install again, which deploys the current key.

Confirm recovery: re-run the Site Key health probe — a JSON reply means the worker now holds the right key — then a mirror check: an AI-agent request to a mirrored page returns X-Norg-Edge: mirror again. For a NORG-hosted or Deploy-button install (no token), see hosting options, which covers key recovery for that path.

Why each permission is needed

Every grant below is exercised by the install code today — the one forward-looking exception (the write half of Bot Management: Edit) is spelled out in its own row rather than left implied. Nothing here is silent "might need it later" scoping.

Cloudflare API token permissions

Subject: Cloudflare API token for NORG edge routing (account-owned)

Please create an ACCOUNT-OWNED API token (Account Home -> Manage Account ->
API Tokens -> Create Token -> Create Custom Token -> Start from scratch).
A token from My Profile -> API Tokens will not work for this — it is capped
by the creating user's role.

Name: norg-edge-router

Permissions (two policy blocks on one token):

  Account -> <our account>
    - Workers Scripts : Edit
    - Workers Scripts : Read
    - Workers Tail    : Read

  Zone -> Specific zone -> <our-domain.com>   (NOT "All zones")
    - Zone            : Read
    - Workers Routes  : Edit
    - DNS             : Read
    - Zone Settings   : Read
    - Zone WAF        : Edit
    - Bot Management  : Edit

Optional hardening: restrict Client IP Address Filtering to NORG's egress
IPs (NORG can supply the current list) and set a TTL.

Please verify it before sharing — this must return 200, not 403:

  curl -s -o /dev/null -w "%{http_code}" \
    https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/workers/scripts \
    -H "Authorization: Bearer <TOKEN>"

Then send me the token through <your secrets channel>. I will paste it
into NORG; it is stored encrypted and never shown again.

curl -s -o /dev/null -w "%{http_code}" \
  https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/workers/scripts \
  -H "Authorization: Bearer <TOKEN>"
# 200 -> the token can reach Workers Scripts on this account
# 403 -> capped (user token) or missing grant; the install would fail

Facts for evaluating this install

Each row states one property of the install and the source that backs it — a code symbol, a repository test, or Cloudflare's own documentation.

• The API token's Workers Scripts grant is account-scoped — Cloudflare offers no per-worker or per-script variant — so the token can enumerate and modify every Worker in the account. NORG’s own calls only ever name its own script family, norg-edge-router or norg-edge-router-<id>. (source: apps/api/app/services/edge_routing/customer_zone_client.py#WORKERS_SCRIPTS_GRANT_HINT)
• The account administrator can revoke the token at any time from Manage Account → API Tokens, and rolling it invalidates the previous secret; the worker keeps serving as installed and only the update path stops. (source: Cloudflare docs)
• Changes the token makes to the account and zone — script uploads, route and variable changes — are recorded in the account Audit Log, so each change is independently reviewable. (source: Cloudflare docs)
• The install runs a preflight pass that inspects the zone and changes nothing: a conflicting foreign route aborts the install with zero mutations. (source: apps/api/tests/services/test_edge_install_service.py#test_route_conflict_aborts_with_zero_mutations)
• On every worker route NORG creates or updates (create_route, update_route), NORG sets request_limit_fail_open, so a Workers-plan daily-cap breach bypasses the worker and the origin answers the request unchanged — automatically, with no dashboard step. (source: apps/api/app/services/edge_routing/customer_zone_client.py#REQUEST_LIMIT_FAIL_OPEN)
• That coverage is limited to routes NORG creates. A route created by hand, in the dashboard or the API, defaults to fail closed (on a Cloudflare staging zone on 2026-10-26 a hand-made API route came back with request_limit_fail_open: false); past the cap such a route returns Cloudflare error 1027 unless its failure mode is set to fail open or the account is on Workers Paid. (source: Cloudflare docs)
• A zone that already has a foreign Worker on the same {domain}/* route is not changed until the installer confirms coexist_existing_worker: the preflight makes zero mutations and asks first. Once confirmed, that route moves to NORG’s Worker with its pattern unchanged, and the existing Worker is bound to NORG’s as a Service Binding named ORIGIN, so every non-agent request still reaches it. Uninstall, or an install that stops part-way, moves the route back before anything is removed. the existing-Worker install guide. (source: apps/api/tests/services/test_edge_install_coexist.py#test_equal_route_under_the_real_pin_asks_to_coexist)
• A site that is itself served by a Worker on a Workers Custom Domain installs with no extra confirmation: a route takes precedence over a Custom Domain on the same hostname, so NORG adds one route for its own Worker and binds the Custom Domain Worker to it as a Service Binding named ORIGIN, which hands every non-agent request to that Worker directly. The Custom Domain and its Worker are never written to; uninstall deletes only NORG’s route and Worker. (source: Cloudflare docs)
• The worker never reads cookies, request bodies, or Authorization headers to make its decision; it classifies a request from headers such as the User-Agent and Cloudflare’s source-IP signal, and forwards the body to the origin untouched. (source: apps/api/app/assets/edge-router-worker.js)
• Appending ?agent=true to any URL returns the mirror a verified AI agent would receive for that path. It is the review lever and bypasses the source-address (verified-source) check by design, so the mirror can be inspected from any address; it serves only what a verified agent would already get at that URL, and has an effect only once the site is entitled and serving mode is on — a path with no mirror returns the normal page. (source: apps/api/app/assets/edge-router-worker.js)
• A NORG-served response is identified by the header X-Norg-Edge: mirror together with Cache-Control: private, no-store; the normal page carries no X-Norg-Edge header, so the two page types are told apart by that header alone. (source: apps/api/app/assets/edge-router-worker.js)

Gotchas

Everything on this list was learned debugging real installs — scan it before concluding an install, a setting, or a test is broken.