Instance Configuration Management#

LangBot's instance-level configuration lives in data/config.yaml and is managed through the ConfigManager class. It is the single source of truth for system-wide settings (API ports, database, concurrency, storage, plugins, etc.) — distinct from pipeline-level configuration stored in the database or adapter/plugin-specific config.

Boot Sequence#

LoadConfigStage is the first stage in the boot pipeline 1, running before logging, key generation, or any service initialization. The full stage order is:

1. LoadConfigStage — loads data/config.yaml, applies env overrides, resolves instance ID
2. GenKeysStage — generates JWT secret/recovery key if absent
3. SetupLoggerStage — initializes persistent logging
4. BuildAppStage — constructs all application components
5. ShowNotesStage — displays startup messages

How Config Is Loaded#

LoadConfigStage.run() calls config.load_yaml_config('data/config.yaml', 'config.yaml', completion=False), which is a convenience wrapper re-exported from bootutils/config.py 2. The real implementation is load_yaml_config in src/langbot/pkg/config/manager.py, which:

1. Creates a YAMLConfigFile instance backed by data/config.yaml.
2. Instantiates a ConfigManager and calls load_config() to read the file into ConfigManager.data (an in-memory dict).
3. Returns the ConfigManager instance, which is stored on ap.instance_config 3.

The loaded object is accessed everywhere as ap.instance_config.data[<key>] — for example, ap.instance_config.data['api']['port'] to read the HTTP port.

Environment Variable Overrides#

After loading the YAML file, _apply_env_overrides_to_config() is applied to ap.instance_config.data. Rules:

• Variable names must be all-uppercase and contain __ (double underscore) as the hierarchy separator.
• __ maps to nested YAML keys: CONCURRENCY__PIPELINE → concurrency.pipeline 4.
• Scalar types are coerced to match the existing value type (bool, int, float, or string) 5.
• List values accept comma-separated strings: SYSTEM__DISABLED_ADAPTERS="aiocqhttp,dingtalk" 6.
• Dict-type keys are skipped 7.
• Keys not present in the YAML are created as strings 8.

After overrides are applied, the config is written back to disk via ap.instance_config.dump_config(), which calls yaml.dump() with allow_unicode=True and 4-space indentation 9.

Instance ID Resolution#

LoadConfigStage resolves the instance ID with the following priority:

1. system.instance_id in config.yaml (settable via SYSTEM__INSTANCE_ID env var)
2. data/labels/instance_id.json (file-based persistence)
3. Auto-generated instance_<uuid>, saved to data/labels/instance_id.json

The resolved value is stored in constants.instance_id . constants.edition is read from system.edition (default: "community") 11.

ConfigManager Class#

ConfigManager (src/langbot/pkg/config/manager.py) is a thin wrapper over a ConfigFile implementation:

Key methods: load_config(completion=True) fills missing keys from a template; dump_config() / dump_config_sync() persist data back to disk 12.

The completion=False flag used during instance config loading means no automatic template backfill — the file is loaded as-is without merging defaults.

data/config.yaml Top-Level Sections#

The canonical template is at src/langbot/templates/config.yaml 13:

Key Source Files#