Environment variables

This page is the authoritative reference for IMP environment variables. Variables are verified against the backend source (src/ and ee/) and the frontend source. Variables in the example .env that do not match code-level names are called out explicitly. Required? means the backend throws or the feature silently fails at startup if the variable is absent. Optional means it is feature-gated or has a safe default.

Core

Variable	Required?	Component	Purpose	Example
`NODE_ENV`	No	Server, Worker	`production` enables compiled dist; any other value enables dev mode.	`production`
`PORT`	No	Server, Worker	HTTP listen port. Defaults to `9001` on the backend image, `9002` on the worker image.	`9001`
`BACKEND`	Yes	Server, Frontend	Public URL of the backend API — used in OAuth callbacks, Recall webhooks, per-trigger inbound-email webhook URLs (`/webhooks/routine/{secret}`), and tool-credential submit URLs. Must be reachable from the browser, from Recall’s servers, and from any inbound-email delivery source.	`https://api.imp.example.com`
`NEXT_BACKEND`	Yes	Frontend	Backend URL reachable from within the frontend container’s network. Use the container name when both run on the same Docker network.	`http://exulu-backend:9001`
`NEXTAUTH_URL`	Yes	Frontend	Canonical public URL for NextAuth. Set to the same value as `FRONTEND`.	`https://imp.example.com`
`NEXTAUTH_URL_INTERNAL`	No	Frontend	Backend URL for server-side NextAuth calls. Falls back to `NEXTAUTH_URL` if absent.	`http://exulu-backend:9001`
`NEXTAUTH_SECRET`	Yes	Server, Frontend	Must be identical in both. Used to sign session JWTs (frontend) and verify them + encrypt stored secrets (backend). Generate with `openssl rand -base64 32`.	`3n/afQmVBq…`
`AUTH_MODE`	No	Server, Frontend	Login mode. `password` (default) or `otp` (requires SMTP). Set in both environments with the same value.	`password`
`INTERNAL_SECRET`	No	Server	Shared secret for internal service-to-service calls using the `internal` request header. Not required for standard deployments.	`some-internal-secret`
`NPM_TOKEN`	No (legacy)	Server, Worker	Legacy Docker build argument retained in the example repo. `@exulu/backend` is published to the public npm registry — no token is required to install it. The build arg may be left empty or removed.	`npm_ku7I…`
`EXULU_ENTERPRISE_LICENSE`	Yes (EE)	Server	Enterprise Edition license key. Required to unlock queue-backed workers and EE features. Must start with `EXULU_EE_`.	`EXULU_EE_t@G0+…`

Consumer configuration

FRONTEND is a deployment-convention variable used by consumer projects and templates (e.g. exulu-example) to supply the public frontend URL for invite and notification links. It is not read by @exulu/backend itself (process.env.FRONTEND does not appear in the backend source). Set it in whichever layer of your deployment config constructs those links.

Variable	Purpose	Example
`FRONTEND`	Public URL of the frontend. Used by consumer templates for invite/notification links.	`https://imp.example.com`

Postgres

Variable	Required?	Component	Purpose	Example
`POSTGRES_DB_HOST`	Yes	Server, Worker	Hostname or IP of the Postgres server. Use `exulu-pgvector` when both run on the same Docker network.	`exulu-pgvector`
`POSTGRES_DB_PORT`	No	Server, Worker	Postgres port. Default: `5432`.	`5432`
`POSTGRES_DB_USER`	Yes	Server, Worker	Postgres user.	`postgres`
`POSTGRES_DB_PASSWORD`	Yes	Server, Worker	Postgres password.	`changeme`
`POSTGRES_DB_NAME`	No	Server, Worker	Application database name. Created automatically if absent. Default: `exulu`.	`exulu`
`POSTGRES_DB_SSL`	No	Server, Worker	Set to `true` to enable SSL (with `rejectUnauthorized: false`).	`false`

See Postgres service for connection pool settings and max_connections requirements.

Redis

Redis is required for background workers (embeddings, evals, routines). If REDIS_HOST and REDIS_PORT are absent, the server starts without worker support.

Variable	Required?	Component	Purpose	Example
`REDIS_HOST`	Yes (workers)	Server, Worker	Redis hostname.	`exulu-redis`
`REDIS_PORT`	Yes (workers)	Server, Worker	Redis port. Default: `6379`.	`6379`
`REDIS_USER`	No	Server, Worker	Redis username. Default: `""` (empty; Redis 6+ treats an empty username as the `default` ACL user).	`default`
`REDIS_PASSWORD`	No	Server, Worker	Redis password. Omit for unauthenticated Redis.	`changeme`

S3-compatible storage

IMP uses an S3-compatible bucket for file uploads (via the Uppy companion proxy). MinIO is the recommended self-hosted option.

