Configuration Reference

NeuroSim Core is configured via a YAML file specified on the Core command line with --config=<file>. All settings have built-in defaults and you can also supply any value as an environment variable so the config file is optional.

Loading Order

Values are resolved in this priority order (highest wins):

1. Environment variables — always take precedence
2. Config file values — override defaults when a file is supplied
3. Built-in defaults — used when no file or environment variable is present

Environment Variable Mapping

Environment variable names are derived from the YAML key path by replacing dots with underscores and uppercasing. For example:

Complete Example

http:
  port: "8080"
  sse_keepalive: 20
  serve_ui: true

kafka:
  brokers: localhost:9092
  register_topic: neurosim-plugins
  event_topic: neurosim-events

store_type: postgresql
postgresql:
  dsn: postgres://neurosim:changeme@localhost:5432/neurosim

license_file_path: /etc/neurosim/license.jwt

schemapath: ./schemas

Reference

http

http.port

The TCP port the HTTP server listens on. Serves both the REST API and the embedded web UI.

http.sse_keepalive

How often (in seconds) Core sends a comment keepalive on Server-Sent Events (SSE) connections. This prevents proxies and load balancers from closing idle streaming connections. Increase this value if your infrastructure has longer idle timeouts; decrease it if connections drop unexpectedly.

http.serve_ui

When true, the embedded React web UI is served at /. Set to false if you are running Core purely as an API server and do not wish to make the UI available.

kafka

kafka.brokers

Comma-separated list of Kafka broker addresses. For a multi-broker cluster, list all brokers:

kafka:
  brokers: kafka1:9092,kafka2:9092,kafka3:9092

Core only needs to reach one broker to bootstrap — it will discover the rest from the cluster metadata.

kafka.register_topic

The Kafka topic where plugins publish their registration heartbeats. This topic should be configured with cleanup.policy=compact (log compaction) so that Core can reconstruct the current set of registered plugins on startup. See Prerequisites — Topic Configuration.

All plugins operating with this Core instance must use the same registration topic name.

kafka.event_topic

The orchestration topic for plugins to send scenario responses and status messages to.

store_type

Controls where scenario definitions and run history are persisted.

• memory — data is held in process memory. All definitions and run history are lost when Core restarts. Suitable for development and evaluation.
• postgresql — data is persisted to PostgreSQL. Scenario definitions, run records, event statistics, and timing data survive restarts. Required for any production deployment.

postgresql

Only used when store_type: postgresql.

postgresql.dsn

PostgreSQL connection string in DSN format:

postgres://<user>:<password>@<host>:<port>/<database>

Additional PostgreSQL connection parameters can be appended as query string parameters per the libpq connection string format:

postgresql:
  dsn: postgres://neurosim:changeme@localhost:5432/neurosim?sslmode=require&connect_timeout=10

Security note: Avoid placing the DSN value directly in a config file that is committed to version control. Use the POSTGRESQL_DSN environment variable or a secrets manager to inject it at runtime.

Core automatically applies any pending schema migrations on startup. The database user must have CREATE TABLE and CREATE INDEX privileges on the target database for migrations to succeed.

license_file_path

Absolute or relative path to the NeuroSim license JWT file. Core reads and validates this file at startup, then re-checks it every hour. If the license is absent, expired, or invalid, Core will not run.

Use an absolute path in production to avoid ambiguity about the working directory:

license_file_path: /etc/neurosim/license.jwt

The license file is issued and supplied by NeuroSim sales support.

schemapath

Path to a directory containing JSON schema files defining the valid form of NeuroSim Core's orchestration messages. This directory is bundled inside the Docker image at /app/schemas and does not normally need to be changed.

If you are running the binary directly, ensure this path points to the schemas/ directory that ships alongside the binary.

Minimal Production Config

The smallest valid config file for a production deployment:

http:
  port: "8080"

kafka:
  brokers: kafka1:9092,kafka2:9092
  register_topic: neurosim-plugins
  event_topic: neurosim-events

store_type: postgresql

license_file_path: /etc/neurosim/license.jwt

Supply POSTGRESQL_DSN as an environment variable to keep credentials out of the config file.