Environment Variables Reference
Every environment variable Polyant reads is listed here. Variables marked required must be set before first boot; others have defaults or are optional features.
Database
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | Alt | — | Full Postgres URL. Either this or the four POSTGRES_* vars below. |
POSTGRES_HOST | Alt | localhost | Postgres host. |
POSTGRES_PORT | Alt | 5432 | Postgres port. |
POSTGRES_DB | Alt | polyant | Postgres database name. |
POSTGRES_USER | Alt | polyant | Postgres user. |
POSTGRES_PASSWORD | Yes | — | Postgres password. Required by docker-compose and the engine. |
Auth and crypto
| Variable | Required | Default | Description |
|---|---|---|---|
AUTH_SECRET | Yes | — | 32+ char random string. Encrypts session JWTs in both packages. |
AUTH_INTERNAL_SECRET | No | — | Shared secret between web and engine for the credentials-verification endpoint. |
ENCRYPTION_KEY | Yes | — | 64-character hex (32 bytes) for AES-256-GCM secret encryption. |
INITIAL_ADMIN_EMAIL | No | administrator@local | Email of the auto-created Superadmin on first boot. |
INITIAL_ADMIN_PASSWORD | No | random | Password of the auto-created Superadmin (printed once if not set). |
Server
| Variable | Required | Default | Description |
|---|---|---|---|
API_PORT | No | 4000 | HTTP port for the engine. |
BASE_URL | No | — | Public base URL for the engine. Used in webhook deep links. |
CORS_ORIGINS | No | open in dev, closed in production | Comma-separated allowlist of origins (e.g. https://app.example.com,https://admin.example.com). When unset in NODE_ENV=production, all cross-origin requests are rejected. Setting it to * is refused at startup (a credentialed wildcard would let any origin read authenticated responses). |
TRUST_PROXY | No | 0 | Number of trusted reverse-proxy hops between the engine and the public internet (e.g. 1 behind Render/Railway/nginx). Also accepts true / false. Controls whether X-Forwarded-Host / X-Forwarded-Proto are honored when reconstructing the request URL for the Twilio webhook signature check. Default 0 (trust nothing) — otherwise attackers can spoof Host/Proto and bypass the Twilio HMAC. |
NODE_ENV | No | (Node default) | Standard Node.js mode. production activates the strict CORS default above and disables verbose error responses. |
Web (Next.js)
| Variable | Required | Default | Description |
|---|---|---|---|
GOOGLE_CLIENT_ID | No | — | Google OAuth client id (required only for Google login). |
GOOGLE_CLIENT_SECRET | No | — | Google OAuth client secret. |
AUTH_TRUST_HOST | No | — | Set to true behind a reverse proxy. |
AUTH_ALLOWED_DOMAINS | No | — (allow any) | Comma-separated list of email domains permitted via Google OAuth. Empty or unset means any verified Google account can sign in. |
INTERNAL_ENGINE_URL | No | http://localhost:4000 | Base URL used by the web’s Credentials provider to call POST /api/auth/credentials/verify on the engine. Set to the engine’s internal address in production. |
NEXT_PUBLIC_API_URL | No | http://localhost:4000 | Public URL of the engine used by the Next.js rewrite rules (browser-side proxy). Read in packages/web/next.config.ts. |
Memory
| Variable | Required | Default | Description |
|---|---|---|---|
DEDUP_SIMILARITY_THRESHOLD | No | 0.90 | Cosine threshold above which a new memory updates an existing one. |
Analytics retention
| Variable | Required | Default | Description |
|---|---|---|---|
ANALYTICS_RETENTION_DAYS | No | 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. |
Datetime
| Variable | Required | Default | Description |
|---|---|---|---|
DATETIME_TIMEZONE | No | UTC | Timezone used in the system prompt’s {{datetime}} substitution. |
DATETIME_LOCALE | No | en-US | Locale for date/time formatting. |
Inbound message coordinator
| Variable | Required | Default | Description |
|---|---|---|---|
MESSAGE_SOFT_DEBOUNCE_MS | No | 2000 | Coalescence window for fragmented bursts. |
MESSAGE_TYPING_DELAY_MS | No | 1500 | Delay before the typing indicator fires. |
MESSAGE_MAX_RESTARTS | No | 3 | Cap on consecutive cancel-and-restart cycles per conversation. |
Agent-to-agent
| Variable | Required | Default | Description |
|---|---|---|---|
AGENT_CALL_TIMEOUT_MS | No | 60000 | Max wall-clock duration of a single sub-agent invocation (virtual agent channel). On timeout the synthesised tool returns an error string to the caller. |
Activity stream (SSE)
| Variable | Required | Default | Description |
|---|---|---|---|
SSE_MAX_CONNECTIONS | No | 50 | Global cap on concurrent subscribers of GET /api/activity-stream/live across all users. Excess connections receive HTTP 503 with Retry-After: 60. |
SSE_MAX_CONNECTIONS_PER_USER | No | 5 | Per-authenticated-user cap on the same endpoint. Same 503 + Retry-After behaviour when exceeded. |
Knowledge
| Variable | Required | Default | Description |
|---|---|---|---|
KNOWLEDGE_MAX_DOCS_PER_INSTANCE | No | 500 | Hard cap on the number of knowledge documents an instance may hold. POST /api/instances/:slug/knowledge returns HTTP 400 when reached; POST .../knowledge/sync reports refused files in the response (refusedCap[]). |
Workspace storage
| Variable | Required | Default | Description |
|---|---|---|---|
WORKSPACES_ROOT | No | packages/engine/workspaces (resolved abs.) | Filesystem root for per-conversation sandbox directories used by the readFile / writeFile / gitCloneRepo tools (<root>/<instance>/conversations/<conv>/). Knowledge documents and all other agent configuration live in PostgreSQL. One of the two documented process.env reads outside config.ts. |
Platform S3 (optional, for attachments)
| Variable | Required | Default | Description |
|---|---|---|---|
PLATFORM_S3_BUCKET | No | — | Bucket where conversation attachments are persisted. |
PLATFORM_S3_REGION | No | — | Bucket region. |
PLATFORM_S3_ACCESS_KEY_ID | No | — | AWS access key. |
PLATFORM_S3_SECRET_ACCESS_KEY | No | — | AWS secret key. |
Debug
| Variable | Required | Default | Description |
|---|---|---|---|
DEBUG_LLM_PAYLOAD | No | unset | Set to 1 to log the full system prompt + message array sent to the LLM provider on every call. Forced off when NODE_ENV=production (logs a stderr warning if both are set) — would leak customer data via stdout. Verbose; development only. |
Other
| Variable | Required | Default | Description |
|---|---|---|---|
DEFAULT_INSTANCE_ID | No | default | Default instance for mono-instance deployments. |
Last updated on