Configuration File

EnerOS uses a TOML-formatted eneros.toml as the main configuration file. This section provides a complete configuration example and details all sections and fields, along with advanced usage such as environment variable overrides, multi-environment configuration strategies, configuration validation, hot reload, and sensitive information management.

Complete Configuration Example

Below is a complete configuration example covering all sections:

# ============================================================
# EnerOS Main Configuration File
# ============================================================

[server]
host = "0.0.0.0"
port = 8080
workers = 4
max_connections = 10000
request_timeout_s = 30
cors_origins = ["*"]

[database]
path = "data/eneros.db"
journal_mode = "wal"
cache_size_mb = 256
migrate_on_start = true

[security]
tls_enabled = false
cert_path = "certs/server.crt"
key_path = "certs/server.key"
ca_path = "certs/ca.crt"
mtls_required = false
auth_token_ttl_minutes = 60

[agent]
max_agents = 100
default_memory_size = 1024
llm_endpoint = "http://localhost:11434"
llm_model = "eneros-llm-7b"
llm_timeout_s = 30
default_max_iterations = 20

[powerflow]
default_method = "newton-raphson"
tolerance = 1e-8
max_iterations = 20
flat_start = false
q_limit_check = true
tap_adjust = true

[topology]
auto_validate = true
strict_mode = false
cache_ttl_s = 300

[gateway]
enabled = false
listen_port = 8443
heartbeat_interval_ms = 1000
max_clients = 100

[timeseries]
retention_days = 365
batch_size = 1000
flush_interval_ms = 100
compression = "zstd"

[observability]
log_level = "info"
log_format = "json"
metrics_enabled = true
metrics_port = 9090
tracing_enabled = false
tracing_endpoint = "http://localhost:4317"

[multi_tenant]
enabled = false
default_tenant = "default"
isolation_mode = "schema"

[realtime]
enabled = false
priority = 80
cpu_affinity = [2, 3]
isolated_cpus = true

Configuration Item Details

[server] Server Configuration

Controls the API server’s listening and concurrency behavior.

[server]
host = "127.0.0.1"      # Local access only
port = 8080
workers = 8
max_connections = 50000
request_timeout_s = 60
cors_origins = ["https://eneros.example.com", "https://dashboard.example.com"]

[database] Database Configuration

Controls the SQLite kernel storage engine.

[database]
path = "/var/lib/eneros/data.db"
journal_mode = "wal"
cache_size_mb = 1024
migrate_on_start = true

[security] Security Configuration

Controls TLS, mTLS, and authentication.

[security]
tls_enabled = true
cert_path = "/etc/eneros/certs/server.crt"
key_path = "/etc/eneros/certs/server.key"
ca_path = "/etc/eneros/certs/ca.crt"
mtls_required = true
auth_token_ttl_minutes = 30

[agent] Agent Configuration

Controls the Agent runtime and LLM inference backend.

[agent]
max_agents = 200
default_memory_size = 2048
llm_endpoint = "http://gpu-node:11434"
llm_model = "eneros-llm-13b"
llm_timeout_s = 60
default_max_iterations = 50

[powerflow] Power Flow Calculation Configuration

Controls the default behavior of the power flow solver.

Available values for default_method:

[powerflow]
default_method = "newton-raphson"
tolerance = 1e-10
max_iterations = 50
flat_start = false
q_limit_check = true
tap_adjust = true

[topology] Topology Configuration

Controls grid topology analysis and caching.

[topology]
auto_validate = true
strict_mode = true
cache_ttl_s = 600

[gateway] Real-Time Safety Gateway Configuration

Controls the behavior of the real-time safety gateway (eneros-gateway).

[gateway]
enabled = true
listen_port = 8443
heartbeat_interval_ms = 500
max_clients = 500

[timeseries] Time-Series Storage Configuration

Controls the kernel time-series storage engine.

[timeseries]
retention_days = 730
batch_size = 5000
flush_interval_ms = 50
compression = "zstd"

[observability] Observability Configuration

Controls logging, metrics, and tracing.

[observability]
log_level = "debug"
log_format = "json"
metrics_enabled = true
metrics_port = 9090
tracing_enabled = true
tracing_endpoint = "http://otel-collector:4317"

[multi_tenant] Multi-Tenant Configuration

Controls the multi-tenant isolation strategy.

Available values for isolation_mode:

[multi_tenant]
enabled = true
default_tenant = "tenant_default"
isolation_mode = "schema"

[realtime] Real-Time Domain Configuration

Controls the real-time domain daemon (eneros-rt).

[realtime]
enabled = true
priority = 90
cpu_affinity = [2, 3]
isolated_cpus = true

Environment Variable Overrides

All configuration items can be overridden via environment variables, in the format ENEROS_ prefix + uppercase path (separated by underscores). Environment variables take precedence over the configuration file.

Naming Rules

Usage Examples

# Override a single configuration item
ENEROS_SERVER_PORT=9090 ./target/release/eneros-api

# Override multiple configuration items
ENEROS_SERVER_PORT=9090 \
ENEROS_DATABASE_PATH=/var/lib/eneros/data.db \
ENEROS_SECURITY_TLS_ENABLED=true \
ENEROS_OBSERVABILITY_LOG_LEVEL=debug \
./target/release/eneros-api

# Array types are comma-separated
ENEROS_SERVER_CORS_ORIGINS="https://a.com,https://b.com" \
./target/release/eneros-api

# Boolean values
ENEROS_SECURITY_MTLS_REQUIRED=true ./target/release/eneros-api

Use in Docker

docker run -d \
  -p 8080:8080 \
  -e ENEROS_SERVER_PORT=8080 \
  -e ENEROS_DATABASE_PATH=/var/lib/eneros/data.db \
  -e ENEROS_OBSERVABILITY_LOG_LEVEL=info \
  -v eneros-data:/var/lib/eneros \
  eneros:latest

