Engine Configuration Reference

Complete reference of all configuration keys and environment variables supported by the Niksphere Engine.

insider 2026-10-02 JSON ↗

IMPORTANT

If db_host or db_port is set, db_driver must be "postgres".

IMPORTANT

http_base_url defaults to http://localhost:<http_port> when empty.

HTTP & Server Settings

Configuration Key	Environment Variable	Type	Default Value	Description
`http_base_url`	`NIKSPHERE_ENGINE_HTTP_BASE_URL`	`string`	`""`	Public base URL used to construct absolute links returned by the Engine. Defaults to `http://localhost:<http_port>` when left empty.
`http_port`	`NIKSPHERE_ENGINE_HTTP_PORT`	`string`	`3000`	TCP port the Engine's HTTP server listens on.
`trusted_proxies`	`NIKSPHERE_ENGINE_TRUSTED_PROXIES`	`[]string`	`[]`	IP addresses or CIDR ranges (e.g. 10.0.0.1, 10.0.0.0/8) of reverse proxies trusted to set the X-Forwarded-For and X-Real-IP headers. Empty by default: no proxy is trusted and the address of the direct connection is used as the client address. When the Engine runs behind a reverse proxy, list all proxies in the chain, otherwise every client appears with the proxy's address. Hostnames and ranges matching every address (0.0.0.0/0, ::/0) are rejected, and the Engine refuses to start if an entry is invalid.

Configuration Key	Environment Variable	Type	Default Value	Description
`db_driver`	`NIKSPHERE_ENGINE_DB_DRIVER`	`string`	`sqlite`	Database backend to use: "sqlite" or "postgres". Must be "postgres" if db_host or db_port is set.
`db_host`	`NIKSPHERE_ENGINE_DB_HOST`	`string`	`""`	Database host. If set together with db_port, db_driver must be "postgres".
`db_name`	`NIKSPHERE_ENGINE_DB_NAME`	`string`	`niksphere`	Database name.
`db_password`	`NIKSPHERE_ENGINE_DB_PASSWORD`	`string`	`niksphere`	Database password.
`db_port`	`NIKSPHERE_ENGINE_DB_PORT`	`string`	`""`	Database port. If set together with db_host, db_driver must be "postgres".
`db_url`	`NIKSPHERE_ENGINE_DB_URL`	`string`	`""`	Full database connection URL (optional alternative to the individual db_host/db_port/db_username/db_password/db_name fields).
`db_username`	`NIKSPHERE_ENGINE_DB_USERNAME`	`string`	`niksphere`	Database username.

Configuration Key	Environment Variable	Type	Default Value	Description
`idp_refresh_token_expiry_days`	`NIKSPHERE_ENGINE_IDP_REFRESH_TOKEN_EXPIRY_DAYS`	`string`	`30`	Number of days an issued refresh token remains valid.
`idp_token_expiry_hours`	`NIKSPHERE_ENGINE_IDP_TOKEN_EXPIRY_HOURS`	`string`	`24`	Number of hours an issued access token remains valid.

Configuration Key	Environment Variable	Type	Default Value	Description
`admin_password`	`NIKSPHERE_ENGINE_ADMIN_PASSWORD`	`string`	`""`	Password for the bootstrap/emergency admin account, seeded on startup.
`admin_pat`	`NIKSPHERE_ENGINE_ADMIN_PAT`	`string`	`""`	Personal access token for the bootstrap/emergency admin account, seeded on startup.
`admin_username`	`NIKSPHERE_ENGINE_ADMIN_USERNAME`	`string`	`""`	Username for the bootstrap/emergency admin account, seeded on startup.

Configuration Key	Environment Variable	Type	Default Value	Description
`allow_debugging`	`NIKSPHERE_ENGINE_ALLOW_DEBUGGING`	`boolean`	`true`	Whether the DAP debug control-plane (/admin/dap) may be used to attach a debugger to a session. Should be set to false in Production environments.
`debug_export_bytecode`	`NIKSPHERE_ENGINE_DEBUG_EXPORT_BYTECODE`	`boolean`	`false`	When enabled, writes the linked runtime bytecode to bytecode.bin/bytecode.txt in the Engine cache directory on every runtime reload.

Engine Configuration Concept — How configuration sources are combined, precedence rules, and usage examples.
Engine Installation & Setup Guide — Quickstart guide to running the Engine.
Engine Deployment Models — Architectural overview of Self-Hosted (Docker / Standalone Binary) and Cloud (Fully Managed) deployment models.