Environment Variables
Database
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | — | — |
POSTGRES_HOST | localhost | Individual PostgreSQL settings are an alternative to DATABASE_URL. The defaults match the local Docker setup. Replace POSTGRES_PASSWORD before deploying. |
POSTGRES_PORT | 5432 | — |
POSTGRES_DB | polyant_enterprise | — |
POSTGRES_USER | polyant_enterprise | — |
POSTGRES_PASSWORD | local-development-password | — |
POSTGRES_SSL | — | Set to “true” only when the DB enforces TLS (e.g. AWS Aurora). Leave unset for local Docker PostgreSQL. Only the literal “true” enables SSL. |
POSTGRES_CONNECT_RETRIES | — (example: 60) | Boot-time DB readiness gate (migrate step waits for the DB before migrating). Covers the Aurora-writer warm-up on a fresh deploy. Defaults: 60 retries × 2000ms. |
POSTGRES_CONNECT_RETRY_DELAY_MS | — (example: 2000) | — |
Memory
| Variable | Default | Description |
|---|---|---|
DEDUP_SIMILARITY_THRESHOLD | 0.90 | Similarity score (0 to 1) above which a memory may be considered a duplicate. Default: 0.90. |
HTTP Server (NestJS)
| Variable | Default | Description |
|---|---|---|
API_PORT | 4000 | — |
Encryption
| Variable | Default | Description |
|---|---|---|
ENCRYPTION_KEY | — | 32-byte hex-encoded key for AES-256-GCM encryption of instance secrets. Generate with: node -e “console.log(require(‘crypto’).randomBytes(32).toString(‘hex’))“ |
Authentication
| Variable | Default | Description |
|---|---|---|
AUTH_SECRET | — | Shared secret between engine and web for JWT verification (Auth.js JWE). Must be identical in both packages. Generate with: openssl rand -hex 32 |
AUTH_TRUST_HOST | true | Auth.js host trust. Required for any self-hosted deployment — including local development on http://localhost — and when running behind a reverse proxy (Render, Railway, nginx, etc.). Leave at true unless you run on a platform (e.g. Vercel) that sets the host automatically. Used by the web package, so it must also be present in packages/web/.env.local. |
Google OAuth (web only)
| Variable | Default | Description |
|---|---|---|
GOOGLE_CLIENT_ID | — | Create credentials at https://console.cloud.google.com → APIs & Services → Credentials |
GOOGLE_CLIENT_SECRET | — | — |
AUTH_ALLOWED_DOMAIN | — | Optional: restrict Google sign-in to a specific organization domain. OSS supports one domain per deployment (one domain = one org). Leave empty to allow any Google account. For production you almost certainly want to restrict this — see docs/deployment.md. Example: AUTH_ALLOWED_DOMAIN=mycompany.com |
AUTH_ALLOWED_DOMAINS | — | Legacy alias: comma-separated list of allowed domains. Still honoured and merged with AUTH_ALLOWED_DOMAIN above. Example: a.com,partner.com |
AUTH_MODE | session | Auth source for the engine’s global AuthGuard. session (default) — Auth.js JWT (cookie/Bearer) + per-instance API key. alb-oidc — trust the x-amzn-oidc-data header forwarded by an AWS ALB with OIDC. The JWT signature is NOT re-verified, so the network boundary IS the trust boundary: the ECS security group MUST restrict ingress to the ALB only. |
AUTH_ALB_SUPERADMIN_GROUP | — (example: polyant-superadmins) | In alb-oidc mode, members of this Cognito group receive the superadmin role. Change this sample value to the group configured in your identity provider. |
REMOVE_AUTHORIZATION_FILTER_FOR_TESTING | — (example: true) | RBAC PermissionGuard. Always ENFORCED here: undeclared routes and failed permission checks are denied with 403. There is no variable to turn that off in production — NODE_ENV=production ignores the escape hatch below. REMOVE_AUTHORIZATION_FILTER_FOR_TESTING=true drops the guard to SHADOW mode (every would-be denial logged as [authz] shadow: would deny …, nothing denied) and works ONLY outside production. It is a local-debugging aid: with it set every @RequirePermission is a no-op and cross-organization isolation is off, so any authenticated user reaches the whole management plane. NOTE: this deployment does NOT read AUTHZ_ENFORCE — that is the OSS knob for the same posture. Setting it here does nothing, which has already sent someone down the wrong path while diagnosing a 403. |
PLATFORM_ADMIN_EMAIL | — (example: [email protected]) | RBAC: the user with this email is promoted to Platform Superadmin on boot (idempotent). Leave empty for no promotion. |
EE_MULTI_ORG_ENABLED | — (example: false) | Single-org lock (default false). While false the deployment holds exactly one organization: org create/rename/delete is gated off, and an ALB-OIDC identity is enrolled into the default org on first sight so org-scoped routes resolve an orgId. Setting it to true turns that enrolment OFF — leave it unset unless the deployment really is multi-tenant, or every gateway user lands without an org and the PermissionGuard denies the management plane. |
CORS_ORIGINS | — | Comma-separated list of origins allowed to call the engine API (CORS). Leave empty in development if engine and web run on the same origin (rewrites). In production, set this to the public origin of your web app. Example: CORS_ORIGINS=https://app.example.com,https://admin.example.com A credentialed wildcard (*) is refused at startup — list explicit origins. |
Reverse proxy
| Variable | Default | Description |
|---|---|---|
TRUST_PROXY | 0 | Number of trusted proxy hops between the engine and the public internet (e.g. set to 1 if a single reverse proxy like Render/Railway/nginx sits in front of the engine). Controls whether X-Forwarded-Host / X-Forwarded-Proto headers are honored when reconstructing the request URL for the Twilio webhook signature check. Accepts an integer hop count or true/false. Leave at 0 (default) if the engine is exposed directly — otherwise attackers could spoof Host/Proto and bypass the Twilio HMAC. |
API rate limiting (@nestjs/throttler)
| Variable | Default | Description |
|---|---|---|
THROTTLE_ENABLED | true | Per-IP throttling on the HTTP API. Defaults: 30 req/min globally, with tighter per-route limits (e.g. POST /v1/chat/completions = 20 req/min). - THROTTLE_ENABLED: only the literal false disables ALL throttling (global default + every per-route @Throttle override). Useful for parallel dev/eval runs that fire many requests from one IP. Default on. - THROTTLE_TTL_MS: window for the global default limit. Default 60000. - THROTTLE_LIMIT: requests per window for the global default. Default 30. |
THROTTLE_TTL_MS | 60000 | — |
THROTTLE_LIMIT | 30 | — |
Instance
| Variable | Default | Description |
|---|---|---|
DEFAULT_INSTANCE_ID | default | Default instance for single-instance setup. Override if needed. |
Enterprise organization mode
| Variable | Default | Description |
|---|---|---|
DEFAULT_ORG_NAME | — (example: Polyant) | Optional display name applied to the seeded default organization on boot. |
Platform S3 (optional - for persisting conversation attachments)
| Variable | Default | Description |
|---|---|---|
PLATFORM_S3_BUCKET | — | When configured, file attachments from WhatsApp/Telegram are stored in this bucket and served via the /api/attachments proxy endpoint. If not configured, attachments still work in-memory but are NOT persisted to DB/UI. |
PLATFORM_S3_REGION | — | — |
PLATFORM_S3_ACCESS_KEY_ID | — | — |
PLATFORM_S3_SECRET_ACCESS_KEY | — | — |
Message coordinator (WhatsApp/Telegram inbound)
| Variable | Default | Description |
|---|---|---|
MESSAGE_SOFT_DEBOUNCE_MS | 2000 | Collapses burst fragments into one pipeline run and cancels/restarts the in-flight pipeline when new fragments arrive — keeps UX responsive. Pre-pipeline coalescing window (ms). Burst fragments within this window are concatenated into one call. Default 2000. |
MESSAGE_TYPING_DELAY_MS | 1500 | Delay before sending the channel’s typing indicator (ms). Starts the “typing…” UX a little after the first fragment — humanises the flow. Default 1500. |
MESSAGE_MAX_RESTARTS | 3 | Cap on consecutive cancel-and-restart cycles per conversation. Once reached, further fragments accumulate and are flushed after the current pipeline completes. Default 3. |
Agent-to-Agent Invocation
| Variable | Default | Description |
|---|---|---|
AGENT_CALL_TIMEOUT_MS | 60000 | Maximum wall-clock duration (ms) of a single sub-agent call through the virtual agent channel. On timeout the caller’s tool returns Errore: timeout dopo Nms instead of waiting forever. Default 60000. |
Auth
| Variable | Default | Description |
|---|---|---|
AUTH_INTERNAL_SECRET | — (example: replace-with-a-generated-credentials-secret) | Shared secret used by the web’s Credentials provider to call the engine’s /api/auth/credentials/verify endpoint. Must be identical in engine and web .env files. Leave this optional setting unset to disable email/password login. Generate with: node -e “console.log(require(‘crypto’).randomBytes(48).toString(‘base64url’))“ |
INITIAL_ADMIN_EMAIL | — (example: [email protected]) | Initial admin user — created on first boot if the users table is empty. Both optional. If INITIAL_ADMIN_PASSWORD is unset, a random password is generated and printed once in the engine logs (with a “change me” warning). |
INITIAL_ADMIN_PASSWORD | — (example: choose-a-strong-password) | — |
PDF_CONCURRENCY | 3 | — |
Activity stream (SSE) resource limits
| Variable | Default | Description |
|---|---|---|
SSE_MAX_CONNECTIONS | 50 | Caps on concurrent subscribers of GET /api/activity-stream/live. Excess connections are rejected with HTTP 503 + Retry-After: 60. - SSE_MAX_CONNECTIONS: global cap across all users. Default 50. - SSE_MAX_CONNECTIONS_PER_USER: per-authenticated-user cap. Default 5. |
SSE_MAX_CONNECTIONS_PER_USER | 5 | — |
Knowledge resource limits
| Variable | Default | Description |
|---|---|---|
KNOWLEDGE_MAX_DOCS_PER_INSTANCE | 500 | Hard cap on the number of knowledge documents an instance may hold. Uploads beyond the cap are rejected with HTTP 400. Default 500. |
Analytics retention
| Variable | Default | Description |
|---|---|---|
ANALYTICS_RETENTION_DAYS | 90 | Daily housekeeping deletes rows older than this many days from ai_logs and pipeline_traces. Both tables grow at one row per LLM call / pipeline run, so unbounded retention is not recommended. Default: 90. |
Per-agent data retention
| Variable | Default | Description |
|---|---|---|
RETENTION_DEFAULT_DAYS | 15 | Fallback TTL in days when an enabled per-instance policy has no explicit retention_days value. Retention is off until a per-instance policy is enabled. Default: 15. |
External plugins
| Variable | Default | Description |
|---|---|---|
PLUGIN_DIRS | — | Comma-separated absolute paths scanned for external plugins in addition to the built-in plugin directory. Leave empty unless self-hosting and loading a local plugin. Example: /opt/polyant/plugins,/srv/acme-plugin |
Logging verbosity
| Variable | Default | Description |
|---|---|---|
LOG_LEVEL | info | Controls how much the structured/pipeline loggers emit (console + daily log files). One of: debug | info | warn | error | silent. Default: info. - debug: verbose per-step pipeline tracing (LLM call lines, tool-call args, system-prompt length, context load) on top of info - info: high-value skeleton — request, LLM token/latency, tool results, supervisor + response timing - warn: suppress info-level lines, keep warnings + errors - error: errors only - silent: disable all structured logging Note: the full system prompt is never logged here — use the per-instance debug_enabled flag or the DEBUG_LLM_PAYLOAD env for full-payload inspection. |
Base URL
| Variable | Default | Description |
|---|---|---|
BASE_URL | http://localhost:4000 | Public base URL of the engine (used for webhook callback URLs, etc.) |
Locale
| Variable | Default | Description |
|---|---|---|
DATETIME_TIMEZONE | UTC | Default timezone and locale used by the supervisor system prompt to format dates/times. Per-instance overrides happen at the prompt level. |
DATETIME_LOCALE | en-US | — |
Tracing (optional, opt-in)
| Variable | Default | Description |
|---|---|---|
LANGSMITH_API_KEY | — | LangSmith credentials are configured per-instance via the admin panel (Settings tab) — not here. Leave the keys below unset unless you want a global fallback for development. See docs for details. |
LANGSMITH_PROJECT | — | — |
LANGSMITH_TRACING | — (example: false) | — |
Debug (DEVELOPMENT ONLY)
| Variable | Default | Description |
|---|---|---|
DEBUG_LLM_PAYLOAD | — (example: 0) | When set to 1, the engine logs the full LLM request payload (system prompt, message contents, tool names) to stdout. The system prompt may contain instance secrets, customer PII pulled from memory, and other sensitive data. WARNING: Never enable this in production. Leave unset (or =0) by default. |
Last updated on