Or in docker-compose.yml:

services:
  eneros-api:
    image: eneros:latest
    environment:
      - ENEROS_SERVER_PORT=8080
      - ENEROS_DATABASE_PATH=/var/lib/eneros/data.db
      - ENEROS_OBSERVABILITY_LOG_LEVEL=info

Use in systemd

[Service]
Environment="ENEROS_SERVER_PORT=8080"
Environment="ENEROS_DATABASE_PATH=/var/lib/eneros/data.db"
EnvironmentFile=/etc/eneros/env
ExecStart=/opt/eneros/bin/eneros-api

/etc/eneros/env file format:

ENEROS_OBSERVABILITY_LOG_LEVEL=info
ENEROS_SECURITY_TLS_ENABLED=true

Multi-Environment Configuration Strategy

EnerOS recommends maintaining separate configuration files for different environments.

Configuration File Naming Convention

eneros.toml            # Default (production)
eneros.dev.toml        # Development environment
eneros.test.toml       # Test environment
eneros.staging.toml    # Staging environment
eneros.prod.toml       # Production environment

Switch via Command Line

# Use development configuration
./target/release/eneros-api --config eneros.dev.toml

# Use production configuration
./target/release/eneros-api --config eneros.prod.toml

Development Environment Configuration Example (eneros.dev.toml)

[server]
host = "127.0.0.1"
port = 8080
workers = 2

[database]
path = "data/dev.db"
journal_mode = "memory"

[security]
tls_enabled = false

[agent]
max_agents = 10
llm_endpoint = "http://localhost:11434"

[observability]
log_level = "debug"
log_format = "text"

Production Environment Configuration Example (eneros.prod.toml)

[server]
host = "0.0.0.0"
port = 8080
workers = 16
max_connections = 50000

[database]
path = "/var/lib/eneros/prod.db"
journal_mode = "wal"
cache_size_mb = 2048

[security]
tls_enabled = true
cert_path = "/etc/eneros/certs/server.crt"
key_path = "/etc/eneros/certs/server.key"
mtls_required = true

[agent]
max_agents = 500
llm_endpoint = "http://gpu-cluster:11434"
llm_model = "eneros-llm-13b"

[observability]
log_level = "info"
log_format = "json"
metrics_enabled = true
tracing_enabled = true
tracing_endpoint = "http://otel-collector:4317"

Select Configuration via Environment Variable

You can select the configuration file based on the ENV variable in the startup script:

#!/bin/bash
ENV=${ENEROS_ENV:-dev}
exec ./target/release/eneros-api --config eneros.${ENV}.toml

Configuration Validation

EnerOS automatically validates the configuration file at startup. If any configuration item is invalid, it will refuse to start and output a detailed error.

Manual Validation

# Validate the configuration file
./target/release/eneros-api --config eneros.toml --check-config

# Output example:
# [OK] server.port: 8080
# [OK] database.path: data/eneros.db
# [WARN] security.tls_enabled: false (recommended to enable in production)
# [OK] agent.max_agents: 100
# [ERROR] powerflow.tolerance: -1 (must be positive)

Common Validation Errors

Hot Reload

EnerOS supports hot reload for some configuration items, taking effect without restarting the service.

Configuration Items Supporting Hot Reload

Trigger Hot Reload

# Trigger via SIGHUP signal
kill -HUP $(cat eneros.pid)

# Trigger via API
curl -X POST http://localhost:8080/api/v1/config/reload

# Via CLI
./target/release/enerosctl config reload

Hot Reload After Modifying Configuration File

# 1. Modify configuration
sed -i 's/log_level = "info"/log_level = "debug"/' eneros.toml

# 2. Send SIGHUP
kill -HUP $(cat eneros.pid)

# 3. Check logs to confirm
tail -f eneros.log
# Should see "Configuration reloaded: log_level=debug"

Configuration items that do not support hot reload (such as server.port, database.path, security.tls_enabled) require a service restart to take effect.

Sensitive Information Management

Avoid hardcoding passwords, API keys, and other sensitive information in configuration files.

Method 1: Environment Variables

[agent]
# Reference environment variables, not directly written
llm_endpoint = "${LLM_ENDPOINT}"
llm_api_key  = "${LLM_API_KEY}"

EnerOS automatically replaces ${VAR_NAME} placeholders with the corresponding environment variable values when loading the configuration.

Method 2: Secret Files

[security]
cert_path = "/etc/eneros/certs/server.crt"
key_path  = "/etc/eneros/secrets/server.key"

Set sensitive file permissions to 600:

chmod 600 /etc/eneros/secrets/server.key
chown eneros:eneros /etc/eneros/secrets/server.key

Method 3: External Key Management

Integrate with HashiCorp Vault, AWS Secrets Manager, etc.:

[secrets]
provider = "vault"
vault_endpoint = "https://vault.example.com:8200"
vault_path = "secret/eneros"
# Pass token via VAULT_TOKEN environment variable

Sensitive Information Checklist

• Configuration file contains no plaintext passwords
• Configuration file permissions are 600, owned by eneros
• Key files are not in version control
• Environment variables or key management services are used
• TLS is enabled in production
• .gitignore includes *.toml, *.key, *.crt

# Set configuration file permissions
chmod 600 eneros.toml
chown eneros:eneros eneros.toml

# Confirm .gitignore contains sensitive files
echo "eneros.prod.toml" >> .gitignore
echo "*.key" >> .gitignore
echo "*.crt" >> .gitignore

Next Steps

• Introduction to EnerOS - Review core concepts
• First Agent - Create and run an Agent