Cloudflare

Runs on: your browser (the Cloudflare dashboard). box:box-setup does the tunnel part on the box.

Used by: box:box-setup, box:expose-service, box:new-landing-page, box:staging-env, and the “Protect the API” part of backend.md.

Cloudflare runs DNS for your domain and sits in front of your box. The Cloudflare Tunnel (cloudflared) dials out from the box to Cloudflare, so no port on the box or your router has to be open. Set it up in Phase 2, after you have a domain (domain.md) and before box:box-setup.

What it costs

The Free plan covers all of this: DNS, proxying, the edge certificate and Cloudflare Tunnel. You pay only for the domain, at whatever registrar you use.

Free-plan limits that matter here: request bodies up to 100 MB, 100 seconds to the first byte. The free edge certificate covers example.com and *.example.com, one level deep.

Steps

1. Create an account

Sign up at dash.cloudflare.com. Turn on two-factor login in your profile.

2. Move the domain’s DNS to Cloudflare

1. In the dashboard, open Domains and choose Onboard a domain. Enter the apex domain (example.com). Pick the Free plan.
2. Check the DNS records Cloudflare copied from your old DNS host. Keep mail records (MX, SPF, DKIM, DMARC) exactly as they were. Mail records are never proxied.
3. Cloudflare shows two nameservers. Copy them.
4. At your registrar: turn DNSSEC off first if it is on. If you skip this, the domain can stop resolving. Then replace the nameservers with the two from Cloudflare.
5. Wait until the domain shows Active on the Domains page. It can take up to 24 hours; often it is minutes.
6. Turn DNSSEC back on, this time in Cloudflare, and add the DS record it gives you at the registrar.

3. Create the API token for DNS

The box skills write DNS records, and Traefik proves domain ownership for its certificates, through one scoped token.

1. Go to My Profile > API Tokens (dash.cloudflare.com/profile/api-tokens).
2. Create a token from the Edit zone DNS template.
3. Permissions: keep DNS Edit. Add Zone Read for the same zone, so skills can look up the zone ID by name.
4. Zone resources: include only your domain, not all zones.
5. Optional, only if your tunnel is managed in the dashboard (box:box-setup does not make one): add the Account permission for Cloudflare Tunnel with Edit.
6. Review and create. Copy the token once. Cloudflare will not show it again.

This token cannot list accounts. That is expected. Skills read the account ID from the zone instead.

4. The tunnel

You do not create the tunnel by hand. box:box-setup runs cloudflared tunnel login on the box. That prints a URL. Open it on your Mac, choose your domain and approve. Then box:box-setup creates a tunnel named box.tunnelName and keeps its ingress in /etc/cloudflared/config.yml on the box.

5. Put admin tools behind Access

Cloudflare Access puts a login in front of a hostname, at Cloudflare’s edge. The request never reaches the tunnel until the person has logged in. Use it for every admin tool and dashboard that has a public hostname: Traefik’s dashboard, Portainer, Grafana, a database UI, n8n, a staging web site. The Zero Trust Free plan covers up to 50 users.

1. In the dashboard, open Zero Trust. The first time, pick a team name (it becomes <team>.cloudflareaccess.com) and the Free plan.
2. Check that the one-time PIN login method is on, in the Zero Trust settings for authentication. Cloudflare then emails a code to an allowed address. No other identity provider is needed.
3. Go to Access controls > Applications, choose Create new application, then Self-hosted and private. Add the public hostname, for example grafana.example.com.
4. Add a policy: action Allow, include the email addresses that may log in. Access denies everyone else by default.
5. Save. Scripts that must reach the tool can use an Access service token (two headers) instead of a login.

Never put Access in front of the API your app calls. The app cannot log in, and every request fails.

Check it: open the hostname in a private browser window. You must see the Cloudflare Access login, not the tool. From the terminal: curl -sI https://grafana.example.com/ | grep -i location points at cloudflareaccess.com. The box:expose-service audit runs the same check on hostnames that look like admin tools.

6. Free-plan protection for the API (optional)

The API limits itself (backend.md, “Protect the API”). Cloudflare can drop the worst traffic before it reaches the box. What the Free plan gives you (checked 2026-09-28):

• One rate limiting rule. It counts by client IP, over 10 seconds, and blocks for 10 seconds. It can match on the URL path. Use it for sign-in: expression starts_with(http.request.uri.path, "/api/auth/"), 20 requests per 10 seconds, action Block. Keep it generous: many phones on one mobile carrier can share one IP. It sits on the page for rate limiting rules in the domain’s Security section.
• Five custom (WAF) rules. One cheap use: block the scanner paths your API never serves, so they do not reach the box at all. Expression: starts_with(http.request.uri.path, "/.env") or starts_with(http.request.uri.path, "/.git") or starts_with(http.request.uri.path, "/wp-"), action Block.
• Bot Fight Mode: leave it off on a domain that serves your app’s API. It may challenge API and mobile app traffic. An app cannot solve a challenge, so the request fails with an HTML page instead of JSON. On the Free plan it covers the whole domain, and WAF rules cannot skip it.

Check it: 25 quick requests to /api/auth/... from one machine get a Cloudflare block page for 10 seconds. curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/.env returns 403 and nothing shows in the API log.

Where the values go

Store the token by secrets.tool (see CONFIG.md):

• env: add CLOUDFLARE_API_TOKEN=... to a .env that is git-ignored.
• doppler: doppler secrets set CLOUDFLARE_API_TOKEN -p <project> -c <config>, then paste it when asked.
• 1password: save it as an item, and set box.cloudflareTokenRef to its op://vault/item/field reference.

The config holds the reference, never the token. box:box-setup also copies the token to the box once, into <box.appsDir>/traefik/.env (root only), because Traefik needs it to renew certificates.

Check it works

# read the token with your secrets tool, e.g. T=$(doppler secrets get CLOUDFLARE_API_TOKEN --plain)
T=$(printenv CLOUDFLARE_API_TOKEN)
curl -s https://api.cloudflare.com/client/v4/user/tokens/verify -H "Authorization: Bearer $T" | jq .result.status
curl -s "https://api.cloudflare.com/client/v4/zones?name=example.com" -H "Authorization: Bearer $T" | jq -r '.result[0].status'
unset T
dig ns example.com @1.1.1.1 +short

Expect active, active, and two *.ns.cloudflare.com names.

Common errors

Wrong or out of date? Fix it on GitHub.