Engine Configuration

The Niksphere Engine supports flexible runtime configuration management. Parameters can be supplied either via Environment Variables (prefixed with NIKSPHERE_ENGINE_) or via Configuration Files (config.yaml, config.json, or config.toml).

Configuration Precedence

The Engine evaluates configuration parameters in the following priority order (highest to lowest):

1. Command-Line Flags (--config <path>)
2. Environment Variables (NIKSPHERE_ENGINE_*)
3. Configuration File (config.yaml / config.json / config.toml)
4. Default Values

Command-Line Flags

When starting the Niksphere Engine executable, the following command-line flags are supported:

Flag	Type	Default Value	Description
--config <path>	string	""	Path to the Engine configuration file (e.g., config.yaml, config.json, or config.toml).
--service-name <name>	string	niksphere-engine	Custom service registration name when running as a background service (Windows Service / systemd).
-h, --help	flag	false	Displays executable usage instructions and available flags.

HTTP & Server Settings

Configuration Key	Environment Variable	Type	Default Value	Description
http_port	NIKSPHERE_ENGINE_HTTP_PORT	string	3000	The TCP port for the Engine HTTP API and Server-Driven UI listener.
http_base_url	NIKSPHERE_ENGINE_HTTP_BASE_URL	string	http://localhost:<http_port>	Base public URL of the Engine instance. Used for OIDC issuer metadata and callback URLs.
trusted_proxies	NIKSPHERE_ENGINE_TRUSTED_PROXIES	[]string	[]	List of trusted proxy IP addresses or CIDR ranges (e.g. 10.0.0.0/8) allowed to set the X-Forwarded-For header. If empty, the engine trusts no proxies for security.

Database Connection Settings

Configuration Key	Environment Variable	Type	Default Value	Description
db_driver	NIKSPHERE_ENGINE_DB_DRIVER	string	sqlite	Database driver backend. Supported options: sqlite, postgres, postgresql.
db_host	NIKSPHERE_ENGINE_DB_HOST	string	127.0.0.1	Hostname or IP address of the database server (PostgreSQL).
db_port	NIKSPHERE_ENGINE_DB_PORT	string	5432	Network port of the database server (PostgreSQL).
db_username	NIKSPHERE_ENGINE_DB_USERNAME	string	niksphere	Database user account name for authentication (PostgreSQL).
db_password	NIKSPHERE_ENGINE_DB_PASSWORD	string	niksphere	Database user account password for authentication (PostgreSQL).
db_name	NIKSPHERE_ENGINE_DB_NAME	string	niksphere	Name of the target database (PostgreSQL) or local database file (SQLite).

| db_url | NIKSPHERE_ENGINE_DB_URL | string | "" | Optional full connection string/DSN overriding individual host/port properties (PostgreSQL & SQLite). |

IMPORTANT

If db_host or db_port are explicitly specified, db_driver MUST be set to postgres or postgresql.

Identity & Authentication (IDP Broker) Settings

Configuration Key	Environment Variable	Type	Default Value	Description
idp_token_expiry_hours	NIKSPHERE_ENGINE_IDP_TOKEN_EXPIRY_HOURS	string	24	Expiration time for active user access tokens (in hours).
idp_refresh_token_expiry_days	NIKSPHERE_ENGINE_IDP_REFRESH_TOKEN_EXPIRY_DAYS	string	30	Expiration time for user refresh tokens (in days).

Configuration Examples

Example 1: Environment Variables

# Server Configuration
$env:NIKSPHERE_ENGINE_HTTP_PORT="3000"
$env:NIKSPHERE_ENGINE_HTTP_BASE_URL="https://engine.company.internal"
$env:NIKSPHERE_ENGINE_TRUSTED_PROXIES="10.0.0.0/8,192.168.0.0/16"

# Database Configuration (PostgreSQL)
$env:NIKSPHERE_ENGINE_DB_DRIVER="postgres"
$env:NIKSPHERE_ENGINE_DB_HOST="db.company.internal"
$env:NIKSPHERE_ENGINE_DB_PORT="5432"
$env:NIKSPHERE_ENGINE_DB_USERNAME="niksphere_admin"
$env:NIKSPHERE_ENGINE_DB_PASSWORD="securepassword123"
$env:NIKSPHERE_ENGINE_DB_NAME="niksphere_prod"

