How to prompt Codex Sites for the site you want
A repeatable shape for Codex Sites prompts — name the audience, the core experience, and the required data, tag @Sites, and let Codex pick storage and identity.
The fastest way to get the site you want out of Codex Sites is to stop describing code and start describing the product. Every strong prompt names three things: the audience who uses it, the core experience they need, and the data that has to persist. Tag @Sites when the task should end in a hosted deployment, describe the behavior you want, and let Codex map that behavior to the right shape — storage, sign-in, the lot. Codex Sites is in preview, so treat the official docs as the live source of truth, but the prompt shape below is stable and worth memorizing.
Codex Sites is the Sites plugin for OpenAI Codex: a prompt or a compatible project becomes a hosted website, web app, or game, with no separate deploy workflow. The build is rarely the weak link. The brief is. A vague prompt produces a vague dashboard, and because every deployment URL is production, a sloppy spec costs you a real deploy. So the work that pays off most happens before you ever type the prompt.
The three things every Sites prompt needs
There is a repeatable triad underneath every prompt that lands close on the first try. Miss one and Codex has to guess; name all three and it has enough to provision the right pieces.
| Part of the prompt | The question it answers | Example phrasing |
|---|---|---|
| Audience | Who is this for, and do they sign in? | "for my operations team," "require a workspace account" |
| Core experience | What do people actually do here? | "submit requests, see owners, update status, filter" |
| Required data | What has to persist between visits? | "keep the request data saved between visits" |
Audience tells Codex whether the site is internal or public, and whether identity matters. Core experience is the verb list — the things a user does — and it shapes the layout and the data model. Required data is the durability requirement: what a person would be annoyed to lose on a refresh. Say all three in plain language and you have given Codex a spec, not a wish.
Name @Sites when you want a deployment
Tag the plugin explicitly with @Sites, especially when the task should end in a hosted deployment. It is a signal, not decoration: it tells Codex this is a Sites job — provision hosting, pick storage, wire identity — rather than generic code generation that leaves you to deploy by hand. Here is the verbatim new-tool prompt from the docs, and notice how it carries the full triad:
@Sites Build a project request dashboard for my operations team. Let team members submit requests, see who owns each one, update the status, and filter the list. Require people to sign in with their workspace account, and keep the request data saved between visits.
Audience: the operations team, signed in with a workspace account. Core experience: submit, see owners, update status, filter. Required data: request data saved between visits. That one request implies sign-in, persistence, and a real data model, and Codex provisions those instead of asking you to.
Map behavior to the right shape
You should not name D1 or R2 in your prompt. You name the behavior, and Codex Sites maps it to the right shape. The docs frame this as "site need to ask for," and the trick is to describe outcomes precisely enough that the mapping is unambiguous.
| Your site needs... | Describe this, and Codex reaches for... |
|---|---|
| A content-led site (landing, marketing, docs) | No persistent state unless a feature needs it |
| Saved records, user progress, or game scores | D1 — a relational database |
| Images, documents, audio, video, or other uploads | R2 — object storage |
| Uploads with searchable metadata | D1 + R2 — D1 for metadata, R2 for the file contents |
| An internal site that needs the workspace user's identity | Workspace-authenticated user identity |
| Public sign-in or an external identity provider | An authentication-enabled Sites project |
The discipline that keeps this clean: do not request durable storage for temporary presentation state. A theme choice, a dismissed banner, which tab is open — that is UI state, and it does not warrant D1 or R2. Reserve storage for product data the site should genuinely remember. If you would not miss it after a refresh, do not ask Codex to store it. For the full storage decision, see adding a database and file uploads to a Codex Sites app.
Worked examples
The docs ship a handful of prompts that are worth reusing as-is rather than inventing your own "magic" phrasing. Each one names @Sites and describes behavior, not implementation.
Deploy an existing project and get its URL:
@Sites Deploy this project. Check whether it is compatible with Sites, make any required changes, and give me the deployment URL.
Add data and uploads in one request — scores are structured, so Codex reaches for D1; avatar uploads are files, so it reaches for R2:
@Sites Add persistent player scores and avatar uploads to this game. Use the appropriate Sites storage and deploy the updated game.
Change who can reach a deployed site, with a confirmation step built into the ask:
@Sites Change this deployed site's access to everyone in my workspace after showing me the current site and confirming the deployment URL.
Three patterns, one habit: state the outcome, name the plugin, let Codex pick the components.
Vague to sharp: a rewrite
Here is the shape of a prompt that wastes a build. It is not wrong, exactly — it is just underspecified, so Codex has to fill the gaps with guesses:
Make me a tool where people can submit things and track them.
No audience, so Codex cannot tell internal from public or whether sign-in matters. The "core experience" is a shrug — submit and track what, and who owns it? And "track them" hides a real persistence question without answering it. Now the same idea, run through the triad:
@Sites Build a request tracker for my support team. Let agents submit tickets, assign an owner, change the status, and filter by owner and status. Require sign-in with a workspace account, and keep the tickets saved between visits.
Audience: the support team, workspace sign-in. Core experience: submit, assign, change status, filter. Required data: tickets saved between visits, which Codex reads as a durability requirement and provisions D1 for. Same idea, but now Codex has a spec it can build against on the first pass instead of a sketch it has to interpret. For the end-to-end flow around prompts like this, see how to use Codex Sites.
Pressure-test the brief first
This is exactly where multi-model chat earns its keep. The triad is easy to state and easy to get subtly wrong — the audience is fuzzier than you think, the verb list is missing a step, you ask for storage you do not need. Because every Codex Sites deployment URL is production, those gaps are not free to discover. So before we name @Sites, we draft the brief and stress-test it.
We do that drafting on oran.chat, handing the same brief to GPT, Claude, and Gemini and branching the conversation instead of overwriting it, so each model's objections sit side by side. One model questions the data model, another flags a missing role in the audience, a third points out we are storing UI state. The prompt we eventually hand Codex is the one that survived three sets of objections, not the first draft. And because we keep one instruction set across all three models, the critique stays consistent — for how that works, see the system prompt that works across GPT, Claude, and Gemini.
Codex Sites turns a good brief into a hosted site fast. Your leverage is the brief, and the cheapest place to fix it is before the first deploy. Remember the two stages once you do prompt: save a reviewable version, then deploy the one you approved.
The authoritative reference is the Codex Sites documentation, and since the feature is in preview, treat those pages as the live source of truth over anything here. For more like this, see Playbooks.