Terminal
Terminal/Skill
Builds and publishes a ChatGPT Sites app whose data and backend run on Convex.
By Convex
Works with
npx skills add get-convex/codex-sites-convex-backend-skill --skill codex-sites-convexBuild the complete application, validate both halves, and publish it unless the user explicitly requests local-only work.
.chatgpt.site URL.project_id, current access policy, and canonical current_live_url. Reuse the confirmed production Convex URL. Deploy Convex again only when backend code, schema, components, schedules, actions, or backend environment requirements changed; obtain fresh production consent immediately before that deployment. Always rebuild, scan, save, deploy, poll, call get_site, and run live QA for the new Sites version.Do not stop a publication workflow after local validation, cloud linking, Site registration, an access change, or environment configuration. Continue through the saved Sites version, deployment, nonempty get_site.current_live_url, and live QA unless a real authorization or platform blocker prevents progress.
api types.convex/, read references/convex-rules.md.convex-helpers or changing ESLint configuration, read references/helpers-and-eslint.md.If the installed sites:sites-building, sites:sites-hosting, convex:convex-expert, or convex:convex-reviewer skills are available, read and follow the relevant skill before acting. This skill sets the cross-product architecture; those skills own their product-specific implementation details.
Run scripts/check-runtime.sh from the target project root before npm install, npx, a project script, or another Node-based project command. Its initial node --version probe must be the first executable runtime check. Require Node.js 22.13.0 or newer and recommend Node.js 24 LTS. If it fails, stop before npm or npx, explain that npm install cannot install or switch Node, and follow references/local-runtime-and-server.md. After repairing the existing runtime selection within authorization, verify command -v node, node --version, command -v npm, and npm --version in a fresh login shell. Then run scripts/preflight.sh and inspect AGENTS.md, .openai/hosting.json, package.json, the lockfile, app/, convex/, and .env.example when present. Preserve the existing package manager, dependencies, scripts, lockfile, working structure, and unrelated uncommitted changes.
Report these Sites states separately; never use one as proof of another:
.openai/hosting.json contains a valid nonempty project_id, and get_site confirms the hosted record. Sidebar visibility is checked separately and may lag.get_site.current_live_url is nonempty. A deployment URL or successful save alone is not sufficient.For a new Codex user, explain that they paste the $codex-sites-convex prompt into a Codex task opened on their app folder. Treat the task box as an instruction composer, not direct shell input. When command tools are available, run routine setup, validation, and build commands directly instead of making the user copy them. If the user prefers manual execution, tell them to select the terminal icon in the upper right corner or press Ctrl plus the backtick key, confirm it is using the same project root, show commands in order, and distinguish commands that exit from development servers that must remain running. If the current surface cannot access project files or run commands, direct the user to the Codex desktop app, Codex CLI, or another command capable Codex environment. Ask the user only for required approval, authentication, account or project selection, secure secret entry, a user interface action, or a real platform blocker. Do not assume they know what “project root,” “terminal,” or a command approval means.
Classify CONVEX_DEPLOYMENT, the presence and scope of CONVEX_DEPLOY_KEY, saved Convex CLI user configuration, and the public Convex URL without printing credentials or configuration contents. No login prompt does not prove accountless mode; saved CLI credentials may already be active.
Classify the task:
convex/ and initialize the ChatGPT Sites frontend around it; do not scaffold another product app.Confirm an existing Convex project only when the same project root has both a convex dependency in package.json and either convex/ or convex.json. In a monorepo, use the nearest unambiguous matching root. Do not install managed Convex AI files when project ownership is missing or ambiguous.
For a new project, use the installed Sites building workflow to initialize the local project files, but do not start or open the Sites server yet. This cross-product ordering overrides the usual Sites-only preview order: provision Convex and pass the backend-readiness gate first. Create .nvmrc and .node-version with 24, set package.json#engines.node to >=22.13.0, copy assets/check-node-version.mjs to the app as scripts/check-node-version.mjs, and add predev, prebuild, and prestart scripts that run the check. Merge with existing scripts and preserve any stricter compatible starter requirement. Set or merge Vite server.strictPort: true so the new project fails on an occupied expected port. Treat .openai/hosting.json as a local hosting manifest, not proof of registration; only a valid nonempty project_id identifies a registered Site. Do not replace the project's vinext/Vite/Cloudflare Worker structure.
For an existing project, install dependencies only when absent. Preserve compatible runtime pins, pre-scripts, its package manager, and its deliberate port configuration. Do not create a second lockfile or replace existing pre-scripts when adding a runtime check. Inspect the actual starter before choosing its public environment-variable convention.
Use the current Convex workflow rather than hand-writing setup. Prefer the callable Convex start/runbook tools when available. Otherwise:
npm install convex
npx convex dev
npx convex ai-files status
These commands show the new npm-project path. For an existing pnpm, Yarn, or Bun project, use that package manager's install and executable commands; never create package-lock.json beside another lockfile.
For a confirmed Convex project, run npx convex ai-files install only when status reports missing or stale files. Let the CLI manage AGENTS.md, CLAUDE.md, convex.json, generated guidance, and project skills; never reproduce or edit managed sections by hand. Read convex/_generated/ai/guidelines.md completely before editing convex/ when it exists.
For accountless local agent development, use the supported non-interactive flow:
npm install
npx convex dev --once
Do not require login and do not set the legacy CONVEX_AGENT_MODE=anonymous flag. In a non-interactive shell with no configured deployment or deploy key, Convex automatically provisions a local backend.
Accountless Agent Mode is local-only. It may write the local frontend URL to .env.local, but it does not create a hosted Sites environment variable and cannot power a published Site. Linking the folder to Convex Cloud provides managed development and production deployments; it does not by itself publish Sites.
After provisioning, run scripts/check-backend-ready.sh. Do not start the Sites server or open a browser until .env.local contains a nonempty NEXT_PUBLIC_CONVEX_URL and the generated Convex API exists.
For an interactive preview, keep npx convex dev running alongside Sites after the initial provisioning succeeds. Do not overwrite existing environment files. Keep .env.local ignored and .env.example limited to public names without values.
Treat Convex development and production as separate targets:
npx convex dev --once to provision/push once, then keep npx convex dev running for an interactive preview. The frontend uses the development URL written to .env.local.npx convex dev --once, and publish Sites against its public URL. Label it non-production and report its expiration.npx convex deploy. Capture the production deployment URL and rebuild Sites with that URL; never publish a bundle connected to the development deployment.Before implementing any product capability:
https://www.convex.dev/components/get-convex.md.https://docs.convex.dev/llms.txt.SKILL.md completely before writing code.convex-helpers repository and package documentation. Install it only for a named matched utility; it is not a Component or default dependency.Never select or install a Convex static-hosting component. ChatGPT Sites owns the frontend build, published URL, and sharing.
Use scripts/check-components.sh <keywords> for a quick catalog search. Treat its output as discovery only; read the matched component skill and official documentation before implementation.
Follow https://www.convex.dev/agent-setup.md. Prefer the full official Convex plugin for Codex because it includes skills and MCP. Inspect and verify the marketplace and installed plugin before changing anything. When the plugin succeeds, do not install separate Convex skills or add a duplicate MCP server.
Run applicable setup commands directly. Ask the user only when approval, authentication, a user-interface action, or a restart is required. Preserve unrelated settings and repository changes.
When the full plugin is unavailable, use the fallback integration. Add this entry to ~/.codex/config.toml without replacing unrelated configuration, then restart Codex:
[mcp_servers.convex]
command = "npx"
args = ["-y", "convex@latest", "mcp", "start"]
Verify the selected integration with plugin listing, AI-file status, and MCP health where available; install success alone is insufficient. Report setup as partial with the exact remaining action when verification fails or a restart is pending. Continue implementing without MCP when normal CLI access is sufficient. Do not enable broad production access by default.
Start Sites only after the backend-readiness gate passes. Resolve the expected port from the existing dev command or configuration; the stock Vinext starter expects 3000. Inspect retained sessions and only that intended port:
If Sites was started before Convex wrote .env.local, stop it and restart it exactly once after NEXT_PUBLIC_CONVEX_URL exists. Environment variables are captured when the client bundle starts; a running server will not reliably pick up a newly created public URL.
When .env.local, dependencies, and hosting configuration change together, allow those changes to settle and perform one clean restart. Treat JSON parse errors, overlapping Vite restarts, fallback ports, multiple-renderer warnings, and worker errors appearing in that window as one cascading server-state failure until the clean restart proves otherwise.
Capture the exact Local URL printed by the healthy server. Allow up to 60 seconds for the first worker compilation, then run scripts/check-local-url.sh EXACT_LOCAL_URL EXPECTED_PORT. Do not substitute a guessed URL or accept a successful response from another port. For local-only work, keep one healthy Sites server and one interactive Convex server running through handoff unless the user asks to stop them. If the execution surface cannot preserve long-running processes, state that limitation and give the exact command the user must keep running. Explain that localhost works only on that computer and only while the development server remains alive. Never describe localhost as published or shareable.
Before building a large data-driven product, create the smallest vertical slice:
ConvexProvider.Validate locally, then publish this slice when publishing is authorized. Confirm the published origin can make HTTPS and WebSocket connections to Convex. If Content Security Policy, CORS, WebSocket, or mixed-content restrictions block it, stop and report the exact evidence. Do not disguise the failure with local-only success.
Propose schema changes before implementing them. Then build the smallest coherent product:
schema.ts, validators, and explicit indexes.api.module.functionName references.useQuery for reactive reads and useMutation for writes.NEXT_PUBLIC_CONVEX_URL is missing. Render a clear configuration/setup state and construct ConvexReactClient only after a valid URL exists.Add the removable “Built with ChatGPT Sites + Convex” footer from references/built-with-footer.md unless the user explicitly asks to omit or remove it. Use the bundled light and dark logo assets, follow the Site's resolved theme, use the Phosphor GitHub logo for the repository link, link each brand to its official site, and preserve the removal comment in source code.
Run the project scripts that exist, plus the applicable checks:
npx convex dev --once
npx convex codegen
npm run build
Run lint and a separate type check when defined. Use scripts/verify-project.sh for local structural checks, or scripts/verify-project.sh --publish when publication was requested. Review changed Convex functions for validators, authentication, public/internal visibility, indexes, pagination, bounded reads, and mutation conflicts.
Run scripts/check-runtime.sh again before final Node-based checks. For local preview work, verify the exact expected URL returns HTTP success while the server remains running. When the shell runtime changed, perform the final runtime verification in a new login shell so the fix survives the next terminal session.
For a new project, configure the official @convex-dev/eslint-plugin recommended rules and ensure lint checks the actual Convex directory. For an existing project, preserve its ESLint format and extend a compatible configuration; do not replace unrelated rules or silently migrate configuration formats. If the existing project has no ESLint setup, recommend the plugin and report lint as not configured rather than failing solely for its absence. Follow references/helpers-and-eslint.md and the current official ESLint documentation.
Fix failures and rerun the failing check. Do not declare completion from a local UI preview alone.
After the local production build passes, inspect .openai/hosting.json. If publication was requested and no valid project_id exists, call create_site exactly once through the Sites hosting workflow and persist the returned project_id. Call get_site to confirm the registration before starting or resuming Convex production setup. Check list_sites or the Sites UI separately for sidebar visibility.
This checkpoint registers the Site only. Do not claim that a Sites version was saved or that the Site was published. If get_site succeeds but the Site is not listed yet, preserve the existing project_id, do not call create_site again, report Registered Site; sidebar indexing pending, and ask the user to refresh or reopen Sites. Report Registered Site as the last completed lifecycle state and name the next required Convex action.
If a hydration warning mentions attributes injected by Grammarly or another browser extension, verify once in a clean Chrome profile or with extensions disabled. Do not change application code when the warning disappears and the server-rendered markup otherwise matches.
Read and follow references/deployment-and-qa.md completely.
Deployment order: Convex backend → production Convex URL → Sites production build → Sites publish → URL and access verification.
The complete durable-publication lifecycle is:
project_id, then call get_site.access_level, latest_version_number, current_live_url, Sites environment-variable names, and the frontend's current Convex URL without displaying credentials.npx convex deploy, obtain fresh, target-specific production authorization even when Sites access is already public.convex.cloud URL.NEXT_PUBLIC_CONVEX_URL as non-secret public configuration. Never put a deploy key, admin key, or backend secret in Sites public environment variables.scripts/check-production-bundle.sh BUILD_DIR PRODUCTION_URL DEVELOPMENT_URL; fail if the bundle contains localhost, the development URL, a deployment key marker, or lacks the exact production URL.save_site_version once for that build.get_deployment_status until success or failure.url, call get_site, and require current_live_url to be nonempty and match the deployment URL.For an existing frontend-only update, do not redeploy an unchanged Convex backend. Confirm the current production deployment and exact URL, then continue with the clean production build, bundle scan, exact source commit, Sites version save, deployment, canonical URL check, and live QA. If any Convex backend behavior or configuration changed, use the full production deployment and fresh-consent steps above.
Before publishing, resolve whether the Site should be public or require sign-in. Default to private when the user has not requested public access. Explain the resolved access mode and obtain explicit authorization before changing to public or changing any access list. Public access is an access policy, not a deployment, and never proves that the Site is published.
An accountless local backend cannot power a published Site. Before production deployment, confirm the intended Convex team, project, production deployment, and authorized account or production-scoped key. Obtain fresh consent immediately before every production deployment. Reject any production bundle containing localhost, 127.0.0.1, a local URL, an unintended development deployment, or a deployment credential.
Treat this recovery state as registered and public but unpublished: valid project_id, access_level: public, latest_version_number: 0, current_live_url: null, no Sites environment variables, and a frontend still targeting accountless local Convex. Preserve public access, but complete cloud linking, fresh production authorization, production deployment, Sites public configuration, clean rebuild and scan, exact-commit save and deploy, live URL confirmation, and production QA. Use scripts/check-publication-state.sh with a normalized state file when diagnosing this case.
For an explicitly requested temporary shared preview, follow the Cloud Agent Mode path in references/agent-mode.md and references/deployment-and-qa.md. Confirm the team and project; reuse only a suitable isolated cloud dev deployment or create one with an explicit expiration; use only deployment-scoped access; configure its environment; push with npx convex dev --once; and build Sites with its public convex.cloud URL. Confirm Sites access before publishing. Never expose the deploy key, call the backend production, or imply that preview data automatically transfers to production.
Call save_site_version once for the production build, then deploy that saved version. Poll the Sites deployment to success or failure and retain its exact returned url, but report the Site as published only after get_site.current_live_url is nonempty and matches that URL. Open the confirmed live URL in Codex and make its clickable link the first item in the final answer. For an existing Site, read project_id from .openai/hosting.json, call get_site, and treat current_live_url as canonical; never reconstruct a URL from a slug.
If work stops at any point, report the last completed state using the four state names above and the single next required action. Never upgrade the wording from local, registered, or saved to published without a confirmed get_site.current_live_url.
Every published handoff must explain how to reopen the Site in ChatGPT Sites and manage it through Settings. Hosted Site management is not available through a standalone Codex CLI or IDE screen.
Every successful first-publication and update handoff must include this exact instruction:
For future updates, ask Codex:
$codex-sites-convex Build, validate, and publish the latest version to ChatGPT Sites.
Every temporary-preview handoff must begin with the live Sites URL and label Temporary shared preview. Report the exact Convex deployment expiration, Sites access mode, visitor sign-in requirements, whether data is shared or isolated, what fails after expiration, and the steps required to promote to production.
Do not enable production MCP writes, generate a sign-in bypass token, make a Site public, or add users or groups unless the user explicitly authorizes that action.
Finish only when:
dev, build, and start, and any runtime repair survives a fresh login shell;convex-helpers utility was selected for a named need rather than installed speculatively;$codex-sites-convex invocation so a new user reliably activates this skill;