Variable	Required?	Component	Purpose	Example
`COMPANION_S3_REGION`	Yes	Server	Bucket region. For MinIO, set this to any value (e.g., `eu-central-1`).	`eu-central-1`
`COMPANION_S3_KEY`	Yes	Server	S3 access key ID.	`minioadmin`
`COMPANION_S3_SECRET`	Yes	Server	S3 secret access key.	`U4Hq9Xm9HqVV6EB`
`COMPANION_S3_BUCKET`	Yes	Server	Bucket name. Must exist before the backend starts.	`exulu`
`COMPANION_S3_ENDPOINT`	Yes	Server	Full endpoint URL. For MinIO inside Docker: `http://exulu-minio:9000`.	`http://exulu-minio:9000`
`COMPANION_S3_PREFIX`	No	Server	Key prefix applied to all uploaded file paths. Useful when the bucket is shared with other services. Read via consumer config and Uppy upload paths.	`imp/`

The frontend also reads COMPANION_S3_ENDPOINT to construct upload URLs for the browser. Set it in both environments.

See S3 storage service for bucket creation and CORS configuration.

LiteLLM

Variable	Required?	Component	Purpose	Example
`EXULU_USE_LITELLM`	No	Server	Set to `true` to start the LiteLLM supervisor. Required for model routing, embeddings, and budgets.	`true`
`LITELLM_MASTER_KEY`	Yes (if enabled)	Server, Worker	Authentication key for the LiteLLM proxy. Backend throws at startup if `EXULU_USE_LITELLM=true` and this is absent.	`sk-01e8bf6d…`
`LITELLM_DATABASE_URL`	No	Server	Postgres connection string for LiteLLM’s dedicated database. Must be a different database from `POSTGRES_DB_NAME`. See LiteLLM service.	`postgres://postgres:pw@host:5432/litellm`
`LITELLM_CONFIG_PATH`	No	Server	Path to `config.litellm.yaml`, relative to the working directory. Default: `./config.litellm.yaml`.	`./config.litellm.yaml`
`LITELLM_HOST`	No	Server	Host the LiteLLM child process binds to. Default: `127.0.0.1`. Set to `0.0.0.0` to expose the proxy to worker containers on a separate host.	`127.0.0.1`
`LITELLM_PORT`	No	Server	Port the LiteLLM child process listens on. Default: `4000`.	`4000`

Model providers

These variables appear in config.litellm.yaml under litellm_params using LiteLLM’s os.environ/ interpolation syntax. Set them in the backend container environment so LiteLLM can read them at startup.

Variable	Required?	Component	Purpose	Example
`VERTEX_CREDENTIALS_PATH`	No	Server	Path to a Google Vertex AI service account JSON file, mounted into the container.	`./vertex-auth.json`
`COHERE_API_KEY`	No	Server	Cohere API key, used when a reranker model references `os.environ/COHERE_API_KEY`.	`sk-cohere-…`

Add other provider API keys (OpenAI, Anthropic, Azure, etc.) the same way — expose them in the container environment and reference them from config.litellm.yaml with os.environ/VARIABLE_NAME.

Transcription

Transcription requires a running Whisper server. See Whisper service.

Variable	Required?	Component	Purpose	Example
`TRANSCRIPTION_SERVER`	No	Server	HTTP URL of the Whisper transcription server. Feature is off if absent.	`http://whisper-host:9876`
`TRANSCRIPTION_MODEL`	No	Server	LiteLLM model name to use for LiteLLM-backed transcription (alternative to `TRANSCRIPTION_SERVER`). Requires `EXULU_USE_LITELLM=true`.	`whisper-1`
`WHISPER_HOST`	No	Server	Whisper server host for the embedded supervisor (when running Whisper as a child process). Default: `127.0.0.1`.	`127.0.0.1`
`WHISPER_PORT`	No	Server	Whisper server port. Default: `9876`.	`9876`
`HF_AUTH_TOKEN`	No	Whisper container	HuggingFace access token. Enables speaker diarization (pyannote). Set in the Whisper container environment, not the backend.	`hf_abc123…`
`TTS_MODEL`	No	Server	LiteLLM model name for text-to-speech. Requires `EXULU_USE_LITELLM=true`.	`tts-1`
`TTS_VOICE`	No	Server	Voice ID for TTS. Required if `TTS_MODEL` is set.	`alloy`

Claim check

Claim check (POST /claims/check) verifies an answer’s claims against the sources supplied with the request. See the Claim Check API.

