This page covers environment variables for ARMS instances you already run. Public self-host install steps are not published here — for on-premises or private deployments, contact dev@elsaifoundry.com.

There are two namespaces. Do not mix them.

Namespace	Process	Examples
SDK / your app	Application instrumented with elsai-arms	ELSAI_ARMS_*, OTEL_EXPORTER_OTLP_*
ARMS server	apps/web and apps/api (repo-root Compose)	DATABASE_URL, ELSAI_CRON_SECRET, ELSAI_VAULT_ENCRYPTION_KEY

Telemetry vs platform HTTP (SDK)

Use	URL	Authentication
Telemetry	https://<arms-host>/api/ingest	otlp_headers / OTEL_EXPORTER_OTLP_HEADERS (x-api-key)
Vault / evals	ELSAI_ARMS_URL (base URL)	ELSAI_ARMS_API_KEY as Authorization: Bearer

ELSAI_ARMS_API_KEY does not authenticate OTLP. See SDK configuration and ARMS destination.

---

Application metadata (PostgreSQL)

ARMS stores users, organisations, projects, sessions, and API keys in PostgreSQL, not SQLite.

DATABASE_URLrequired

Postgres connection string for the API (apps/api).

export DATABASE_URL=postgresql://user:pass@host:5432/elsaiobserve

DB_SSL

Set to true to enable TLS for the Postgres pool (rejectUnauthorized: false).

export DB_SSL=true

SQLITE_DATABASE_URL is not the application database.

ClickHouse / collector (INIT_DB_*)

INIT_DB_HOST, INIT_DB_PORT, INIT_DB_DATABASE, INIT_DB_USERNAME, and INIT_DB_PASSWORD configure ClickHouse for the OpenTelemetry collector write path and API telemetry reads. They are not SQLite and not DATABASE_URL.

The collector’s OTLP ports 4317/4318 stay internal. SDKs send to /api/ingest.

Authentication / session

ARMS uses email and password (see Authentication). NEXTAUTH_SECRET must be identical on apps/web and apps/api.

NEXTAUTH_URL

Canonical URL of the UI.

export NEXTAUTH_URL=http://localhost:3000

NEXTAUTH_SECRET

Encrypts NextAuth session tokens. Also used as a Vault encryption fallback when ELSAI_VAULT_ENCRYPTION_KEY is unset.

export NEXTAUTH_SECRET=your-secret-here

Generate with: openssl rand -base64 32

SESSION_MAX_AGE_SECONDS

Session lifetime in seconds. Compose default is 604800 (7 days).

LOGIN_RATELIMIT_MAX_ATTEMPTS

Max failed login attempts per window. Default 5.

LOGIN_RATELIMIT_WINDOW_MS

Login rate-limit window in milliseconds. Default 900000 (15 minutes).

Server

PORT

Host port for Docker Compose. The container listens on DOCKER_PORT (default 3000).

API_URL

Base URL the API uses for cron jobs (Auto Evaluation, Auto Pricing, Agents materialization). Defaults to http://localhost:$PORT. Set this behind a reverse proxy.

export API_URL=https://observe-api.example.com

Cron (required)

ELSAI_CRON_SECRETrequired

Secret sent as header X-CRON-JOB. Required. If unset, cron routes fail closed (Auto Evaluation, Auto Pricing, Agents materialize are refused). There is no shared default.

export ELSAI_CRON_SECRET=your-cron-secret

Vault and CORS (server)

ELSAI_VAULT_ENCRYPTION_KEY

AES-256-GCM key for Vault values. Falls back to NEXTAUTH_SECRET. Changing it after secrets exist prevents decrypt.

export ELSAI_VAULT_ENCRYPTION_KEY=your-vault-encryption-key

ELSAI_ALLOWED_CORS_ORIGINS

Comma-separated browser origins allowed to call POST /api/vault/get-secrets. Do not use *.

export ELSAI_ALLOWED_CORS_ORIGINS=https://app.example.com,https://admin.example.com

ELSAI_ALLOWED_ORIGINS

Alias for ELSAI_ALLOWED_CORS_ORIGINS. NEXTAUTH_URL is also treated as an allowed origin.

ELSAI_REQUIRE_ORG_FILTER

Set true or 1 to enforce organisation-scoped isolation on telemetry queries.

Agents materialization

AGENTS_MATERIALIZE_SCHEDULE

Cron for the Agents materialization job. Default * * * * *.

AGENTS_MATERIALIZE_MAX_PER_TICK

Max agents per run. Default 100.

AGENTS_MATERIALIZE_PARALLEL

Max concurrent materializations. Default 4.

Anonymous product telemetry

See Anonymous Telemetry. Set TELEMETRY_ENABLED=false to opt out.

Environment file placement

• Development: apps/web/.env and apps/api/.env
• Docker Compose: .env next to the repository-root docker-compose.yml (or docker-compose.split.yml)
• ARMS reads env at process start — restart after changes. Cron jobs are re-created on startup from the current environment.

Sample .env (server)

DATABASE_URL=postgresql://user:pass@host:5432/elsaiobserve
DB_SSL=false
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-here
API_URL=http://localhost:3000
ELSAI_CRON_SECRET=your-cron-secret
ELSAI_VAULT_ENCRYPTION_KEY=your-vault-encryption-key
INIT_DB_HOST=clickhouse
INIT_DB_PORT=8123
INIT_DB_DATABASE=elsai_arms
INIT_DB_USERNAME=default
INIT_DB_PASSWORD=change-me
TELEMETRY_ENABLED=true