3.2 Configuration Reference DaemonConfig

Configuration Reference (DaemonConfig)

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• src/daemon.rs

The DaemonConfig struct defines the schema for the brainstem-daemon configuration file. This TOML-based configuration controls the Spiking Neural Network (SNN) dimensions, execution frequency, runtime mode, logging verbosity, bounded ingress limits, and networking parameters for the ZeroMQ-based "Spine" interface and control surface.

Purpose and Scope

The configuration serves as the source of truth for the BrainstemDaemon runtime src/daemon.rs:51-78. It is loaded during the initialization phase in the binary entry point and validated before the tick loop begins to ensure hardware and memory constraints are respected.

Sources: src/daemon.rs:51-78

---

TOML Schema Definition

The following table documents every field within the DaemonConfig struct src/daemon.rs:51-78.

Field	Type	Description
runtime_mode	RuntimeMode	Execution mode: live (requires Distill sidecar snn_model.json) or simulation (blank network) src/daemon.rs:40-48
lif_count	usize	Number of Leaky Integrate-and-Fire neurons in the network src/daemon.rs:58
izh_count	usize	Number of Izhikevich neurons in the network src/daemon.rs:59
channels	usize	Number of input stimulus channels (synaptic inputs) src/daemon.rs:60
tick_rate_hz	u32	The frequency of the simulation loop (e.g., 1000 for 1ms steps) src/daemon.rs:53
log_level	String	Tracing filter level (e.g., "info", "debug", "warn") src/daemon.rs:54
control_bind	Option<String>	Optional ip:port for the process control surface (/livez, /readyz, /health, /metrics) src/daemon.rs:77
spine_sub_port	u16	TCP port for the Subscriber socket (Ingress stimulus) src/daemon.rs:55
spine_pub_port	u16	TCP port for the Publisher socket (Egress spikes) src/daemon.rs:56
model_path	PathBuf	Path to the Distill sidecar snn_model.json model weights file src/daemon.rs:57
services	Vec<ServiceConfig>	Optional list of registry-managed services src/daemon.rs:65
ingress	IngressConfig	Bounded per-class ingress parameters and limits src/daemon.rs:71

Sources: src/daemon.rs:40-78

---

Validation Rules

The daemon performs several safety checks during DaemonConfig::load and BrainstemDaemon::try_with_backend.

1. Neuron Count Limit

The total number of neurons (lif_count + izh_count) must not exceed u16::MAX (65,535) src/daemon.rs:166. This is enforced to ensure compatibility with internal indexing logic.

• Logic: If lif_count + izh_count > 65535, validation returns an error, preventing runtime integer overflow or indexing panics.

2. Path Safety Checks

To prevent directory traversal attacks when loading configurations, the load function rejects absolute paths containing parent-directory components (e.g., /etc/../brainstem/daemon.toml) src/daemon.rs:86-95.

• Logic: path.is_absolute() && path.components().any(|c| c == Component::ParentDir) triggers an immediate bail src/daemon.rs:86-95.

3. Ingress and Tick Validation

The configuration invokes ingress validation (config.ingress.validate()) during daemon construction src/daemon.rs:168 to ensure queue limits, timeout bounds, and overflow policies are well-formed.

Sources: src/daemon.rs:86-95, src/daemon.rs:166-168

---

Data Flow: Config to Runtime

The following diagram illustrates how the DaemonConfig values are distributed across the system components during initialization.

Configuration Distribution Map

graph TD
    subgraph "Configuration Space (TOML)"
        CFG["DaemonConfig"]
    end

    subgraph "Code Entity Space"
        BIN["brainstem-daemon (bin)"]
        BD["BrainstemDaemon (struct)"]
        SN["SpikingNetwork (neuromod)"]
        ZMQ_SRC["ZmqStimulusSource"]
        ZMQ_SNK["ZmqSpikeSink"]
        REG["ServiceRegistry"]
        ING["BoundedIngress"]
    end

    CFG -- "lif_count, izh_count, channels" --> SN
    CFG -- "tick_rate_hz, runtime_mode" --> BD
    CFG -- "log_level" --> BIN
    CFG -- "spine_sub_port, model_path" --> ZMQ_SRC
    CFG -- "spine_pub_port" --> ZMQ_SNK
    CFG -- "services (Vec)" --> REG
    CFG -- "ingress" --> ING

    BIN -- "calls DaemonConfig::load()" --> CFG
    BIN -- "calls BrainstemDaemon::try_with_backend()" --> BD

Loading

Sources: src/daemon.rs:51-78, src/daemon.rs:118-124

---

Minimal Working Example

A standard configuration file for a local development environment using the default spine ports and live runtime mode.

# ~/.config/soma/daemon.toml
runtime_mode   = "live"
lif_count      = 16
izh_count      = 0
channels       = 16
tick_rate_hz   = 1000
log_level      = "info"
control_bind   = "127.0.0.1:9090"
spine_sub_port = 5555
spine_pub_port = 5556
model_path     = "/var/lib/soma/snn_model.json"

[ingress]
# Optional ingress overrides (defaults apply if omitted)

[[services]]
name    = "telemetry"
enabled = true

[[services]]
name    = "critic-ipc"
enabled = true

Loading Logic

The binary attempts to find configuration files in the standard platform configuration directory (e.g., ~/.config/soma/daemon.toml on Linux) via platform-dependent directory resolution. If the --config flag is provided via CLI, it overrides this default.

Sources: src/daemon.rs:80-101, AGENTS.md:70-94

---

Implementation Details

Initialization Pipeline

The conversion from DaemonConfig to a running BrainstemDaemon involves validation and registry setup.

sequenceDiagram
    participant Main as "brainstem_daemon (bin)"
    participant Config as "DaemonConfig (src/daemon.rs)"
    participant Registry as "ServiceRegistry (src/registry.rs)"
    participant Daemon as "BrainstemDaemon (src/daemon.rs)"

    Main->>Config: "load(path)"
    Config-->>Main: "Ok(cfg)"
    Main->>Daemon: "try_with_backend(cfg, backend)"
    Note over Daemon: "validate_neuron_count(&config)"
    Daemon->>Registry: "from_configs(config.services)"
    Registry-->>Daemon: "registry"
    Daemon-->>Main: "Ok(daemon)"

Loading

Registry Ownership

The DaemonConfig.services vector is consumed during daemon construction src/daemon.rs:65, transferring ownership into the ServiceRegistry while the BrainstemDaemon retains the primary configuration fields required to drive the tick loop src/daemon.rs:118-124.

Sources: src/daemon.rs:51-78, src/daemon.rs:118-124