Variable	Required?	Component	Purpose	Example
`CLAIM_CHECK_DEFAULT_MODEL`	No	Server	LiteLLM model name used for a claim check when the request names no `model` and no agent configuration supplies one (`claim_check.model`, the retrieval tool’s `utility_model`, or the agent’s own model). Required only for agent-less calls — an API client that posts an answer plus its own sources and names no `agent` gets HTTP 400 until this is set. Calls that name an `agent` resolve the model from its configuration and ignore this variable.	`vertex-gemini-2.5-flash`
`CLAIM_CHECK_TIMEOUT_MS`	No	Server	Request deadline for `POST /claims/check`, in milliseconds. Defaults to `60000`. A check that has not finished by this deadline is cancelled (provider calls aborted, in-flight slot released) and the caller gets `504`. A non-numeric or non-positive value is ignored and the default is used instead — the deadline is never disabled. Raise this together with `claim_check.caps.maxSentences` on an agent: a higher cap means more sentences and more provider calls, so a cap raised without a matching deadline increase just moves where the 504 lands, after the calls — and therefore their cost — have already been spent.	`120000`

Meetings (Recall)

Meeting recording via Recall.ai is optional.

Variable	Required?	Component	Purpose	Example
`RECALL_API_KEY`	No	Server	Recall.ai API key. Feature is off if absent.	`token_abc…`
`RECALL_REGION`	No	Server	Recall.ai region (`us`, `eu`, `ap`).	`eu`
`RECALL_WORKSPACE_VERIFICATION_SECRET`	No	Server	Webhook verification secret from the Recall dashboard.	`whsec_…`
`TOTAL_MAX_RECORDINGS_DURATION_PER_MONTH`	No	Server	Monthly cap on total recording minutes across all users (as a string). No limit if absent.	`1500`

SMTP

There are two separate SMTP variable namespaces. See SMTP and authentication for the full explanation. Backend variables — used by the agent email tool (SMTP_*):

Variable	Required?	Component	Purpose	Example
`SMTP_HOST`	No	Server	SMTP server hostname.	`smtp.example.com`
`SMTP_PORT`	No	Server	SMTP port. Default: `587`.	`587`
`SMTP_SECURE`	No	Server	Set to `true` for implicit TLS (port 465).	`false`
`SMTP_USER`	No	Server	SMTP username.	`user@example.com`
`SMTP_PASSWORD`	No	Server	SMTP password.	`changeme`
`SMTP_FROM`	No	Server	Default sender address for agent-sent emails.	`noreply@example.com`

The shared .env.example in the example repo lists SMTP_USERNAME, SMTP_SENDER_EMAIL, and SMTP_TLS. These names do not match what the backend code reads. Use SMTP_USER, SMTP_FROM, and SMTP_SECURE in the backend container environment.

Frontend variables — used by NextAuth for OTP sign-in emails (EMAIL_SERVER_*):

Variable	Required?	Component	Purpose	Example
`EMAIL_SERVER_HOST`	No	Frontend	SMTP host for OTP code emails.	`smtp.example.com`
`EMAIL_SERVER_PORT`	No	Frontend	SMTP port for OTP code emails.	`587`
`EMAIL_SERVER_USER`	No	Frontend	SMTP username for OTP code emails.	`user@example.com`
`EMAIL_SERVER_PASSWORD`	No	Frontend	SMTP password for OTP code emails.	`changeme`
`EMAIL_FROM`	No	Frontend	Sender address for OTP code emails.	`noreply@example.com`

Telemetry

OpenTelemetry export to SigNoz is optional. All three must be set for telemetry to initialise. See Observability.

Variable	Required?	Component	Purpose	Example
`SIGNOZ_ACCESS_TOKEN`	No	Server	SigNoz API key.	`signoz_abc…`
`SIGNOZ_TRACES_URL`	No	Server	OTLP HTTP traces endpoint.	`https://ingest.eu.signoz.cloud:443/v1/traces`
`SIGNOZ_LOGS_URL`	No	Server	OTLP HTTP logs endpoint.	`https://ingest.eu.signoz.cloud:443/v1/logs`

Sandbox

Variable	Required?	Component	Purpose	Example
`EXULU_REQUIRE_SANDBOX`	No	Server, Worker	Set to `1` to throw at the first sandboxed skill invocation if the sandbox is unavailable, instead of falling back to degraded mode. Useful for production hardening.	`1`

Guest access

These variables control the anonymous guest chat feature. All five are optional; the backend uses the defaults listed when the variables are absent.

