Configuration

nivq is configured with environment variables — pass them however your setup prefers: a .env or --env-file for Docker, -e flags for a single container, Helm values for Kubernetes, or a secrets manager. All are optional except the datastore connection and the encryption key. Group by group:

Datastores (required)

Shell

NIVQ_DATASOURCE_URL=jdbc:postgresql://postgres:5432/nivq
NIVQ_DATASOURCE_USERNAME=nivq
NIVQ_DATASOURCE_PASSWORD=...
NIVQ_REDIS_HOST=redis
NIVQ_REDIS_PORT=6379

This is nivq's own metadata store (Postgres + pgvector) and cache (Redis) — not the databases your agents query. Those are added in the app as data sources.

Encryption (required)

Shell

# 32-byte base64 key; encrypts stored data-source credentials and secrets (AES-256)
NIVQ_ENCRYPTION_KEY_V1=...

Protect this key

Losing NIVQ_ENCRYPTION_KEY_V1 means every stored credential becomes unrecoverable. Back it up in a secrets manager, and never commit it.

LLM providers

A platform-managed provider handles lightweight internal tasks. Per-agent providers (the model each agent reasons with) are configured per agent in the app, not here.

Shell

NIVQ_PLATFORM_LLM_PROVIDER=anthropic                 # anthropic | openai | azure | ollama
NIVQ_PLATFORM_LLM_MODEL=claude-haiku-4-5-20251001
NIVQ_PLATFORM_LLM_API_KEY=...
NIVQ_PLATFORM_LLM_BASE_URL=                           # set for Azure / self-hosted / Ollama

For air-gapped sites, point the provider at a local Ollama via NIVQ_PLATFORM_LLM_BASE_URL.

Embeddings (optional — enables self-learning)

Pattern memory and semantic search run on an embedding model. This block is all-or-nothing: set all three values to turn self-learning on, or leave them all blank.

Shell

NIVQ_PLATFORM_EMBEDDING_PROVIDER=openai
NIVQ_PLATFORM_EMBEDDING_MODEL_ID=text-embedding-3-small
NIVQ_PLATFORM_EMBEDDING_API_KEY=...

Leaving it blank is fine

With no embedding values set, nivq boots cleanly and works normally — only self-learning is off, so the agent won't grow its pattern memory. Setting just some of the three is a misconfiguration and stops startup on purpose, so you never half-enable it.

Identity (OIDC / SSO)

Enable any subset; the login page only shows the methods you configure. nivq is its own OAuth2 Authorization Server — after any federated login it mints its own JWT, so the rest of the platform behaves identically regardless of IdP.

Social providers (only those with credentials set appear):

Shell

GOOGLE_CLIENT_ID=...        GOOGLE_CLIENT_SECRET=...
MICROSOFT_CLIENT_ID=...     MICROSOFT_CLIENT_SECRET=...   MICROSOFT_TENANT=...
GITHUB_CLIENT_ID=...        GITHUB_CLIENT_SECRET=...
OAUTH2_LOGIN_SUCCESS_URL=https://app.example.com
OAUTH2_LOGIN_FAILURE_URL=https://app.example.com/auth/callback?error=login_failed

Generic OIDC IdP — for on-prem deployments behind Keycloak, Okta, Auth0, Azure AD, PingFederate, etc. Endpoints are auto-discovered from the issuer; set all three to enable the button:

Shell

OIDC_ISSUER_URI=https://keycloak.company.com/realms/company
OIDC_CLIENT_ID=nivq
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Company SSO     # button label (default: "Single Sign-On")

Bootstrap admin — an optional local username/password login for on-prem demo / trial deployments that can't stand up an IdP. Both set → a password form appears and mints the same JWT as SSO. The password is BCrypt-hashed in memory only, never persisted. Leave blank in production (pure SSO).

Shell

NIVQ_BOOTSTRAP_ADMIN_USERNAME=admin@example.com
NIVQ_BOOTSTRAP_ADMIN_PASSWORD=a-long-passphrase

IdP group → role mapping — when a federated user's email domain matches a workspace SSO config, they auto-join that workspace with a role derived from their IdP group claim. Precedence OWNER > ADMIN > MEMBER; no match → default role.

Shell

NIVQ_OIDC_GROUPS_CLAIM=groups        # claim holding the group names (default: groups)
NIVQ_OIDC_DEFAULT_ROLE=MEMBER        # role when no group matches
NIVQ_OIDC_OWNER_GROUPS=nivq-owners
NIVQ_OIDC_ADMIN_GROUPS=nivq-admins
NIVQ_OIDC_MEMBER_GROUPS=nivq-users

Per-workspace SSO and group → workspace routing

Per-workspace SSO (email domain → IdP) and group → specific workspace + role routing are managed in the app (Workspace Settings → SSO), not via env. See the Authentication & SSO guide for the full picture.

URLs & email

Shell

BACKEND_URL=https://api.example.com
FRONTEND_URL=https://app.example.com
NIVQ_SUPPORT_EMAIL=support@example.com
NIVQ_MAIL_SMTP_HOST=...    NIVQ_MAIL_SMTP_PORT=587
NIVQ_MAIL_SMTP_USERNAME=...  NIVQ_MAIL_SMTP_PASSWORD=...

Outbound IPs

If your databases sit behind a firewall, set the public IPs nivq connects from. nivq then shows them in the UI when someone adds a data source, so your team knows exactly what to whitelist.

Shell

NIVQ_OUTBOUND_IPS=203.0.113.10,203.0.113.11

Payments (SaaS only)

Only relevant if you run nivq as a billed service. On-prem deployments can ignore these entirely. Paddle (Merchant of Record) handles international cards; for Turkish customers, NIVQ_TR_PROVIDER routes payments to PayTR.

Shell

# Paddle — international (Merchant of Record)
PADDLE_API_KEY=...                 PADDLE_CLIENT_TOKEN=...     PADDLE_NOTIFICATION_SECRET=...
PADDLE_API_BASE_URL=https://sandbox-api.paddle.com  # or https://api.paddle.com for live
PADDLE_PRICE_TEAM_MONTHLY=pri_...  PADDLE_PRICE_TEAM_ANNUAL=pri_...   # one per plan:interval

# PayTR — Türkiye (TRY)
PAYTR_MERCHANT_ID=...    PAYTR_MERCHANT_KEY=...   PAYTR_MERCHANT_SALT=...   PAYTR_TEST_MODE=1
NIVQ_TR_PROVIDER=paytr   # provider for Türkiye payments

Observability

Shell

NIVQ_OTLP_TRACING_EXPORT_URL=http://jaeger:4318/v1/traces
NIVQ_OTLP_METRICS_EXPORT_URL=...
NIVQ_LOG_FORMAT_CONSOLE=ecs   # emit ECS JSON logs for Elasticsearch/Kibana
NIVQ_LOG_SECURITY=warn        # log level for the security layer (warn | info | debug)

See Deployment for the optional Elasticsearch + Kibana log stack.

Licensing

Licensing has its own properties under nivq.licensing.*. Defaults are sensible; the only one you'll commonly set is hardware binding. See Licensing & activation.