An AGENTS.md File That Tells Your Agent Where To Deploy

You asked your agent to put the app online last week, and it did. Today you asked again in a fresh session and it started from zero. It asked which host. It ran the wrong build. It tried to upload the whole project folder, node_modules and all.

That isn't the agent being forgetful on purpose. Every session starts blank. Whatever you told it last time is gone unless it's written down somewhere the agent reads on its own.

That somewhere is an AGENTS.md file: a plain text file at the top of your project that coding agents load before they do anything. Most people use it for code style and test commands. Almost nobody uses it for the one job you repeat every time, which is getting the thing online.

This post covers what goes in one, how it differs from CLAUDE.md, and a Deploying section you can paste in today. It works for any host. You only have to fill in one line.

What Is An AGENTS.md File?

An AGENTS.md file is a README written for coding agents instead of people. It's ordinary Markdown with no required fields, it sits at the root of your project, and agents that support it read it automatically when a session starts.

The format began as a shared convention between agent makers and is now looked after by the Agentic AI Foundation under the Linux Foundation. the AGENTS.md format and the list of agents that read it Its own suggestions for what to put in one are a project overview, build and test commands, code style, testing, security notes and, near the end of the list, deployment steps.

That last item is the one that saves you the most typing. If your agent already deploys well when you walk it through, how a Claude Code website gets online in one request shows the round trip this file is meant to make permanent.

Nested Files And Which One Wins

You can have more than one. A monorepo can put an AGENTS.md inside each package, and the agent reads the nearest one in the folder tree. The rule from the format's FAQ is simple: the closest file to the code being edited wins, and whatever you type in the chat overrides everything.

For a single app, one file at the root is all you need.

Who Reads AGENTS.md And Who Reads CLAUDE.md?

Many coding agents read AGENTS.md, and Claude Code reads CLAUDE.md first. Since Claude Code 2.1.277, it also reads AGENTS.md when no CLAUDE.md exists anywhere in your working folder or above it. If both files exist, it reads only CLAUDE.md unless you change one setting.

Anthropic's notes on how Claude Code loads AGENTS.md and CLAUDE.md

My pick is to write AGENTS.md and treat it as the source of truth. If you also want Claude-specific rules, make a CLAUDE.md whose first line is @AGENTS.md, then add the extras below it. One file to maintain, and every agent you try next year already knows how you deploy.

One honest caveat. Both files are advice, not locks. Anthropic's own docs say Claude treats them as context rather than enforced configuration, and the same is true for every agent. The file tells the agent what you want. The agent's sandbox and approval settings still decide what it's allowed to do.

What To Put In Your AGENTS.md File

Keep it short and specific. A long file gets skimmed by agents the same way it gets skimmed by people. These are the sections worth having, in the order I'd write them:

1. What the project is. One sentence. "A Vite and React app, no backend."
2. Setup. npm install, plus anything unusual.
3. Build. The exact command and the folder it writes.
4. Checks. The test or lint command the agent should run before saying it's done.
5. Deploying. Where the build goes and how. This is the section most files are missing.
6. Never. Two or three hard rules: never commit .env, never deploy without being asked.

If you've already got a set of prompts that get good pages out of an AI, the same thinking applies here, written once instead of typed every time. The prompts that get a usable website out of an AI covers the chat side of that.

A Deploying Section You Can Copy

The Deploying section tells the agent four things: how to build, which folder is the website, the exact command that sends it, and what to tell you afterwards. Here's the version that works for any static host. Fill in the one line in square brackets.

## Deploying

This project builds to static files. Only the build output is deployed.

1. Run `npm run build`. The output folder is `dist/`.
2. Check that `dist/index.html` exists and that `dist/` holds no
   `.env` file and no `.map` files.
