Skip to main content
Use the repository’s .env.example as the source of truth for local development and .env.self-hosted.example as the source of truth for Docker Compose self-hosting. This page summarizes the variables operators most often need to understand.
Secrets such as provider API keys, auth tokens, signing keys, and encryption keys must be configured only in backend or deployment secret stores. Do not expose them through VITE_ variables.

​
Shared app URLs and secrets

VariableUsed byNotes
APP_BASE_URLConvexPublic web app URL used for redirects such as Google Calendar OAuth.
SITE_URLConvexPublic web app URL used by auth and billing links.
CONVEX_URLServer/runtime, web buildConvex deployment URL. Also exposed to the React dashboard by Vite.
CONVEX_SITE_URLServer/runtime, web buildConvex HTTP actions URL. Also exposed to the React dashboard by Vite.
VOICE_GATEWAY_BASE_URLConvex, voice gatewayPublic HTTPS URL for the voice gateway.
INTERNAL_SERVICE_TOKENConvex, voice gatewayShared secret for internal HTTP calls between the voice gateway and Convex.
SESSION_ENCRYPTION_KEYConvexRequired for encrypted Google Calendar token storage.
DEPLOYMENT_MODEConvex, voice gatewayDeployment mode label used by runtime and telemetry.
For Compose self-hosting, use DEPLOYMENT_MODE=self_hosted_standard and mirror it into VITE_DEPLOYMENT_MODE before rebuilding the web image.

​
Docker Compose self-hosting

These variables are defined in .env.self-hosted.example and used by docker-compose.self-hosted.yml. See the Docker Compose guide for bootstrap and go-live steps.

​
Convex CLI and backend container

VariableUsed byNotes
CONVEX_SELF_HOSTED_URLHost CLI (pnpm self-hosted:convex:*)URL the Convex CLI uses to reach your self-hosted backend, typically http://127.0.0.1:3210 during local smoke.
CONVEX_SELF_HOSTED_ADMIN_KEYHost CLIGenerated with generate_admin_key.sh inside the convex-backend container.
INSTANCE_SECRETConvex backend containerHex secret for the open-source backend. Generate with pnpm self-hosted:secrets. Placeholder values break backend startup.
CONVEX_CLOUD_ORIGINConvex backend containerMust exactly match CONVEX_URL. pnpm self-hosted:convex:env and pnpm self-hosted:verify reject mismatches.
CONVEX_SITE_ORIGINConvex backend containerMust exactly match CONVEX_SITE_URL.
The voice gateway always uses the internal Docker URL http://convex-backend:3211 for Convex HTTP actions. Keep CONVEX_SITE_URL in .env.self-hosted as the public or browser-facing URL; pnpm self-hosted:convex:env syncs that value into the Convex deployment for webhooks and auth.

​
Host ports and ingress

VariableDefaultNotes
WEB_PORT8080Local bind for web dashboard (127.0.0.1).
VOICE_GATEWAY_PORT3001Local bind for voice gateway.
CONVEX_PORT3210Local bind for Convex client API.
CONVEX_SITE_PROXY_PORT3211Local bind for Convex HTTP actions proxy.
CONVEX_DASHBOARD_PORT6791Local bind for Convex dashboard.
HTTP_PORT80Caddy HTTP ingress on the host.
HTTPS_PORT443Caddy HTTPS ingress on the host.
CADDY_BIND_ADDRESS127.0.0.1Host bind address for Caddy ingress. Use 0.0.0.0 before exposing public HTTPS traffic.
COMPOSE_PROJECT_NAMElobbystackDocker Compose project name; change to run multiple stacks on one host.

​
Caddy hostnames

VariableNotes
APP_HOSTNAMEPublic hostname routed to the web dashboard.
VOICE_HOSTNAMEPublic hostname routed to the voice gateway.
CONVEX_HOSTNAMEPublic hostname routed to Convex client port 3210.
CONVEX_SITE_HOSTNAMEPublic hostname routed to Convex HTTP actions port 3211.
ACME_EMAILEmail for Let’s Encrypt registration via Caddy.
Caddy routing is defined in docker/caddy/Caddyfile and baked into the Caddy image at build time.

