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. |
cloud | Managed hosting (coming soon). |
Environment Variables
When you run elmo init, the CLI generates a .env file in your config directory. You can edit this file directly to change settings.
Core 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 |
ELMO_ENCRYPTION_KEY | Base64-encoded 32-byte key used to encrypt provider credentials stored in the database | Auto-generated |
ELMO_ENCRYPTION_KEY_OLD | Previous encryption keys, comma-separated, kept readable during a rotation | — |
DISABLE_TELEMETRY | Set to 1 to disable all telemetry. See Telemetry. | — |
DEFAULT_DELAY_HOURS | How often each enabled prompt is re-run against the AI models, in hours. | 24 |
Back up ELMO_ENCRYPTION_KEY alongside your database. Credentials stored in the database are encrypted with it and nothing else — if you lose the key, or restore a database backup onto a deployment that generated a different one, those credentials cannot be recovered and have to be entered again. Elmo logs an error and falls back to the provider keys in your .env when a stored credential will not decrypt.
Rotating the encryption key
Every stored credential records which key encrypted it, so a rotation doesn't have to happen all at once:
- Move the current value of
ELMO_ENCRYPTION_KEYintoELMO_ENCRYPTION_KEY_OLD. - Put a freshly generated key in
ELMO_ENCRYPTION_KEY(openssl rand -base64 32), and restart.
New values are encrypted under the new key while anything saved under a retired one stays readable, so nothing has to be re-entered up front. Drop ELMO_ENCRYPTION_KEY_OLD once every stored credential has been saved again — until then, keep it, or those credentials become unreadable and Elmo logs which key it is missing.
DEFAULT_DELAY_HOURS only takes effect for prompts scheduled after you change it. Prompts that are already scheduled keep the cadence they were created with, even after a restart. To apply a new cadence to an existing prompt, disable it and then re-enable it under Settings → Prompts — re-enabling reschedules it at the current DEFAULT_DELAY_HOURS.
AI Provider Keys
At least one provider is required for Elmo to track visibility. See Providers for a full cost/capability breakdown and recommended setups.
| Variable | Description |
|---|---|
BRIGHTDATA_API_TOKEN | BrightData token — recommended scraper for ChatGPT + Google AI Mode. Sign up |
OXYLABS_USERNAME | Oxylabs Web Scraper API username — alternative scraper for ChatGPT, Perplexity, Google AI Mode. Sign up |
OXYLABS_PASSWORD | Oxylabs Web Scraper API password |
OLOSTEP_API_KEY | Olostep key — recommended scraper, powers most large-scale trackers. Sign up |
OPENAI_API_KEY | OpenAI API key — enables ChatGPT (via API, not the consumer UI) |
ANTHROPIC_API_KEY | Anthropic API key — enables Claude tracking |
OPENROUTER_API_KEY | OpenRouter key — one key for Claude + other hosted models |
DATAFORSEO_LOGIN | DataForSEO login — optional, enables DataForSEO targets such as google-ai-mode:dataforseo:online, chatgpt:dataforseo:online, perplexity:dataforseo:online, and gemini:dataforseo:online |
DATAFORSEO_PASSWORD | DataForSEO password |
SCRAPE_TARGETS | Comma-separated model:provider[:version][:online] entries. See Providers. |
Updating Configuration
To change environment variables after initial setup:
# Edit the .env file
nano ~/.elmo/.env
# Restart services to pick up changes
elmo compose down
elmo compose up -dUsing an External Database
By default, elmo init provisions a PostgreSQL container. To use an existing database instead, choose "Use existing Postgres" during elmo init and provide your connection string when prompted.
Your database must be PostgreSQL 15 or later.
Was this page helpful?