Where to Publish agent-policy.json: the /.well-known/ Path
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
An agent policy lives at exactly one address: https://<your-site>/.well-known/agent-policy.json. Agents discover your terms by fetching that single, stable URL — there is no registry to register with and no directory to submit to in v0.1. The file must be served as application/json and reachable without authentication. Publish it anywhere else, or behind a login, and as far as the format is concerned you have not published it at all.
What is the well-known path?
The /.well-known/ directory is the web's conventional shelf for site-level declarations — files that describe the site itself rather than any page on it. AGENT-POLICY v0.1 puts its document there for the same reason robots.txt sits at a fixed root path: discovery only works if the finder does not have to search. An agent visiting a new site makes one guess, and the format guarantees the guess is right. The policy's own site field names the canonical origin, and the file belongs on that origin — a policy served from a different domain than the one it describes is a document in the wrong envelope.
The serving requirements, one by one
Exact path. /.well-known/agent-policy.json — not /agent-policy.json, not a page about the policy. Content type. application/json, so agents and validators parse it as the document it is. No authentication. The spec is explicit: reachable without authentication. A login wall, a bot challenge that blocks the fetch, or an IP allowlist all defeat discovery — the agents the file addresses are precisely the visitors such walls keep out. The real file. What the URL returns must be the policy itself, not a redirect to a landing page or a stale cached draft; validate the live copy, not the one on your disk, because the live copy is the only one agents will ever read.
Two softer requirements deserve the same seriousness. Stability: the URL is a promise — agents cache it, operators bookmark it, and other documents cite it — so treat moving it the way you would treat moving your homepage. Freshness: the served file should be the current version, with last_updated matching your latest review; a deployment pipeline that publishes every page except this one is a quiet, common failure, and fleets that host many policies watch for it as the multi-site guide describes.
Self-host, or let AgentGate host it?
Self-hosting is the default the spec assumes: you serve the file from your own origin, which is also the strongest form of the declaration — the terms sit on the domain they govern. AgentGate's Pro tier offers hosted policy URLs — we serve your agent-policy.json for you — which suits owners who cannot easily add a well-known file to their stack, or who want the policy's home managed alongside its change history. The trade-off is the envelope point above: a hosted URL is a convenience with a different address, so weigh it against how literally your agents discover policies. The hosted URLs guide works through the decision; either way, the document itself — generated by the free generator, checked by the validator — is the same file.
Checking the publication like an agent
Finish by doing what your readers do. From a machine that is not logged into anything, fetch the well-known URL and read what comes back. Confirm the status is success, the content type is JSON, and the body is your current policy — then paste that fetched body into the validator and confirm it is the document you meant to publish. This ten-minute ritual, repeated after every edit, is the difference between believing you have a policy and having one. It is also the first diagnostic when an operator reports your terms look wrong: fetch before you argue.
Worked example: a SaaS tool finds its policy behind its own login wall
Fictional example. Ledgerline, a fictional invoicing tool for freelancers, published its policy correctly in every respect but one: its platform's blanket authentication middleware intercepted /.well-known/ along with everything else, so unauthenticated fetches — which is to say, every agent fetch — received the login page with a success status. The file existed; the discovery failed. The tell was an operator's polite email quoting the "policy" they had fetched, which contained a password form. The fix was a middleware exemption for the single path. Ledgerline's checklist now includes a logged-out fetch of the well-known URL after every platform release — 1 URL, checked like an agent, because that is who the URL is for.
The publishing checklist
- Use the exact path.
/.well-known/agent-policy.jsonon the origin the policy describes. - Serve it as JSON. Content type
application/json, body equal to the policy document itself. - Keep it public. No login, challenge, or allowlist between an agent and the file.
- Validate the live copy. Fetch the published URL and validate what returns, not the draft on disk.
- Protect the URL. Treat the address as permanent infrastructure; re-check it after every platform change.
Keep reading
How to Validate an agent-policy.json File · The Five Conformance Rules of AGENT-POLICY v0.1 · How to Tell AI Agents What They May Do · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
Can I publish the policy at a different URL?
Not for discovery purposes. Agents look at /.well-known/agent-policy.json on your origin — that fixed location is the discovery mechanism the whole format rests on. You may also post the document elsewhere for humans, but the well-known copy is the policy as far as agents are concerned.
Does the policy need its own domain or subdomain?
No. It lives on the same origin it governs, in the /.well-known/ path. The file's site field names that canonical origin, and the two should match: the envelope and the letter should agree about whose terms these are.
What if my platform cannot serve a .well-known file?
That is the case hosted policy URLs exist for: AgentGate's Pro tier serves your agent-policy.json at a hosted URL. It is a pragmatic substitute with a different address, so it trades the spec's pure discovery for convenience — the hosted URLs guide weighs the decision in full.
Why must the file be reachable without authentication?
Because its readers are, by definition, visitors who have not been given credentials. An agent discovering your terms is a stranger asking what the rules are. A policy behind a login answers only agents who already have accounts — the ones who need the declaration least.
How do I know agents can actually fetch my file?
Fetch it the way they do: logged out, from a clean session, with no special headers, and read the response. Success status, JSON content type, and your current document body — all three — are the proof. Repeat after edits and platform releases; discovery fails quietly when stacks change.
Generate a policy — free · Validate a policy · What an agent access policy is