Configuration

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

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

Every stored credential records which key encrypted it, so a rotation doesn't have to happen all at once:

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.

At least one provider is required for Elmo to track visibility. See Providers for a full cost/capability breakdown and recommended setups.

Brand onboarding and the Opportunities report also need one direct LLM API key — OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or MISTRAL_API_KEY — even if SCRAPE_TARGETS only uses scrapers. Elmo uses the first of those that's set; to pick one explicitly, set ONBOARDING_LLM_TARGET (e.g. claude:anthropic-api).

Elmo uses Jev from TypeSafe to read each answer. Jev decides which tracked companies the answer really mentions, its sentiment toward each one, and the passage that shows it. The worker won't start without a key for Jev: either a TypeSafe key from console.typesafe.ai, or an OPENROUTER_API_KEY, which calls Jev through OpenRouter and bills your OpenRouter account.

elmo init asks which one to use, offering the OpenRouter key you entered for onboarding if there is one. If you add an OpenRouter key just for Jev, it also pins ONBOARDING_LLM_TARGET to the provider you chose for onboarding, which OpenRouter would otherwise take over from Anthropic or Mistral. elmo upgrade asks the same before it stops anything when .env has neither key, or only an OpenRouter key on a deployment from before Jev; it can't see a key saved only in Elmo's settings.

Elmo makes one Jev call for each answer that names a tracked company. Answers that name none are never sent. Its cost grows with the answer's length and with how many tracked companies it names.

Very roughly, that's $0.15–0.35 per 1,000 answers. A month of answers is about prompts × platforms × RUNS_PER_PROMPT × 30 when prompts run daily:

These are estimates, not quotes; see TypeSafe's pricing, or OpenRouter's for Jev, for current rates.

The worker picks TypeSafe or OpenRouter when it starts, and never falls back from one to the other. Both serve the same Jev release, so switching keeps the judgements you already have; only a new Jev version in an Elmo release re-judges history. OpenRouter serves Jev 1.13 from a dated snapshot that it may update to a newer 1.13 one, and runs requests over about 32 KB in Jev's long-context mode, so long answers may be judged slightly differently there.

A large re-judge goes as fast as your TypeSafe or OpenRouter rate limit allows, with nothing to configure. Each worker finds the limit itself: it speeds up while calls succeed, slows down when Jev rate-limits it, and retries those calls after the wait Jev asks for. For example, with a 100,000 input tokens per second limit, one worker judges about a million answers in roughly 16 hours.

When the judge's version, or a brand's or competitor's names, change, the worker re-judges that brand's history in the background, starting with the last 30 days. A re-judge only goes back REPROCESS_DAYS, and only through enabled prompts of enabled brands. Older answers keep how they were judged when they were recorded. A prompt or brand that's enabled again has its answers within the window caught up at that point. Re-judging only asks about what changed. Adding a competitor, or editing one's names, aliases or domains, asks Jev about that company alone, and only in answers that name it. That costs a fraction of judging those answers from scratch. Removing a competitor asks nothing. Edits made within a minute of each other are handled in one pass. A new judge version re-judges everything in the window, so it costs about REPROCESS_DAYS worth of answers: at the default, roughly three months of the figures above.

To change environment variables after initial setup:

elmo init asks how you'll access Elmo. Choose From a domain and enter it (for example elmo.example.com, which becomes https://elmo.example.com), then point your reverse proxy at the port you pick. Sign-in is only accepted from the configured URL.

To change it later, run elmo edit env, set both APP_URL and VITE_APP_URL to the new URL (for example https://elmo.example.com), then restart with elmo compose up -d. Elmo must be served from the root of its domain, not a subpath.

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.

elmo init provisions Postgres 18. elmo upgrade rolls the Elmo images but never touches the Postgres container, so a deployment created on an earlier major keeps running on it — supported, and nothing you have to act on. Postgres 16 gets fixes until November 2028.

If you do want to move, Postgres cannot read a data directory written by a different major version, so it takes a dump and restore.

Take a dump while the old container is still running:

Check that elmo-backup.sql is non-empty and ends with -- PostgreSQL database dump complete before continuing. Then edit the Postgres service with elmo edit compose, changing both the image and the mount path:

Now restore. Postgres 18 finds no cluster at its new path, initializes an empty one alongside the old files, and the dump goes into that:

Bringing up postgres on its own first matters: it keeps db-migrate from initializing an empty schema ahead of the restore.

Nothing is destroyed along the way: the old cluster stays in the volume, unused, so you can roll back by putting the original image and /var/lib/postgresql/data mount back. Keep elmo-backup.sql either way.