> Netlify: what your AI agent should know — from The Handover, the-handover.org/services/netlify
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Netlify

What we tell an AI agent working on a project that uses Netlify: 2 rules, 1 learned the hard way.

Build a full rootnote set for a Netlify project: https://the-handover.org/build?areas=working-agreement,hosting&hosting=netlify

The vendor's own file for agents (what Netlify is, where its documentation lives): https://docs.netlify.com/llms.txt. This page covers where it catches agents out.

### Platform subdomains are blocked as a category, so a subset of users silently fails

> Hard-won · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-16

Put anything a user or a client application will reach on a **custom domain**,
never the free platform subdomain.

Corporate filters and security vendors block `*.pages.dev`, `*.vercel.app` and
`*.netlify.app` **as whole categories**, because they are also where a great
deal of phishing is hosted. The consequence is the worst available shape: it
works for you, it works for most people, and it fails completely for whoever
sits behind one of those filters — with no error you will ever see.

**This is not a polish step to do before launch.** A subdomain that reached real
users is a subdomain in somebody's bookmarks and somebody's integration, and
moving it later costs more than setting it up now.

Full account: https://the-handover.org/docs/custom-domains-for-edge-deployments.md

### Preview deployments are reachable, so scope secrets to the environment that needs them

> General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-18

- **Scope production secrets to production only.** Both platforms set variables
  per environment; a production database URL available to previews is available
  to every branch anyone pushes.
- **Never point a preview at production data.** A preview URL is easy to find and
  easy to share, so treat anything deployed there as public.
- **Gate previews that must stay private** with the platform's protection rather
  than relying on the URL being obscure.