Engine Configuration Concept

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

Configuration Sources

• Configuration File — A single config.yaml, config.json, or config.toml file holding all settings as key/value pairs. Either passed explicitly via --config <path>, or auto-discovered by the Engine — see Configuration File below.
• Environment Variables — Any configuration key can also be supplied as an environment variable using the NIKSPHERE_ENGINE_ prefix. This is the preferred approach for containerized deployments (Docker, Kubernetes) where mounting a config file is impractical — see Environment Variables below.

Configuration File

If --config <path> is not provided, the Engine automatically searches for a file named config (with a .yaml, .json, or .toml extension) in the following locations, in order, and loads the first one it finds:

1. User config directory (OS-specific — one of three Standard Directories the Engine resolves, alongside State and Cache):
   • Windows: %APPDATA%\Niksphere\Engine\
   • macOS: ~/Library/Application Support/Niksphere/Engine/
   • Linux: $XDG_CONFIG_HOME/niksphere/Engine/ (defaults to ~/.config/niksphere/Engine/)
2. System-wide directory:
   • Windows: %PROGRAMDATA%\Niksphere\Engine\
   • Linux / macOS: /etc/niksphere/engine/
3. The Engine executable's own directory
4. The current working directory

Passing --config <path> (or -c <path>) skips this search entirely and loads exactly the given file instead.

Example

Any one of the following (matched by file extension) works — place it in one of the locations above, e.g. ~/.config/niksphere/Engine/config.yaml on Linux:

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"

Environment Variables

Every configuration key can also be supplied as an environment variable. The Engine uppercases the key and prefixes it with NIKSPHERE_ENGINE_ — for example, the db_host key becomes NIKSPHERE_ENGINE_DB_HOST.

Example

# 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

Configuration Precedence

When the same setting is supplied through more than one source, the Engine resolves it 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

In practice, this means an environment variable overrides the same key set in a configuration file, and pointing --config at a different file changes which file is consulted in the first place.

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.
• Standard Directories Concept — The Config directory above is one of three OS-standard directories (Config/State/Cache) the Engine resolves.