Environment variables

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

Variable	Used by	Notes
`APP_BASE_URL`	Convex	Public web app URL used for redirects such as Google Calendar OAuth.
`SITE_URL`	Convex	Public web app URL used by auth and billing links.
`CONVEX_URL`	Server/runtime, web build	Convex deployment URL. Also exposed to the React dashboard by Vite.
`CONVEX_SITE_URL`	Server/runtime, web build	Convex HTTP actions URL. Also exposed to the React dashboard by Vite.
`VOICE_GATEWAY_BASE_URL`	Convex, voice gateway	Public HTTPS URL for the voice gateway.
`INTERNAL_SERVICE_TOKEN`	Convex, voice gateway	Shared secret for internal HTTP calls between the voice gateway and Convex.
`DASHBOARD_TEST_CALL_TOKEN`	Convex, voice gateway	Optional shared token for elevated dashboard test-call rate limits from verified internal paths. Do not expose this through public widget requests.
`SESSION_ENCRYPTION_KEY`	Convex	Required for encrypted Google Calendar token storage.
`DEPLOYMENT_MODE`	Convex, voice gateway	Deployment 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

Variable	Used by	Notes
`CONVEX_SELF_HOSTED_URL`	Host 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_KEY`	Host CLI	Generated with `generate_admin_key.sh` inside the `convex-backend` container.
`INSTANCE_SECRET`	Convex backend container	Hex secret for the open-source backend. Generate with `pnpm self-hosted:secrets`. Placeholder values break backend startup.
`CONVEX_CLOUD_ORIGIN`	Convex backend container	Must exactly match `CONVEX_URL`. `pnpm self-hosted:convex:env` and `pnpm self-hosted:verify` reject mismatches.
`CONVEX_SITE_ORIGIN`	Convex backend container	Must 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

Variable	Default	Notes
`WEB_PORT`	`8080`	Local bind for web dashboard (`127.0.0.1`).
`VOICE_GATEWAY_PORT`	`3001`	Local bind for voice gateway.
`CONVEX_PORT`	`3210`	Local bind for Convex client API.
`CONVEX_SITE_PROXY_PORT`	`3211`	Local bind for Convex HTTP actions proxy.
`CONVEX_DASHBOARD_PORT`	`6791`	Local bind for Convex dashboard.
`HTTP_PORT`	`80`	Caddy HTTP ingress on the host.
`HTTPS_PORT`	`443`	Caddy HTTPS ingress on the host.
`CADDY_BIND_ADDRESS`	`127.0.0.1`	Host bind address for Caddy ingress. Use `0.0.0.0` before exposing public HTTPS traffic.
`COMPOSE_PROJECT_NAME`	`lobbystack`	Docker Compose project name; change to run multiple stacks on one host.

Caddy hostnames

Variable	Notes
`APP_HOSTNAME`	Public hostname routed to the web dashboard.
`VOICE_HOSTNAME`	Public hostname routed to the voice gateway.
`CONVEX_HOSTNAME`	Public hostname routed to Convex client port `3210`.
`CONVEX_SITE_HOSTNAME`	Public hostname routed to Convex HTTP actions port `3211`.
`ACME_EMAIL`	Email 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:

Variable	Purpose
`SELF_HOSTED_WEB_VERIFY_URL`	Base URL for web checks (default `http://127.0.0.1:${WEB_PORT}`).
`SELF_HOSTED_VOICE_VERIFY_URL`	Base URL for voice gateway checks.
`SELF_HOSTED_CONVEX_VERIFY_URL`	Base URL for Convex `/version`.
`SELF_HOSTED_CONVEX_SITE_VERIFY_URL`	Base URL for Convex HTTP action checks.
`SELF_HOSTED_DASHBOARD_VERIFY_URL`	Base 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

Variable	Notes
`VITE_APP_NAME`	Display name; defaults to LobbyStack in `.env.example`.
`VITE_DEPLOYMENT_MODE`	Client-side deployment mode label.
`VITE_POSTHOG_KEY`, `VITE_POSTHOG_HOST`, `VITE_POSTHOG_UI_HOST`	Optional web analytics settings.
`VITE_WEB_CALL_ENDPOINT`	Required for self-hosting. Set this to your voice gateway session endpoint, for example `${VOICE_GATEWAY_BASE_URL}/web-call/sessions`.

