All configuration is environment variables. In Docker Compose they come from .env (start from .env.example); on Kubernetes from the chart's values and the Secrets in secrets.*. An invalid value usually stops the server with a message naming the variable.
Production by default. With NI_AUTH_DEPLOY_ENV unset, the server refuses to start when a required key is missing, shorter than required, all zero bytes, or a placeholder (anything containing change-me, changeme, change-in-prod, replace-with, REPLACE_, dev-key or dev-secret). development, dev, local or test accepts them with a warning at every start. Never set it on a shared deployment.
Specialised settings have their own pages: Context settings, audit tiering, client events, selfguard, telemetry pipeline, BYOC compute.
Server and URLs
| Variable | Default | Meaning |
|---|
NI_AUTH_HTTP_ADDR | :8080 | Listen address |
NI_AUTH_PUBLIC_URL | http://localhost:8080 | Public URL: OAuth redirects, the OIDC issuer, email links. HTTPS in production |
NI_AUTH_API_PUBLIC_URL | NI_AUTH_PUBLIC_URL | Public URL of the API when it is on its own host; used for every client-facing URL that is not a sign-in path (model and MCP gateways, downloads, the API reference) |
NI_AUTH_JWT_ISSUER | http://localhost:8080 | Token iss; must equal NI_AUTH_PUBLIC_URL |
NI_AUTH_JWT_AUDIENCE | ni-auth-api | Token aud |
NI_AUTH_REGISTRATION_MODE | invite | invite (an invitation is required) or open |
NI_AUTH_SUPER_ADMIN_EMAILS | empty | Emails that receive super admin on registration; empty: nobody, there is no first-user bootstrap |
NI_AUTH_CORS_ALLOWED_ORIGINS | empty | Browser origins allowed cross-origin; empty disables CORS |
NI_AUTH_PASSKEY_RP_ID, NI_AUTH_PASSKEY_ORIGINS | | Passkey relying party and allowed origins |
NI_AUTH_TERMINAL_ORIGINS | empty | Origins the workspace web terminal accepts; unset, it is unavailable |
NI_AUTH_SAAS_ENABLED | false | The hosted service's plans and billing; off for self-hosted |
NI_ASSISTANT_ENABLED | true | false turns the console assistant off for the whole deployment |
NI_REGION_ID | local | The cell this installation is; self-hosted keeps local |
NI_AUTH_DEPLOY_ENV | unset (production) | See above |
Database
| Variable | Meaning |
|---|
DATABASE_URL | keystone_app, the runtime role, under row-level security. A superuser or BYPASSRLS role is refused |
DATABASE_PLATFORM_URL | keystone_platform, for the named cross-organisation tasks. Required, must differ from DATABASE_URL |
DATABASE_OWNER_URL | keystone_owner, for migrations and restores only. Never give it to the running server |
KEYSTONE_OWNER_PASSWORD, KEYSTONE_APP_PASSWORD, KEYSTONE_PLATFORM_PASSWORD | The three role passwords the bootstrap sets: at least 16 characters, all different (openssl rand -hex 24) |
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_PORT | Docker Compose's PostgreSQL service; change POSTGRES_PASSWORD |
NI_AUTH_DB_MAX_OPEN | Open connections per server process (default 25; the Helm chart sets database.poolPerPod, default 50). Keep replicas times this below PostgreSQL's max_connections |
NI_AUTH_DB_MAX_IDLE | Idle connections (default: the open limit) |
NI_AUTH_DB_MAX_LIFETIME, NI_AUTH_DB_MAX_IDLE_TIME | Connection lifetime (default 5m) and idle time (default 1m), Go durations |
Use PgBouncer in session mode only; transaction mode is not supported, because the tenant of each connection is a session setting.
Keys and secrets
| Variable | Required | Generate | Purpose |
|---|
KMS_MASTER_KEY | yes | openssl rand -hex 32 | Seals the KMS keys, the audit signing keys and the manifest signing keys. Keep stable |
NI_AUTH_AUDIT_HMAC_KEY | yes | openssl rand -base64 48 | Audit hash chains. Keep stable |
NI_AUTH_AUDIT_SIGNING_KEY | yes | openssl rand -base64 48 | Audit signing |
NI_OBSERVABILITY_SIGNING_KEY | yes | openssl rand -base64 48 | Context and governance evidence chain. Keep stable |
NI_AUTH_API_KEY_PEPPER, NI_AUTH_OAUTH2_PEPPER, NI_AUTH_EMAIL_TOKEN_PEPPER | yes | openssl rand -base64 48 | Credential digests |
NI_AUTH_AGENT_PEPPER | no | | Agent credential digests; empty uses NI_AUTH_API_KEY_PEPPER |
NI_AUTH_TOTP_ENCRYPTION_KEY, NI_AUTH_LDAP_ENCRYPTION_KEY, NI_AUTH_SOCIAL_ENCRYPTION_KEY, NI_AUTH_WEBHOOK_ENCRYPTION_KEY | yes | openssl rand -base64 32 | AES-256-GCM keys for secrets at rest |
NI_AUTH_VAULT_ENCRYPTION_KEY, NI_AUTH_SECRETS_ENCRYPTION_KEY | yes | openssl rand -base64 48 | AI provider keys and governed secrets; rotate by moving the old value to *_RETIRED_KEYS |
NI_AUTH_PASSPORT_KEY | yes | openssl rand -base64 48 | Model Passport signing |
NI_AUTH_APPROVAL_SECRET | yes | openssl rand -base64 48 | Approval tokens |
NI_AUTH_DLP_TOKEN_ENCRYPTION_KEY | no | openssl rand -base64 32 | DLP token vault; unset, tokenisation answers 503 |
NI_AUTH_MANIFEST_KEY_ROTATION_DAYS | no | | Days between manifest signing key rotations (default 90) |
Token signing
| Variable | Default | Meaning |
|---|
NI_AUTH_OIDC_PRIVATE_KEY_PEM, NI_AUTH_OIDC_PRIVATE_KEY_FILE | Compose: /run/secrets/oidc_private_key | The OIDC signing key; the PEM takes precedence |
NI_AUTH_OIDC_KEY_ID | | The kid of that key |
NI_AUTH_SIGNING_ALGORITHM | RS256 | RS256 or ES256 |
NI_AUTH_SIGNING_KEY_PEM, NI_AUTH_SIGNING_KEY_FILE, NI_AUTH_SIGNING_KEY_ID | | An access token signing key instead of database-managed keys |
NI_AUTH_ACCESS_TOKEN_TTL, NI_AUTH_REFRESH_TOKEN_TTL | .env.example: 15m, 720h | Token lifetimes |
NI_AUTH_SESSION_IDLE_TIMEOUT | 168h | Idle timeout of sessions |
NI_AUTH_CONSOLE_CLIENT_ID, NI_AUTH_CONSOLE_SESSION_IDLE_TIMEOUT, NI_AUTH_CONSOLE_SESSION_MAX_LIFETIME | , 1h, 12h | The console's OAuth client and its session limits |
Signing keys of optional features
Each is an Ed25519 PKCS#8 PEM (openssl genpkey -algorithm ed25519) with a key id kept stable until you rotate.
| Variables | Without them |
|---|
NI_AUTH_MODELS_SIGNING_KEY_PEM, NI_AUTH_MODELS_SIGNING_KEY_ID | /api/v1/models/resolved answers 503 |
NI_AUTH_AGENTPOLICY_SIGNING_KEY_PEM, NI_AUTH_AGENTPOLICY_SIGNING_KEY_ID | The resolved agent policy answers 503 |
KEYSTONE_MCP_SIGNING_KEY_PEM (or _FILE), KEYSTONE_MCP_SIGNING_KEY_ID | /api/v1/mcp/resolved answers 503 |
NI_AUTH_HARNESS_SIGNING_KEY_PEM, NI_AUTH_HARNESS_SIGNING_KEY_ID | Harness packs can be read and assigned but not published |
Email
NI_AUTH_SMTP_HOST, NI_AUTH_SMTP_PORT, NI_AUTH_SMTP_STARTTLS, NI_AUTH_SMTP_USERNAME, NI_AUTH_SMTP_PASSWORD, NI_AUTH_SMTP_FROM, NI_AUTH_SMTP_INSECURE_SKIP_VERIFY, NI_AUTH_SIGN_IN_URL. See Email.
Proxies and client addresses
NI_AUTH_TRUSTED_PROXIES, NI_AUTH_TRUSTED_CDN_PROXIES, NI_AUTH_CLIENT_IP_HEADER, NI_AUTH_CLIENT_COUNTRY_HEADER, NI_AUTH_CONSOLE_CONTEXT_KEYS. See Client IP addresses.
Outbound connections
| Variable | Default | Opens |
|---|
NI_AUTH_OUTBOUND_ALLOW_PRIVATE_CIDRS | empty | Internal networks that webhooks, approval channels, SIEM integrations, LDAP and Active Directory, inference servers and vendor connectors may reach. Overrides every built-in rule, metadata addresses included: keep it narrow. An invalid value is logged and ignored |
NI_AUTH_MODELS_PRIVATE_NETWORKS | empty | Model provider connections on internal networks |
KEYSTONE_MCP_ALLOW_PRIVATE_NETWORKS | empty | MCP servers on internal networks |
NI_AUTH_WEBHOOK_ALLOW_PRIVATE | false (server) | Organisation webhooks to private and loopback addresses. The Docker Compose file defaults it to true when unset; .env.example sets false |
Storage
| Variable | Default | Meaning |
|---|
NI_OBJECT_STORE_DIR | Compose: /var/lib/keystone/objects | Shared directory for exports and artifacts; with several replicas, a volume all of them mount |
NI_OBJECT_STORE_S3_BUCKET, _REGION, _KMS_KEY_ID, _PREFIX, _ENDPOINT | | An S3 or S3-compatible bucket instead |
NI_AUTH_AUDIT_EXPORT_MAX_ROWS | 1,000,000 | Largest audit export (1 to 50,000,000) |
NI_AUTH_AUDIT_EXPORT_RETENTION_DAYS | 7 | Days an export file is kept (1 to 365) |
NI_AUTH_AUDIT_EXPORT_DIR | | Where earlier releases kept export files; moved to the object store at start |
Audit ledger
| Variable | Default | Meaning |
|---|
NI_AUDIT_CHAIN_LANES | 8 | Lanes per organisation chain, unless the organisation sets its own |
NI_AUDIT_GROUP_COMMIT_WINDOW | 2ms | Group commit window, 1 to 5 ms |
NI_AUDIT_GROUP_COMMIT_MAX_IN_FLIGHT | 8 | Group commit shards per replica |
NI_AUDIT_GROUP_COMMIT_SPLIT_BY_CHAIN | | true commits each chain of a batch in its own transaction |
NI_AUTH_AUDIT_TIERING_*, NI_AUTH_AUDIT_HOT_WINDOW_DAYS, NI_AUTH_AUDIT_ARCHIVE_YEARS | | See Retention and tiering |
Backups
NI_AUTH_BACKUP_ENCRYPTION_KEY, NI_AUTH_BACKUP_S3_BUCKET, NI_AUTH_BACKUP_S3_PREFIX, NI_AUTH_BACKUP_S3_REGION, NI_AUTH_BACKUP_S3_ENDPOINT, NI_AUTH_BACKUP_S3_ACCESS_KEY, NI_AUTH_BACKUP_S3_SECRET_KEY. See Backup and restore.
Monitoring
| Variable | Meaning |
|---|
NI_AUTH_METRICS_TOKEN | Bearer token for Prometheus scrapes of /metrics, /metrics/cloud, /metrics/selfguard and the rollout gate; at least 32 bytes. Empty: only super admins can read them |
NI_AUTH_SELFGUARD_* | See Monitoring and self-healing |
Air gap
| Variable | Meaning |
|---|
NI_AIRGAP_LICENSE_PUBLIC_KEY, NI_AIRGAP_LICENSE_PUBLIC_KEY_FILE | The Ed25519 public key offline licences are verified with; set at most one. See Air-gapped installation |
Workers
| Variable | Meaning |
|---|
WORKER_SHARED_SECRET | Authenticates sandbox workers to the internal worker API (port 9090) |
WORKER_API_BIND | Docker Compose: the address port 9090 is published on (default 127.0.0.1). Never a public or all-interfaces address |