# Security & Identity
$env:NIKSPHERE_ENGINE_IDP_TOKEN_EXPIRY_HOURS="12"

# Server Configuration
export NIKSPHERE_ENGINE_HTTP_PORT="3000"
export NIKSPHERE_ENGINE_HTTP_BASE_URL="https://engine.company.internal"
export NIKSPHERE_ENGINE_TRUSTED_PROXIES="10.0.0.0/8,192.168.0.0/16"

# Database Configuration (PostgreSQL)
export NIKSPHERE_ENGINE_DB_DRIVER="postgres"
export NIKSPHERE_ENGINE_DB_HOST="db.company.internal"
export NIKSPHERE_ENGINE_DB_PORT="5432"
export NIKSPHERE_ENGINE_DB_USERNAME="niksphere_admin"
export NIKSPHERE_ENGINE_DB_PASSWORD="securepassword123"
export NIKSPHERE_ENGINE_DB_NAME="niksphere_prod"

# Security & Identity
export NIKSPHERE_ENGINE_IDP_TOKEN_EXPIRY_HOURS="12"

# Server Configuration
export NIKSPHERE_ENGINE_HTTP_PORT="3000"
export NIKSPHERE_ENGINE_HTTP_BASE_URL="https://engine.company.internal"
export NIKSPHERE_ENGINE_TRUSTED_PROXIES="10.0.0.0/8,192.168.0.0/16"

# Database Configuration (PostgreSQL)
export NIKSPHERE_ENGINE_DB_DRIVER="postgres"
export NIKSPHERE_ENGINE_DB_HOST="db.company.internal"
export NIKSPHERE_ENGINE_DB_PORT="5432"
export NIKSPHERE_ENGINE_DB_USERNAME="niksphere_admin"
export NIKSPHERE_ENGINE_DB_PASSWORD="securepassword123"
export NIKSPHERE_ENGINE_DB_NAME="niksphere_prod"

# Security & Identity
export NIKSPHERE_ENGINE_IDP_TOKEN_EXPIRY_HOURS="12"

.env File

# Server Configuration
NIKSPHERE_ENGINE_HTTP_PORT=3000
NIKSPHERE_ENGINE_HTTP_BASE_URL=https://engine.company.internal
NIKSPHERE_ENGINE_TRUSTED_PROXIES=10.0.0.0/8,192.168.0.0/16

# Database Configuration (PostgreSQL)
NIKSPHERE_ENGINE_DB_DRIVER=postgres
NIKSPHERE_ENGINE_DB_HOST=db.company.internal
NIKSPHERE_ENGINE_DB_PORT=5432
NIKSPHERE_ENGINE_DB_USERNAME=niksphere_admin
NIKSPHERE_ENGINE_DB_PASSWORD=securepassword123
NIKSPHERE_ENGINE_DB_NAME=niksphere_prod

# Security & Identity
NIKSPHERE_ENGINE_IDP_TOKEN_EXPIRY_HOURS=12

Example 2: Configuration Files (config.yaml / config.json / config.toml)

config.yaml

http_port: "3000"
http_base_url: "http://localhost:3000"
trusted_proxies:
  - "10.0.0.0/8"
  - "192.168.0.0/16"

db_driver: "postgres"
db_host: "localhost"
db_port: "5432"
db_username: "niksphere"
db_password: "secretpassword"
db_name: "nikspheredb"

idp_token_expiry_hours: "24"
idp_refresh_token_expiry_days: "30"

config.json

{
  "http_port": "3000",
  "http_base_url": "http://localhost:3000",
  "trusted_proxies": [
    "10.0.0.0/8",
    "192.168.0.0/16"
  ],
  "db_driver": "postgres",
  "db_host": "localhost",
  "db_port": "5432",
  "db_username": "niksphere",
  "db_password": "secretpassword",
  "db_name": "nikspheredb",
  "idp_token_expiry_hours": "24",
  "idp_refresh_token_expiry_days": "30"
}

config.toml

http_port = "3000"
http_base_url = "http://localhost:3000"
trusted_proxies = ["10.0.0.0/8", "192.168.0.0/16"]

db_driver = "postgres"
db_host = "localhost"
db_port = "5432"
db_username = "niksphere"
db_password = "secretpassword"
db_name = "nikspheredb"

idp_token_expiry_hours = "24"
idp_refresh_token_expiry_days = "30"

Related Documentation

• 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.