Variable	Required?	Component	Default	Purpose	Example
`EXULU_GUEST_RATE_PER_MINUTE`	No	Server	`10`	Maximum messages a single guest IP may send within any rolling one-minute window. Exceeding this returns HTTP 429.	`20`
`EXULU_GUEST_RATE_PER_HOUR`	No	Server	`60`	Maximum messages a single guest IP may send within any rolling one-hour window. Exceeding this returns HTTP 429.	`100`
`EXULU_GUEST_MAX_MESSAGE_CHARS`	No	Server	`8000`	Maximum characters allowed in a single message part. Requests with any text part exceeding this limit are rejected.	`5000`
`EXULU_GUEST_MAX_TOTAL_CHARS`	No	Server	`32000`	Maximum total characters across all text parts in a single request. Requests whose cumulative text exceeds this limit are rejected.	`20000`
`EXULU_TRUST_PROXY`	No	Server	(unset)	Set to `true` when the backend runs behind a trusted reverse proxy that appends the real client IP to `X-Forwarded-For`. When enabled, the rate limiter uses the last entry of that header as the client IP. When unset or any value other than `true`, `X-Forwarded-For` is ignored and the raw socket address is used.	`true`

External user access

These variables control rate limiting for logged-in users with the external role (self-registered users invited to chat with specific agents). Both are optional; the backend uses the defaults listed when the variables are absent. Unlike guest rate limiting, this is keyed by user ID rather than IP, since external users are authenticated.

Variable	Required?	Component	Default	Purpose	Example
`EXULU_EXTERNAL_RATE_PER_MINUTE`	No	Server	`30`	Maximum messages a single external user may send within any rolling one-minute window. Exceeding this returns HTTP 429.	`20`
`EXULU_EXTERNAL_RATE_PER_HOUR`	No	Server	`300`	Maximum messages a single external user may send within any rolling one-hour window. Exceeding this returns HTTP 429.	`500`

Frontend-only variables

The following variables are read exclusively by the frontend container. They do not appear in the backend source.

Variable	Required?	Purpose	Example
`APP_NAME`	No	Application name used as the PWA `name` and `short_name` in the web manifest. Default: `IMP`. Read only by the manifest route. See Branding.	`Acme Agents`
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID (enables “Sign in with Google”).	`1234.apps.googleusercontent.com`
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret.	`GOCSPX-…`
`ALLOWED_EMAIL_DOMAINS`	No	Comma-separated list of email domains allowed to sign in. No restriction if absent.	`example.com,contractor.example.com`
`FEEDBACK_ENABLED`	No	Enables the in-app feedback widget.	`true`
`FEEDBACK_BACKEND`	No	Backend URL for the feedback service (separate IMP instance).	`https://feedback.imp.example.com`
`FEEDBACK_TOKEN`	No	API token for the feedback service.	`tok_…`

Debug and internal variables

These variables are read by the source but are not intended for operator configuration in normal deployments.

Variable	Component	Notes
`DEBUG`	Server	Stripped by the backend before passing the environment to the LiteLLM child process. Do not set `DEBUG` to a Node.js debug namespace pattern in the backend container — it will crash LiteLLM.
`EXULU_VS_TIMING`	Server	Enables vector-search timing logs. Dev/debugging use only.
`EXULU_ENTITY_EXTRACTION_MODEL`	Server	Overrides the entity extraction model. Advanced use; consult the operator guide for your deployment.
`LITELLM_API_KEY`	LiteLLM UI	Read by the bundled LiteLLM admin UI JavaScript. Populated automatically by the supervisor; do not set manually.
`LITELLM_UI_PATH`	Server	Internal: path where the LiteLLM UI is served. Set automatically.
`SERVER_ROOT_PATH`	Server	Root path prefix when the backend is served under a subpath. Not required for standard deployments.
`PUBLIC_API_BASE_URL`	Server	Alias for `BACKEND`, used in Recall callback URL resolution when `BACKEND` is absent. Prefer `BACKEND`.
`NEXT_PUBLIC_AGENT_VISUALIZATION`	Server	Feature flag for agent visualization UI. Set to `true` to enable.
`EXULU_KEEP_NODE_LIBLZMA`	`false`	Keep the optional `node-liblzma` package (LGPL-3.0), which the postinstall hook otherwise removes. Enables `xz` compression inside the skill sandbox.

Deploy

Services

Operate

Environment variables

Core

Consumer configuration

Postgres

Redis

S3-compatible storage

LiteLLM

Model providers

Transcription

Claim check

Meetings (Recall)

SMTP

Telemetry

Sandbox

Guest access

External user access

Frontend-only variables

Debug and internal variables

​Core

​Consumer configuration

​Postgres

​Redis

​S3-compatible storage

​LiteLLM

​Model providers

​Transcription

​Claim check

​Meetings (Recall)

​SMTP

​Telemetry

​Sandbox

​Guest access

​External user access

​Frontend-only variables

​Debug and internal variables

Core

Consumer configuration

Postgres

Redis

S3-compatible storage

LiteLLM

Model providers

Transcription

Claim check

Meetings (Recall)

SMTP

Telemetry

Sandbox

Guest access

External user access

Frontend-only variables

Debug and internal variables