​
Smoke verification overrides

Optional overrides for pnpm self-hosted:verify when using non-default ports:
VariablePurpose
SELF_HOSTED_WEB_VERIFY_URLBase URL for web checks (default http://127.0.0.1:${WEB_PORT}).
SELF_HOSTED_VOICE_VERIFY_URLBase URL for voice gateway checks.
SELF_HOSTED_CONVEX_VERIFY_URLBase URL for Convex /version.
SELF_HOSTED_CONVEX_SITE_VERIFY_URLBase URL for Convex HTTP action checks.
SELF_HOSTED_DASHBOARD_VERIFY_URLBase URL for dashboard reachability.
After changing public URLs (CONVEX_URL, CONVEX_SITE_URL, APP_BASE_URL, hostnames), rebuild the web image and rerun pnpm self-hosted:convex:env. See Docker Compose.

​
Web dashboard build variables

VariableNotes
VITE_APP_NAMEDisplay name; defaults to LobbyStack in .env.example.
VITE_DEPLOYMENT_MODEClient-side deployment mode label.
VITE_POSTHOG_KEY, VITE_POSTHOG_HOST, VITE_POSTHOG_UI_HOSTOptional web analytics settings.

​
Voice gateway

VariableNotes
PORTPort the voice gateway listens on. Defaults to 3001.
WEB_CALL_ALLOWED_ORIGINSComma-separated browser origins allowed to start in-dashboard web calls. Must include the exact web URL operators use.
OPENAI_API_KEYRequired for live OpenAI Realtime voice calls.
OPENAI_REALTIME_MODELDefaults to gpt-realtime.
OPENAI_REALTIME_VOICEDefaults to marin.
OPENAI_TRANSCRIPTION_MODELDefaults to gpt-4o-mini-transcribe.
Optional OpenAI cost fallback variables exist in .env.example for telemetry when automatic model pricing is unavailable.

​
Twilio

VariableNotes
TWILIO_ACCOUNT_SIDTwilio account SID.
TWILIO_AUTH_TOKENTwilio auth token.
TWILIO_VERIFY_SERVICE_SIDRequired for onboarding phone verification.
TWILIO_ALERT_SMS_FROMShared hosted alert SMS sender or messaging service SID.
TWILIO_API_KEY, TWILIO_API_SECRET, TWILIO_MESSAGING_SERVICE_SIDPresent in .env.example for Twilio features, but not required by every deployment path.
TWILIO_PRIMARY_CUSTOMER_PROFILE_SID, TWILIO_A2P_STATUS_EMAIL, TWILIO_A2P_TRUST_PRODUCT_POLICY_SID, TWILIO_A2P_REQUEST_DELAY_MSOptional A2P registration tuning for self-hosted Convex deployments.

​
Google Calendar

VariableNotes
GOOGLE_CLIENT_IDGoogle OAuth client ID.
GOOGLE_CLIENT_SECRETGoogle OAuth client secret.
GOOGLE_REDIRECT_URIOptional if CONVEX_SITE_URL can derive /integrations/google/callback.
Google Calendar token storage also requires SESSION_ENCRYPTION_KEY.

​
Knowledge and AI text providers

VariableNotes
FIRECRAWL_API_KEYEnables website import.
GOOGLE_GENERATIVE_AI_API_KEYEnables Gemini text and embeddings.
GEMINI_TEXT_MODELDefaults to gemini-3.1-flash-lite-preview.
GEMINI_EMBEDDING_MODELDefaults to gemini-embedding-001.

​
SMS compliance

VariableNotes
TWILIO_PRIMARY_CUSTOMER_PROFILE_SIDRequired for hosted 10DLC registration.
TWILIO_A2P_STATUS_EMAILRequired for hosted 10DLC registration callbacks.

​
Email

VariableNotes
RESEND_API_KEYSends password reset and email-change emails.
EMAIL_FROM_ADDRESSVerified sender address used by auth emails.

​
Telemetry

VariableNotes
POSTHOG_KEY, POSTHOG_HOSTBackend telemetry.
POSTHOG_PRIVACY_MODEPrivacy-mode toggle in .env.example.