Modules - Config

Module configuration lives in config.yaml under the modules section. Each module gets its own namespace, accessed through ctx.config. The API handles reading, writing, and defaults.

Reading Config Values

Use ctx.config.get(key, default) to read a value:

greeting = ctx.config.get("greeting", "Hello!")
max_retries = ctx.config.get("max_retries", 3)

To get the entire config dict for a module:

all_config = ctx.config.as_dict()
# -> {"enabled": True, "greeting": "Hello!", "max_retries": 3}

Properties

Property	Type	Description
`ctx.config.enabled`	`bool`	Whether this module is enabled.
`ctx.config.public_base_url`	`str`	The bot's public base URL (from top-level config).

Registering Defaults

Call ctx.config.register_defaults() in an @on_setup function to declare what config keys a module expects and their default values:

from owlbot.api import ModuleContext, on_setup

@on_setup
async def setup(ctx: ModuleContext) -> None:
    ctx.config.register_defaults({
        "greeting": "Hello, {name}!",
        "cooldown": 30,
        "max_messages": 5,
    })

This does two important things:

Backfills to disk: Any keys in the defaults that aren't already in config.yaml get written to the file. This means all available options are visible in the config file after the module has run once. If the module does not have an entry in config.yaml yet, enabled: true is added automatically alongside the defaults.
Provides fallbacks: When ctx.config.get("greeting") is called, it checks the config file first, then falls back to the registered defaults.

Config file values always take precedence over defaults. If greeting: "Yo!" is set in the config, that value is returned by ctx.config.get("greeting"). The default is only used when the key is missing.

After the register_defaults() call above, config.yaml would look like this:

owlbot:
  # ...
owncast:
  # ...
modules:
  greeter:
    enabled: true
    greeting: "Hello, {name}!"
    cooldown: 30
    max_messages: 5

Modules are enabled by default. The enabled key is checked before loading the module. If set to false, the module is not imported.

Writing Config Values

Config values can be changed at runtime. Changes are persisted to disk immediately:

ctx.config.set("last_reset", "2024-01-15")

This updates both the in-memory config and the YAML file.

Built-in Modules

Creating New Modules