Agent Tier DNS Zone

The AI agent fleet (ruche) answers ACME’s DNS-01 challenge with a Cloudflare API token scoped to its own domain, never the token that guards the parent domain (ADR-0054, ADR-0068):

• Blast-radius containment — a Cloudflare token is zone-scoped, not record-scoped. A token able to complete DNS-01 for the parent domain can rewrite MX and every other record in that zone; a token scoped to a separate domain can only touch the agent tier.
• ruche is assumed compromisable (ADR-0054) — the token it holds must cost only the agent tier if it leaks.

Caution

The agent tier’s domain is a separate registered domain, not a subdomain of the parent domain. Cloudflare only supports delegating a subdomain as its own independently-managed zone on Enterprise plans; on Free/Pro the dashboard refuses it outright (“provide the root domain, not a subdomain”). A second domain sidesteps that and reuses the existing Cloudflare integration unchanged.

Caution

essaim.{agents_domain} becomes the aoe dashboard’s origin (#740). An installed PWA binds to its exact origin, so settle the domain before the first install — changing it later forces a delete-and-reinstall on every device.

Config keys

Key	Secret	Holds
agents_domain	no	the agent tier’s own domain, e.g. agents-example.com
agents_cloudflare_dns_api_token	yes	API token scoped to the agents_domain zone only
aoe_subdomain	no	the agent tier’s serving gate — host-scope it, see below

aoe_subdomain decides which Host’s Caddy answers for this zone. Set it under [hosts.<name>], never fleet-wide: a fleet-wide answer points every Host’s Caddy at the agent tier’s token, and the parent domain’s certificates then fail to renew.

Provisioning

Getting a domain onto Cloudflare and minting a scoped token both sit behind an interactive Cloudflare login — those steps are the checklist below.

1. Get the domain onto Cloudflare. Either transfer an existing registration in (Cloudflare dashboard → Domains → Add a site → Transfer a domain) or keep it registered elsewhere and just point its nameservers at Cloudflare (Add a site → Connect a domain). Either way it must be a root domain — Cloudflare rejects a subdomain here. Wait for the zone to show Active.

2. Mint the token, scoped to the new zone only:

   Permission	Level
   Zone → DNS	Edit
   Zone → Zone	Read

   My Profile → API Tokens → Create Token → “Edit zone DNS” template, with Zone Resources narrowed to the single agents_domain zone. Copy the token immediately — it is shown only once.

3. Store both values:

   auberge config set agents_domain agents-example.com
   auberge config set agents_cloudflare_dns_api_token YOUR_TOKEN

4. Verify the token authenticates and is scoped to exactly the one zone:

   curl -s -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.cloudflare.com/client/v4/zones | jq -r '.result[].name'
   # expect exactly: agents-example.com

5. Point the agent Host’s Caddy at it, by host-scoping the serving gate. auberge config set writes only top-level keys, so this one is edited in the file — auberge config edit:

   [hosts.ruche]
   aoe_subdomain = "essaim"

   infrastructure.yml reads that gate and resolves Caddy’s caddy_dns_api_token to agents_cloudflare_dns_api_token on that Host alone; every other Host keeps cloudflare_dns_api_token (ADR-0072). tests/caddy_acme_token.rs asserts both directions.

Rotation

Cloudflare tokens carry no forced expiry unless one is set at creation — set a TTL when minting and note the rotation date. To rotate: create a replacement token scoped to agents_domain the same way, auberge config set agents_cloudflare_dns_api_token NEW_TOKEN, revoke the old token, then auberge deploy --tags caddy -H ruche to rewrite /etc/caddy/caddy.env.