Voice gateway

Variable	Notes
`PORT`	Port the voice gateway listens on. Defaults to `3001`.
`WEB_CALL_ALLOWED_ORIGINS`	Comma-separated browser origins allowed to start in-dashboard web calls. Must include the exact web URL operators use, such as `https://app.lobbystack.com` for the dashboard.
`OPENAI_API_KEY`	Required for live OpenAI Realtime voice calls.
`OPENAI_REALTIME_MODEL`	Defaults to `gpt-realtime`.
`OPENAI_REALTIME_VOICE`	Defaults to `marin`.
`OPENAI_TRANSCRIPTION_MODEL`	Defaults to `gpt-4o-mini-transcribe`.

Optional OpenAI cost fallback variables exist in .env.example for telemetry when automatic model pricing is unavailable.

Twilio

Variable	Notes
`TWILIO_ACCOUNT_SID`	Twilio account SID.
`TWILIO_AUTH_TOKEN`	Twilio auth token.
`TWILIO_VERIFY_SERVICE_SID`	Required for onboarding phone verification.
`TWILIO_ALERT_SMS_FROM`	Shared hosted alert SMS sender or messaging service SID.
`TWILIO_API_KEY`, `TWILIO_API_SECRET`, `TWILIO_MESSAGING_SERVICE_SID`	Present 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_MS`	Optional A2P registration tuning for self-hosted Convex deployments.

Google Calendar

Variable	Notes
`GOOGLE_CLIENT_ID`	Google OAuth client ID.
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret.
`GOOGLE_REDIRECT_URI`	Optional if `CONVEX_SITE_URL` can derive `/integrations/google/callback`.

Google Calendar token storage also requires SESSION_ENCRYPTION_KEY.

Knowledge and AI text providers

Variable	Notes
`FIRECRAWL_API_KEY`	Enables website import.
`GOOGLE_GENERATIVE_AI_API_KEY`	Enables Gemini text and embeddings.
`GEMINI_TEXT_MODEL`	Defaults to `gemini-3.1-flash-lite-preview`.
`GEMINI_EMBEDDING_MODEL`	Defaults to `gemini-embedding-001`.

SMS compliance

Variable	Notes
`TWILIO_PRIMARY_CUSTOMER_PROFILE_SID`	Required for hosted 10DLC registration.
`TWILIO_A2P_STATUS_EMAIL`	Required for hosted 10DLC registration callbacks.

Email

Variable	Notes
`RESEND_API_KEY`	Sends password reset and email-change emails.
`EMAIL_FROM_ADDRESS`	Verified sender address used by auth emails.

Telemetry

Variable	Notes
`POSTHOG_KEY`, `POSTHOG_HOST`	Backend telemetry.
`POSTHOG_PRIVACY_MODE`	Privacy-mode toggle in `.env.example`.

Get started

General

Agent

Manage

Self-hosting

Environment variables

Shared app URLs and secrets

Docker Compose self-hosting

Convex CLI and backend container

Host ports and ingress

Caddy hostnames

Smoke verification overrides

Web dashboard build variables

Voice gateway

Twilio

Google Calendar

Knowledge and AI text providers

SMS compliance

Email

Telemetry

​Shared app URLs and secrets

​Docker Compose self-hosting

​Convex CLI and backend container

​Host ports and ingress

​Caddy hostnames

​Smoke verification overrides

​Web dashboard build variables

​Voice gateway

​Twilio

​Google Calendar

​Knowledge and AI text providers

​SMS compliance

​Email

​Telemetry

Shared app URLs and secrets

Docker Compose self-hosting

Convex CLI and backend container

Host ports and ingress

Caddy hostnames

Smoke verification overrides

Web dashboard build variables

Voice gateway

Twilio

Google Calendar

Knowledge and AI text providers

SMS compliance

Email

Telemetry