Environment Variables
Complete reference for all environment variables.
Required Variables
Frontend (Vite)
# Convex deployment URL
VITE_CONVEX_URL=https://your-deployment.convex.cloud
Backend (Convex)
# WorkOS authentication
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
# WorkOS cookie encryption
WORKOS_COOKIE_PASSWORD=a-secure-32-character-or-longer-password
Optional Variables
OpenAI (for semantic search)
Variable Reference
| Variable | Required | Where | Description |
|---|
VITE_CONVEX_URL | Yes | Frontend | Convex deployment URL |
WORKOS_API_KEY | Yes | Convex | WorkOS API key |
WORKOS_CLIENT_ID | Yes | Convex + Frontend | WorkOS client ID |
WORKOS_COOKIE_PASSWORD | Yes | Frontend | Cookie encryption key |
OPENAI_API_KEY | No | Convex | OpenAI API key for embeddings |
Setting Variables
Convex
# Via CLI
npx convex env set VARIABLE_NAME value
# View current values
npx convex env list
Netlify
- Go to Site settings > Environment variables
- Click Add a variable
- Enter key and value
Vercel
- Go to Settings > Environment Variables
- Add variables for Production/Preview/Development
Local Development
Create a .env.local file in the project root:
# .env.local
VITE_CONVEX_URL=https://your-deployment.convex.cloud
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_COOKIE_PASSWORD=dev-password-at-least-32-characters
Add .env.local to .gitignore to prevent committing secrets.
Generating Secrets
For WORKOS_COOKIE_PASSWORD:
# macOS/Linux
openssl rand -base64 32
# Or use any password generator for a 32+ character string
Troubleshooting
”VITE_CONVEX_URL is undefined”
- Ensure the variable starts with
VITE_ for Vite to expose it
- Restart the dev server after adding variables
”WorkOS authentication failed”
- Verify
WORKOS_API_KEY and WORKOS_CLIENT_ID match your WorkOS dashboard
- Check that redirect URIs are configured
”Cookie not set”
WORKOS_COOKIE_PASSWORD must be at least 32 characters
