Configuration

Environment variables, deployment modes, and advanced configuration options.

Deployment Modes

Elmo supports several deployment modes, controlled by the DEPLOYMENT_MODE environment variable:

Mode	Description
`local`	Single-org, email/password auth. Best for individual use. (default)
`demo`	Read-only mode for showcasing Elmo without allowing changes.
`whitelabel`	Multi-org with Auth0 SSO. Deploy under your own brand. See White Label.
`cloud`	Managed hosting (coming soon).

When you run elmo init, the CLI generates a .env file in your config directory. You can edit this file directly to change settings.

Variable	Description	Default
`DEPLOYMENT_MODE`	Deployment mode	`local`
`DATABASE_URL`	PostgreSQL connection string	Generated by CLI
`BETTER_AUTH_SECRET`	Secret key for session encryption	Auto-generated
`DISABLE_TELEMETRY`	Set to `1` to disable all telemetry	—

At least one AI provider is required for Elmo to track visibility.

Variable	Description
`OPENAI_API_KEY`	OpenAI API key — enables ChatGPT tracking with web search
`ANTHROPIC_API_KEY`	Anthropic API key — enables Claude tracking
`DATAFORSEO_LOGIN`	DataForSEO login — enables Google AI Overviews tracking
`DATAFORSEO_PASSWORD`	DataForSEO password

These variables customize the UI when running in whitelabel mode:

Variable	Description
`VITE_APP_NAME`	Application name displayed in the UI
`VITE_APP_ICON`	URL to your app icon
`VITE_APP_URL`	Your deployment URL
`VITE_APP_PARENT_NAME`	Your agency/company name
`VITE_APP_PARENT_URL`	Your agency/company URL
`VITE_CHART_COLORS`	Comma-separated hex colors for charts

Required when DEPLOYMENT_MODE=whitelabel:

Variable	Description
`VITE_AUTH0_DOMAIN`	Auth0 tenant domain
`VITE_AUTH0_CLIENT_ID`	Auth0 client ID (public)
`AUTH0_DOMAIN`	Auth0 tenant domain (server-side)
`AUTH0_CLIENT_ID`	Auth0 client ID (server-side)
`AUTH0_CLIENT_SECRET`	Auth0 client secret

To change environment variables after initial setup:

# Edit the .env file
nano ./elmo/.env

# Restart services to pick up changes
elmo stop
elmo start

If you need to regenerate the elmo.yaml file (e.g. after changing Postgres mode):

elmo regen

This rebuilds elmo.yaml from your current settings without touching .env.

By default, elmo init provisions a PostgreSQL container. To use an existing database instead:

Choose "Use existing Postgres" during elmo init, or

Edit .env to set DATABASE_URL to your connection string

Run elmo regen to update elmo.yaml (removes the Postgres container)

Restart with elmo stop && elmo start

Your database must be PostgreSQL 15 or later.

Elmo collects anonymous usage data to help improve the product. This includes CLI install events and web app usage metrics.

To disable all telemetry:

DISABLE_TELEMETRY=1

Add this to your .env file, or export it in your shell before running CLI commands.

Was this page helpful?