VERBATIM SOURCE
SKILL.md
skill://sites@openai-curated-remote/root/.codex/plugins/cache/openai-curated-remote/sites/0.1.32/skills/sites-hosting/SKILL.md
---
name: sites-hosting
description: Host websites with Sites. Use with `sites-building` for Site registration, publishing, and deployment verification, or for hosting management without changing source.
---
# Sites hosting
Publish the exact validated source with the shortest safe sequence. Use the
lifecycle CLI for local checkpoint preparation and native `codex_apps` tools
for remote creation, version saving, deployment, and status verification.
Keep implementation changes in `sites-building`; this skill owns publishing.
The current Sites connector descriptions are the source of truth for arguments
and archive requirements.
## Site lifecycle ownership
Only the Site-owning agent responsible for the user's requested Site may run
`sites-hosting`, obtain source credentials, prepare checkpoints, or call Sites
tools. This is the main agent, including an independently started background or
invisible task that owns the requested Site, not a spawned child. A spawned
subagent returns its assigned image, asset, or research result without invoking
Sites skills or tools or editing the checkout. Do not delegate publishing or
status polling to a monitoring subagent.
Make native `codex_apps` create, save, deploy, and status calls directly in the
owning main conversation. Core supplies the current turn and product context;
do not replace these calls with shell HTTP requests or fabricated metadata.
## Communicate clearly
Assume the user is a nontechnical knowledge worker. Keep source control,
credentials, IDs, commits, versions, archives, connector calls, and deployment
polling out of user-facing messages. Usually send one publishing update, then
the verified URL or a plain-language blocker. Announce verified intermediate
checkpoints as described in **Handoff** without waiting for feedback unless
the user requested review gates.
## Rules
- Publish coherent milestones from `sites-building` unless the user requested
local-only work. Every checkpoint is production, not staging or preview.
- Checkpoint preparation is the normal build and packaging gate; do not add a
separate foreground build before it. Publishing does not require additional
browser testing or visual QA.
- Treat `public/screenshot.jpeg` as an optional deployment thumbnail. Preserve
an existing file. Create or refresh it only when the user explicitly requests
a Sites deployment thumbnail; a generic screenshot request does not count.
Missing or failed capture never blocks validation, version saving, or deployment.
- Use the lifecycle checkout and its `.openai/hosting.json` identity. Keep Git
operations and source credentials inside the CLI; never copy credentials
into commands, files, Git configuration, or user-facing output.
## Register a new Site
Work registers a new Site before source implementation and dependency setup.
Start only after `sites-building` runs the CLI's local `create` preflight and
receives `ready_to_create`; preflight failure must not create a remote Site.
1. The main agent calls `sites_create_site` directly through `codex_apps` with
the exact returned `create.arguments`.
2. Copy the response's opaque `id` unchanged as `--project-id` for the
`initialize` command in `sites-building`. The create response can include a
source credential: ignore it, and never copy, print, persist, or pass it to
initialization. The CLI acquires its own process-local Git credential.
3. Return to `sites-building` to initialize that same project with the validated
slug and starter, then implement the Site. Do not create another Site when
later publishing or recovering from an initialization failure.
Reuse the existing project for edits and hosted-Site management. Treat quota,
permission, and access errors as blockers; do not change the slug speculatively.
If the creation outcome is uncertain, reconcile whether the Site already
exists before continuing; never blindly repeat creation.
## Fast publish sequence
Start with the existing `checkout_path` and a concise checkpoint message from
`sites-building`. At most one checkpoint may be preparing, awaiting save/deploy,
or nonterminal for a given `project_id`. Do not start another checkpoint or
push during that interval: the prepared commit must still be the source branch
HEAD when saved. Keep source unchanged during preparation. After launch, the
same owner may alternate continued source work with direct status polls, but
must finish terminal verification before the next checkpoint for that Site.
Different Site projects may proceed independently.
### Prepare and approve
Run the lifecycle CLI from this skill:
```sh
python3 "$(dirname "<absolute path of this SKILL.md>")/scripts/sites.py" checkpoint \
--path "<checkout_path>" \
--message "<concise commit message>"
```
Checkpoint reads current access before changing source state. For a verifiably
owner-only Site it selects private deployment without asking again. For a
shared, public, or not verifiably owner-only Site, it requires explicit approval
before preparing publication. If it requests approval, reuse qualifying
approval below or stop and ask the user, naming the resolved audience. Only
after approval, rerun with `--user-approval-provided`.
An explicit request to deploy or publish this Site counts as approval; a request
only to create or edit a website does not. Reuse explicit approval for the same
Site in the current conversation, including later checkpoints, while the
audience is unchanged or narrower and the user has not revoked or limited it.
Keep passing the flag under those conditions. Ask again if the audience widens,
the target Site changes, or the user revokes or limits approval. Never treat a
prepared payload or its approval flag as independent evidence of user consent.
The default checkpoint builds, packages, commits, and pushes, then returns
`ready_to_publish` with a private local archive for native MCP upload. A build
or packaging failure stops before push, save, or deploy. Use
`--use-remote-build` only for a clearly transient or environmental local-build
failure outside the Site source that cannot reasonably be fixed in the checkout.
That path pushes source without a
local build or archive upload. Fix code-level failures instead of bypassing them.
`ready_to_publish` is preparation, not a saved version, deployment, or live URL.
If it is already available, continue with that handoff rather than rerunning
checkpoint. If preparation stops before deployment, there are no deployment IDs
to poll or announce.
### Save and deploy through native MCP
Complete each prepared handoff with direct main-conversation `codex_apps` calls:
1. Call `sites_save_site_version` with the exact returned `save.arguments`.
Preserve the pushed `commit_sha` and, when present, the absolute local
`archive` path. Native MCP uploads that file; do not pass a backend
uploaded-file object or upload it through shell HTTP. Keep the exact archive
unchanged in the same primary execution environment until saving succeeds.
Never substitute a later HEAD, rebuild, or mix source and archive from
different checkpoints.
2. Verify the saved version's `project_id` and `source.commit_sha` match the
prepared result and its `id` is present. If they do not, stop without
deploying. Use that exact opaque `id` as `version_id`.
After this verified save, remove only that checkpoint's local archive and
its now-empty temporary directory. Keep it for diagnosis or retry if saving
fails or its outcome is uncertain; never remove the checkout or other artifacts.
A cleanup failure does not block deploying the verified version; retain the
path for later cleanup rather than rebuilding or saving again.
3. Call the returned `deploy.tool` with that `project_id` and `version_id`.
`sites_deploy_site_version` requires qualifying explicit user approval.
If private deployment rejects with `site_not_owner_only`, do not retry
private or silently fall back. Read the current access policy, reuse
approval only for the same Site and an unchanged or narrower audience, or
ask for approval. Only then call `sites_deploy_site_version` for the same
saved version; do not prepare another checkpoint merely to obtain approval.
4. Verify the deployment's `project_id` and `version_id` match this handoff and
its `id` is present. Keep these immutable IDs together for verification.
Unknown or malformed responses are not success.
5. Follow **Handoff** directly, including when the launch snapshot is already
terminal. A launch response alone is not verified publication.
## Handoff
The Site-owning main agent itself calls `sites_get_deployment_status` directly
through `codex_apps` in the main conversation with the exact `project_id` and
the deployment response's `id` as `deployment_id`. The deployment owns its
saved version; do not pass `version_id` to the status call.
Poll while status is `pending`, `building`, or `publishing`, stopping at
`succeeded` or `failed`. While it runs, the owner may continue source work and
poll between edits; do not spawn a monitor. The direct main-agent call that
returns terminal status is the verification. Make it even if the launch
response was already terminal. The frontend keys on this call to show the
checkpoint; a relayed result or URL pasted into commentary cannot substitute.
- On `succeeded`, the same direct response must contain the literal production
URL. If the URL is absent, make one additional same-ID status call. Follow
its returned state; if it remains `succeeded` without a URL, report incomplete
verification rather than success. Never substitute a URL from a launch
snapshot, another checkpoint, or a subagent.
- On `failed`, keep the immutable IDs for diagnosis and follow **Failure
handling**. Do not announce publication or automatically redeploy that version.
- On an unknown or malformed response, stop and report incomplete verification;
do not guess status or substitute IDs.
When a direct response contains `succeeded` and its URL, immediately send a
concise checkpoint-ready commentary with a short milestone label and that URL,
even while implementation continues. This deliverable is exempt from the
progress-update limit in `sites-building`. Do not wait for feedback unless the
user requested review gates, but incorporate steering before the final checkpoint.
Do not fetch or open the deployed URL merely to finish publishing, and never
navigate the cloud browser to a live Sites URL; that runtime cannot reach it.
The direct status call surfaces the verified URL for the user to open in their
own browser. Explicitly requested agent-side browser QA stays in
`sites-building` on the internal agent preview.
For final delivery, return the literal verified deployed URL and a concise
description of what the user can do. Never let an older checkpoint stand in for
the latest requested work. Keep IDs, checkout paths, credentials, and temporary
artifacts private unless the user needs nonsecret details to act.
## Existing sites and advanced capabilities
For environment, deployment, analytics, or access-management requests, inspect
the current Site and connector schema before acting. Treat all IDs and cursors
as opaque and copy them exactly.
- Do not run `create`, `edit`, or `checkpoint` for management-only work. Source
changes return to `sites-building` and use this skill's checkpoint flow.
- Do not claim public access or another mode absent from the current project
or connector, or change audience or environment values without corresponding
user intent. Every deployment URL is production.
- Poll an existing nonterminal deployment only when progress is requested or
required to finish an active flow.
## Failure handling
- If saving rejects a stale commit because another writer advanced the branch,
stop the handoff and reconcile the checkout in `sites-building` before
preparing a new checkpoint. Never replace only the SHA while retaining an
earlier archive.
- For source or remote-build failures, return to `sites-building`, fix the
checkout, and prepare a new checkpoint. Do not automatically redeploy the
failed saved version. Keep recoverable intermediate failures internal unless
they block delivery or require user action.
- For other connector, Git, authentication, or validation failures, identify
the failed phase; do not switch deployment tools. Classify Git's
`CONNECT tunnel failed, response 403` as proxy or network policy before
authentication; do not rotate credentials.
- If checkpoint IDs are missing, recover the actual phase/result; never guess
IDs or poll an unrelated deployment. Offer only capabilities exposed by the
current connector and Site. Report a blocking or final failure with its
user-visible reason and next step.