3. Deploy only the contents of `dist/`: [your host's deploy command]
4. Reply with the live URL. If the host returns a claim link or an
   expiry time, give me those too, word for word.

Never deploy unless I ask for it in this session.

Swap dist/ for build/ or out/ if your framework writes there. Vite uses dist. Create React App uses build. A Next.js static export uses out.

Step 2 matters more than it looks. An agent will happily ship whatever is in the folder, and a forgotten .env in a public folder is a public .env.

The Same Section, Filled In For A No-Account Deploy

Here is what that third line looks like with a real host in it. I'm using ours, because it's the one I can vouch for: OxyPages takes a zipped build output with one HTTP request and needs no account, no CLI and no key.

## Deploying

This is a Vite app. It deploys as static files from `dist/`.

1. Run `npm run build`.
2. Check `dist/index.html` exists and `dist/` has no `.env` or `.map` files.
3. Zip what is inside `dist/`, not the folder itself:
   (cd dist && zip -r ../dist.zip .)
4. Send it:
   curl -sS -X POST https://api.oxypages.com/drops/app \
     -H "X-Oxy-Agent: my-agent" -F "file=@dist.zip"
5. Reply with `url` and `claim_url` from the response. Say the link
   expires in 30 minutes unless I open the claim link to keep it.

Never send the source folder, `node_modules` or `package.json`.
Never deploy unless I ask for it in this session.

The reply carries the live link and a claim link. That temporary-link-then-claim pattern isn't ours alone: Vercel, Netlify and Cloudflare all have their own version, with a longer window than our 30 minutes. How deploying without an account works, host by host has the dated comparison.

If you already use one of those hosts, put its own deploy command on that line instead. The rest of the section doesn't change.

A Five-A-Side League Table, Before And After

Say you've built a small Vite app that shows the league table for your Thursday five-a-side games. You built it with Codex, you've deployed it twice, and both times you spent five messages explaining how.

Without an AGENTS.md file, "put it online" gets you something like this: the agent asks where, you tell it, it runs the dev server instead of the build, you correct it, it zips the project root, the host refuses the source folder, and you correct it again.

With the Deploying section above in the root of the repo, the same request goes like this:

1. The agent reads AGENTS.md at the start of the session.
2. It runs npm run build, which writes dist/.
3. It checks for dist/index.html and confirms there's no .env in the folder.
4. It zips the contents of dist/ and runs the deploy line.
5. It replies with the live link, the claim link and the expiry, because step 5 told it to.

The first deploy took a conversation. Every one after it takes one sentence.

When we ran this exact flow with Claude Code in an empty Vite project, it didn't even need the file: it found the instructions on our site and did the whole deploy from one request. I haven't recorded the same test with Codex or Cursor, so I won't claim it. What I can say is that the request is a plain curl, which works from any agent allowed to run a shell command, and the AGENTS.md file is what makes the agent choose that command without asking you first.

When The Agent Says It Can't Reach The Internet

Some agents block network access by default, so the deploy step fails even with perfect instructions. The fix is an approval or a setting, not a better file. Add one line to the Deploying section so the agent knows to ask rather than give up: "If the deploy command is blocked by the sandbox, ask me to approve it."

What An AGENTS.md File Can't Do

Being straight about the limits, because they decide whether this is worth setting up.

• It can't make a server app static. If your project renders pages on a server or has api/ routes, no deploy line in a text file turns it into files. It needs a host that runs code, such as Vercel, Netlify or Cloudflare Workers, and OxyPages is the wrong tool for it.
• It can't override the sandbox. The agent still needs permission to use the network.
• It can't keep secrets out by itself. The check in step 2 helps. Reading what's in the folder helps more.
• It isn't read by every tool. Chat assistants on claude.ai or ChatGPT don't read your project files at all.

What To Do Next

Open your project, create a file called AGENTS.md at the top, and paste in the generic Deploying section. Fill in the build command, the output folder and the deploy line for whichever host you use. If you use Claude Code alongside other agents, add a CLAUDE.md whose first line is @AGENTS.md.

Then ask your agent to deploy in a brand new session. If it gets there without a single follow-up question, the file is doing its job.

If you'd like a deploy line that needs no account to test, start with a free no-account link and claim it if you want to keep it.