difference between the following:
CONVEX_DEPLOYMENT
CONVEX_URL
CONVEX_SITE_URL
#env
tough inlet
gusty furnaceBOT
Hi @tough inlet. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Here’s how those three Convex-related environment variables differ:
CONVEX_DEPLOYMENT
- Identifies which Convex deployment your local dev tools are talking to (e.g.
dev:adjective-animal-123). - Written by
npx convex devinto.env.localduring local development. - Used by the CLI to know where to push functions in dev, and to infer the associated production deployment when you run
npx convex deploylocally.[Project config; CLI deploy]
CONVEX_URL (and framework-specific variants)
- The deployment URL your frontend client uses to connect to Convex (WebSocket + HTTP API), e.g.
<https://...convex.cloud.> - Exposed to the browser via a framework-specific env var like
VITE_CONVEX_URL,NEXT_PUBLIC_CONVEX_URL, etc., whichnpx convex devwrites into.env.local.[React URL config; Project config] - When you run
npx convex deploy --cmd 'npm run build'in CI/hosting, Convex setsCONVEX_URL(or similarly named) for your build so the frontend points at the production deployment.[CLI deploy; Netlify hosting]
CONVEX_SITE_URL
- The HTTP Actions / “site” URL for your deployment, e.g.
<https://...convex.site.> - Used for:
- Serving HTTP Actions.
- Things like webhooks and some auth configurations.
- Always available in Convex functions as
process.env.CONVEX_SITE_URL.[Env vars] - In self-hosting, it corresponds to the origin serving HTTP actions (port 3211).[Self-hosted docker]
- You can override it when using a custom HTTP Action domain.[Custom domains]
In short:
CONVEX_DEPLOYMENT: which deployment (name/id).CONVEX_URL: main backend client URL (WebSocket/API).CONVEX_SITE_URL: HTTP Actions / webhook / “.site” URL.