GeoHarness

Cloudflare setup, permissions and limits

GeoHarness needs one Cloudflare API token and your account ID. The token needs only the permission groups of the features you enable, and preflight probes each one before anything is changed.

Updated · Source: cloudflare-permissions.json

How do I create the API token?

  1. In the Cloudflare dashboard open My Profile → API Tokens and choose Create Token → Create Custom Token.
  2. Name it, for example geoharness-<site>.
  3. Add each permission group in the table below that your target and optimizations need: account groups under Account, zone groups under Zone.
  4. Under Account Resources include only your account; under Zone Resources include only the zone that serves your domains.
  5. Create the token and store it as the repository secret CLOUDFLARE_API_TOKEN; store your account ID as CLOUDFLARE_ACCOUNT_ID.

Which permission groups does the token need?

API token permission groups (from cloudflare-permissions.json)
Permission groupScopeNeeded for
Cloudflare Pages Writeaccountpages-deploy, pages-custom-domain
Workers Scripts Writeaccountworkers-deploy
Bot Management Writezonebot_fight_mode, ai_bots_protection
DNS Writezoneworkers-custom-domain, pages-custom-domain
Response Compression Writezonezstd
Workers Routes Writezoneworkers-custom-domain
Zone Readzonezone-read
Zone Settings Writezoneemail_obfuscation, rocket_loader, early_hints, http3, brotli, smart_tiered_cache
Zone Transform Rules Writezonerewrite-rules

Per feature, as preflight checks them:

FeatureWhat it doesGroups
workers-deployUpload the assets-only (or negotiate) WorkerWorkers Scripts Write (account)
workers-custom-domainAttach the site's domains to the Worker as Custom DomainsWorkers Routes Write (zone), DNS Write (zone)
pages-deployCreate the Pages project and upload a deploymentCloudflare Pages Write (account)
pages-custom-domainAttach domains to the Pages project and create their proxied CNAMEsCloudflare Pages Write (account), DNS Write (zone)
zone-readFind the zone that serves each domainZone Read (zone)
rewrite-rulesURL Rewrite Transform Rules that serve markdown twins on Accept: text/markdownZone Transform Rules Write (zone)
email_obfuscationTurn Email Obfuscation off (it rewrites HTML that agents and twins read)Zone Settings Write (zone)
rocket_loaderTurn Rocket Loader off (it rewrites script tags and hurts Lighthouse)Zone Settings Write (zone)
early_hintsTurn Early Hints onZone Settings Write (zone)
http3Turn HTTP/3 onZone Settings Write (zone)
brotliTurn Brotli onZone Settings Write (zone)
smart_tiered_cacheTurn Smart Tiered Cache onZone Settings Write (zone)
zstdCompression Rule preferring zstd for the site's hostResponse Compression Write (zone)
bot_fight_modeTurn Bot Fight Mode off so AI crawlers receive HTTP 200Bot Management Write (zone)
ai_bots_protectionSet AI bots protection to disabled so AI crawlers receive HTTP 200Bot Management Write (zone)

Opt out of any zone optimization with extra-optimizations (for example all -zstd) and its permission is no longer required.

What are the free-tier limits?

Cloudflare free-plan limits GeoHarness works within
ResourceFree planGeoHarness use
Transform Rules (URL Rewrite)10 rules per zone, no regex3 rules per host, built from concat and wildcard_replace
Workers static asset requestsFree and unlimitedEvery page, twin and file is a static asset
Workers requests100,000 per dayNone, unless the zone is not accessible (fallback below)
_headers rules100The site's own rules plus GeoHarness's; more is a build error
Markdown for AgentsPro plan and aboveNot used; reproduced with twins and rewrite rules

What happens when something is missing?